Hinweise zur Dokumentation

Diese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs- und Automatisierungstechnik, das mit den geltenden nationalen Normen vertraut ist.
Zur Installation und Inbetriebnahme der Komponenten ist die Beachtung der Dokumentation und der nachfolgenden Hinweise und Erklärungen unbedingt notwendig.
Das Fachpersonal ist verpflichtet, für jede Installation und Inbetriebnahme die zu dem Zeitpunkt veröffentlichte Dokumentation zu verwenden.

Das Fachpersonal hat sicherzustellen, dass die Anwendung bzw. der Einsatz der beschriebenen Produkte alle Sicherheitsanforderungen, einschließlich sämtlicher anwendbaren Gesetze, Vorschriften, Bestimmungen und Normen erfüllt.

Disclaimer

Diese Dokumentation wurde sorgfältig erstellt. Die beschriebenen Produkte werden jedoch ständig weiter entwickelt.
Wir behalten uns das Recht vor, die Dokumentation jederzeit und ohne Ankündigung zu überarbeiten und zu ändern.
Aus den Angaben, Abbildungen und Beschreibungen in dieser Dokumentation können keine Ansprüche auf Änderung bereits gelieferter Produkte geltend gemacht werden.

Marken

Beckhoff®, TwinCAT®, EtherCAT®, EtherCAT G®, EtherCAT G10®, EtherCAT P®, Safety over EtherCAT®, TwinSAFE®, XFC®, XTS® und XPlanar® sind eingetragene und lizenzierte Marken der Beckhoff Automation GmbH.
Die Verwendung anderer in dieser Dokumentation enthaltenen Marken oder Kennzeichen durch Dritte kann zu einer Verletzung von Rechten der Inhaber der entsprechenden Bezeichnungen führen.

Patente

Die EtherCAT Technologie ist patentrechtlich geschützt, insbesondere durch folgende Anmeldungen und Patente:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
mit den entsprechenden Anmeldungen und Eintragungen in verschiedenen anderen Ländern.

EtherCAT® ist eine eingetragene Marke und patentierte Technologie lizenziert durch die Beckhoff Automation GmbH, Deutschland.

Copyright

© Beckhoff Automation GmbH & Co. KG, Deutschland.
Weitergabe sowie Vervielfältigung dieses Dokuments, Verwertung und Mitteilung seines Inhalts sind verboten, soweit nicht ausdrücklich gestattet.
Zuwiderhandlungen verpflichten zu Schadenersatz. Alle Rechte für den Fall der Patent-, Gebrauchsmuster- oder Geschmacksmustereintragung vorbehalten.


TwinCAT ADS WebService : Einleitung

TwinCAT ADS Web Service

Einleitung

Der ADS-WebService bietet die Möglichkeit, die ADS Kommunikation via HTTP auch durch Firewalls zu leiten.
Eine ADS Kommunikation durch das Internet für Diagnose- und Visualisierungszwecke ist somit möglich.

Voraussetzung :

  • PC mit TwinCAT auf Windows XP/7/8 oder Windows CE System mit IIS (Microsoft Internet Information Server)

Installation des Webservices und Beispielprogramme:

  • Einrichten unter Windows 7/8
  • Einrichten unter Windows XP
  • Einrichten unter Windows CE
  • ADS Webservice Beispiele


TwinCAT ADS WebService : Installation Windows 7

TwinCAT ADS Web service

Install TwinCAT ADS Webservice on a PC (here: Windows 7)

This chapter describes the IIS configuration required for the TwinCAT ADS Webservice running on Windows 7. (Please note: The configuration can differ for other Windows operating systems).

Requirements :

The TwinCAT ADS Webservice is delivered by the default TwinCAT installation. This chapter describes how to configure Internet Information Service 7.

Step 1: Installing IIS7

By default, IIS7 is not part of the Windows 7 installation. Therefore you need to add this functionality manually. For more information see http://technet.microsoft.com/de-de/library/cc725762%28v=ws.10%29.aspx

Please note: When installing IIS7, the following extensions need to be activated:

  • ISAPI Extensions
  • ISAPI Filters

Step 2: Create "Virtual Directory" in IIS7 (Internet Information Service)

Usually this step will be performed automatically by the Setup.

  • Open "Internet Information Service (IIS) Manager" which can be found under "Control Panel\Administrative Tools\"
  • Right click on "Default Web Site"
  • Select "Add Virtual Directory..."
  • Please enter the alias "TcAdsWebService" and the physical path to your TwinCAT ADS Webservice installation

    For TwinCAT2 use C:\TwinCAT\ADS Api\TcAdsWebService\100\xp

    For TwinCAT3 use C:\TwinCAT3\AdsApi\TcAdsWebService\100\xp

  • Click on "OK"

  • Double-click the "Authentication" icon, select "Anonymous Authentication" and click on "Edit". Instead of specifying a user account, select the "Application pool identity" and click on "Ok".

  • Next, you need to set execute permissions on that virtual directory. Select the added directory and double-click on "Handler Mappings"

  • Click on "Edit Feature Permissions" and select the "Execute" permission. Click on "OK".

  • As a next step you need to create an ISAPI allowance. Please select the root node in IIS Manager (named after your computername) and then double-click "ISAPI and CGI Restrictions".
  • Click on "Add" to create a new enabled extensions. In the "ISAPI or CGI path" textbox, please specify the path to TcAdsWebService.dll:

Path for TwinCAT2: C:\TwinCAT\ADS Api\TcAdsWebService\100\xp

Path for TwinCAT3: C:\TwinCAT3\AdsApi\TcAdsWebService\100\xp

  • Also select the checkbox "Allow extension path to execute".

  • Restart your IIS.

Please note: If you use Windows 7 64-bit, you need to explicitely enable 32-bit ISAPI-DLLs in IIS. In this case, please perform the following steps:

  • Open "Internet Information Service (IIS) Manager" which can be found under "Control Panel\Administrative Tools\"
  • Click on "Application Pools"
  • Select the "DefaultAppPool" and click on "Advanced Settings..." from the Actions panel
  • Set the entry "Enable 32-bit Applications" to "True", then click on "OK" to commit the changes

Step 3: Testing TwinCAT ADS Webservice configuration

The URL of the TwinCAT ADS Webservice on the PC system can be accessed locally or from a remote computer. In both cases, open the web browser (e.g. Internet explorer) and enter the URL of the TwinCAT ADS Webservice, for example:

http://<ip-adress or name of PC device>/tcadswebservice/tcadswebservice.dll

Examples:

http://192.168.0.1/tcadswebservice/tcadswebservice.dll
http://localhost/tcadswebservice/tcadswebservice.dll

The TwinCAT ADS Webservice will reply with a status page containing the portnr and netid. If you see this page, the installation and configuration of the ADS Webservice has been successful.

HINT :

In case of problems (like receiving no HTML status data) please check if your system uses a proxy server.
After deactivating the proxy and reloading the URL, the TwinCAT ADS Webservice should reply with the status info above.


TwinCAT ADS WebService : Konfiguration unter Windows XP

Einrichten des TwinCAT ADS WebServices auf einem PC (hier: Windows XP)

Notwendige Komponenten und Dateien:

Die benötigten Komponenten für den ADS-WebService werden installiert mit :
  • einer aktuellen TwinCAT Installation (z.B. TwinCAT 2.10 Build 1246 )
  • Einer separaten Installation TwinCAT ADS Communication Library (ohne TwinCAT)

Zum Einrichten des TwinCAT ADS WebServices benötigen Sie folgende Dateien (normalerweise zu finden unter C:\TwinCAT\ADS Api\TcAdsWebService\V100\XP\):
  • TcAdsWebService.dll
  • TcAdsSoap.dll
  • TcAdsWebService.WSDL

Einrichten des ADS-WebService unter dem Betriebssystem XP

Auf anderen Windows-Betriebssystemen kann die Konfiguration in Details abweichen.
Neues Virtual Directory im IIS (Internet Information Service) anlegen:
  • Öffnen Sie die Internet Information Services (unter Control Panel/Administrative Tools/ bzw. Systemsteuerung/Verwaltung/).
  • Klicken Sie in der Baumansicht mit der rechten Maustaste auf Default Web Site.
  • Wählen Sie New/Virtual Directory... aus.

Klicken Sie im folgenden Fenster auf Next.

Geben Sie unter Alias TcAdsWebService ein und klicken Sie auf Next.

Geben Sie unter Directory den Pfad des TwinCAT ADS Web Services an (normalerweise C:\TwinCAT\ADS Api\TcAdsWebService\V100\xp\). Verwenden Sie ggf. die Browse...-Funktion, um diesen Ordner auszuwählen.
Klicken Sie danach auf Next.

Wählen Sie Read, Run scripts und Execute aus und klicken Sie Next.

Klicken Sie Finish um das Einrichten des TwinCAT ADS Web Services abzuschließen.

Die Konfiguration ist abgeschlossen. Der ADS WebService steht nun zur Verfügung.


TwinCAT ADS WebService : Konfiguration unter Windows CE

Einrichten des TwinCAT ADS WebServices unter Windows CE

Notwendige Komponenten und Dateien:

Die benötigten Komponenten für den ADS-WebService werden installiert mit :
  • einer aktuellen TwinCAT Installation (z.B. TwinCAT 2.10 Build 1246 )
  • Einer separaten Installation TwinCAT ADS Communication Library (ohne TwinCAT)

Zum Einrichten des TwinCAT ADS WebServices benötigen Sie folgende Dateien (normalerweise zu finden unter C:\TwinCAT\ADS Api\TcAdsWebService\V100\ce\):
  • TcAdsWebService.dll
  • TcAdsSoap.dll
  • TcAdsWebService.WSDL

Einrichten des ADS-WebService unter dem Betriebssystem CE

Legen Sie auf dem BECKHOFF-CE Gerät (z.B. CX1001) unter \hard disk\www\ ein neues Verzeichnis mit dem Namen TcAdsWebService an.

Kopieren Sie anschließend die drei Dateien TcAdsWebService.dll, TcAdsSoap.dll und TcAdsWebService.WSDL hinein.

Die Konfiguration ist damit abgeschlossen.


TwinCAT ADS WebService : Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows 7

Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows 7

SSL/TLS Configuration

Rightclick on the Computer button in the Windows 7 Startmenu and press Manage to open the "Computer Management" window.

If you need a certificate for development or intranet use only, you can generate a self signed certificate based on the computer name, directly in the Internet Information services by following the next steps here.

If you already have a server certificate which you want to use you can follow the next steps here.

If you want to create a self signed certificate for a domain in the world wide web, you can generate it with the SSLCert.exe.
If you have created a certificate with the SSLCert.exe you can follow the next steps here.

Creating a self signed certificate for development use

In the Computer Management Window navigate to "Services and Applications"->"Internet Information Servicess (IIS) Manager" and click on the root node of the Internet Information Services Manager navigation.

In the content pane of the Internet Information Services Manager choose the "Server Certificates" icon and double click on it.

Click on the "Create Self-Signed Certificate..." menu entry in the Actions pane of the "Server Certificates" window.

In the opened dialog you have to specify a friendly name for your certificate. After that press the OK button to confirm.

The certificate was added to the certificate store of your computer and is displayed in the list of available Server certificates in the "Server certificates" window of the IIS Manager.

You can double click on the new entry to open the certificate information dialog for further information about the certificate.

HTTPS Binding

Now mark the website node in the Internet Information Services Manager navigation which contains the virtual directory for the TcAdsWebService and click on the "Bindings..." menu point in the appropriate Actions pane.

Now we have to create a binding for the https protocol. Press the "Add" button to open the "Add Site Binding" dialog.

In the "Add Site Binding" dialog, choose the following values to create a binding for the https protocol.

A bining for the https protocol is now available in the "Site Bindings" dialog.

Now you can connect to all virtual directories of your website over the http and the https protocol.

Follow the next steps, if you want to allow connection over the https protocol only.

Navigate to the TcAdsWebService virutal directory and open the "SSL/TLS Settings" window.

In the "SSL Settings" dialog check the "Require SSL" checkbox.

The Internet Information Services will now only allow connections over the https protocol.

NTLM Authentication

Rightclick on the "Computer" button in the Windows 7 Startmenu und press "Manage" to open the Computer Management Window.

Choose the virual directory node of the TcAdsWebService in the Internet Information Services Manageer navigation.

Open the Authentication dialog for the TcAdsWebService virual directory.

Enable "Windows Authentication" and disable all other authentication methods.

NTLM is now active and required for the TcAdsWebService.


TwinCAT ADS WebService : Configuration on Windows Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows XPC

TwinCAT ADS Web Service : Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows XP

Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows XP

SSL/TLS Configuration

Rightclick on the "My Computer" button in the Windows XP Startmenu and press Manage to open the "Computer Management" window.

In the Computer Management window expand the "Internet Information Services" node and perform a right click on the "Default Web Site" node.
Click on "Properties" in the context menu.

In the "Web Site Properties" window choose the "Directory Security" tab and press the "Server Certificate" button below the "Secure communications" section.

Press the "Next" button on the first dialog of the "Web Server Certificate Wizard" window.

Choose "Assign an existing certificate" and press "Next".

Select your server certificate from the list and press "Next".

If you dont have a valid server certificate you can generate a self-signed certificate with SSLCert.exe.

All virtual directories below the "Default Web Site" node are now available over the https protocol.

NTLM Authentication

Choose the virtual directory node of the TcAdsWebService and right click on it.
In the context menu press "Properties" to open the "Properties" window.

In the "Properties" window choose the "Directory Security" tab and press the "Edit" button below the "Anonymois access and authentication control" section.

The default setting for websites in the Internet Information Services is "Anonymous Access".
To enable NTLM authentication you have to uncheck the "Anonymous access" checkbox and check the "Integrated Windows authentication" checkbox.

NTLM is now activated and required for the TcAdsWebService.


TwinCAT ADS WebService : Configuration on Windows CE

Configuration of SSL/TLS and NTLM Authentification for the TwinCAT ADS WebServices on Windows CE

SSL/TLS Configuration

  • In the registry create a subkey named SSL/TLS below /HKEY_LOCAL_MACHINE/Comm/HTTPD/ registry key.
  • Create the following values in /HKEY_LOCAL_MACHINE/Comm/HTTPD/SSL/TLS/
    • IsEnabled
      • Type: DWORD
      • Value: 0x00000001
    • CertificateSubject
      • Type: STRING
      • Value: <Subject value of the certificate in certificate store which should be used for SSL/TLS>
  • Restart the HTTPD WebServer with the following console command: services refresh htp0:

Generating a self signed certificate with SSLCert.exe.

The tool is provided with the ADS API under \TWINCATDIR\ADS Api\TcAdsWebService\SSLCert.

NTLM Authentication

  • The value NTLM in registry key /HKEY_LOCAL_MACHINE/Comm/HTTPD/ has to be set to 0x00000001 to enable NTLM Authentication for the HTTPD WebServer.
  • In the /HKEY_LOCAL_MACHINE/Comm/HTTPD/VROOTS/ subkey for your website, or in the subkey named / if you have placed your website under \HARD DISK\www\ the value a has to be set to 0x00000001.
  • Restart the HTTPD WebServer with the following console command: services refresh htp0:


SSLCert.exe

SSLCert.exe

SSLCert is a console application which can be used to create self-signed certificates for SSL encoding.

Usage: SSLCert.exe DOMAINNAME

Parameters

DOMAINNAME

The name of the domain which should be secured by SSL.

Example 1

If a web resource should be reachable over the url http://www.beckhoff.com/webui/ you have to use the following command to create a certificate with SSLCert:

SSLCert.exe www.beckhoff.com

This will generate a certificate with the common name www.beckhoff.com in the certificate store which can be used for SSL encoding. And a www.beckhoff.com.cer file in the working directory of the SSLCert application which can be exported on a client system as trusted root authority.

Anyway some browsers may not trust such a certificate because its self signed.

Example 2

If a web resource should be reachable over the url http://beckhoff.com/webui/ you have to use the following command to create a certificate with SSLCert:

SSLCert.exe beckhoff.com

This will generate a certificate with the common name beckhoff.com in the certificate store which can be used for SSL encoding. And a beckhoff.com.cer file in the working directory of the SSLCert application which can be exported on a client system as trusted root authority.

Anyway some browsers may not trust such a certificate because its self signed.

Example 3

If a web resource should be reachable over the url http://192.168.1.1/webui/ you have to use the following command to create a certificate with SSLCert:

SSLCert.exe 192.168.1.1

This will generate a certificate with the common name 192.168.1.1 in the certificate store which can be used for SSL encoding. And a 192.168.1.1.cer file in the working directory of the SSLCert application which can be exported on a client system as trusted root authority.

Anyway some browsers may not trust such a certificate because its self signed.

Important:

SSLCert.exe has to be used with the "Administrator" account.
Another account does not have the required privileges to add a certificate to the system certificate store. Even if its part of the "Administrators" group.