Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


TwinCAT ADS WebService : Introduction

TwinCAT ADS Web Service

Introduction

In this document the "ADS Communication via WebService" is described.
The ADS-WebService enables the possibility to set up an ADS communication via HTTP through a firewall.
Now it is possible to use an ADS communication via internet for diagnosis and visualisation.

Prerequisites :

  • PC with TwinCAT on Windows XP/7/8 or Windows CE System with IIS (Microsoft Internet Information Server)

  • Configuration for Windows CE
  • Configuration for Windows XP
  • ADS Webservice samples


TwinCAT ADS WebService : Configuration on Windows XP

Configuration of the TwinCAT ADS WebServices on a PC (in this example: Windows XP)

The required components for the ADS-WebService are comming with installation of :

  • current TwinACT Installation (e.g. TwinCAT 2.10 Build 1246 )
  • a seperat installation (without TwinCAT) "TwinCAT ADS Communication Library"

necessary files:

To set up the TwinCAT ADS WebService the following files are needed (can be found in "C:\TwinCAT\ADS Api\TcAdsWebService\V100\xp\"):

  • TcAdsWebService.dll
  • TcAdsSoap.dll
  • TcAdsWebService.WSDL

This example explains the configuration on Windows XP. On other windows operation systems this configuration may differ in some aspects.

Creation of a new "Virtual Directory" in the IIS (Internet Information Service)

  • Open the "Internet Information Services" (in "Control Panel/Administrative Tools/").
  • Right-click in the tree-view on the righthand side on "Default Web Site".
  • Select "New/Virtual Directory...".

Click "Next".

Insert "TcAdsWebService" as the alias and click "Next".

Insert the directory of the TwinCAT ADS Web Services (usually "C:\TwinCAT\ADS Api\TcAdsWebService\V100\xp\"). You can use the "Browse..."-Button to find this folder.

After that click the "Next"-button.

Check "Read", "Run scripts" and "Execute" and click "Next".

To complete the configuration of the TwinCAT ADS Web Service click "Finish".

Ready. The ADS WebService is now fully operational.


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 : Configuration on Windows CE

Configuration of the TwinCAT ADS WebServices on Windows CE

The necessary components for the ADS-Webservice installed with:

  • current TwinACT Installation (e.g. TwinCAT 2.10 Build 1246 )
  • a seperat installation (without TwinCAT) "TwinCAT ADS Communication Library"

necessary files:

To set up the TwinCAT ADS WebService the following files are needed (can be found in "C:\TwinCAT\ADS Api\TcAdsWebService\V100\ce\"):

  • TcAdsWebService.dll
  • TcAdsSoap.dll
  • TcAdsWebService.WSDL

Create a new folder in "\hard disk\www\" with the name "TcAdsWebService" on your BECKHOFF-CE-Device (e.g. CX1001) and copy the 3 files mentioned above to this folder.

The configuration is completed.


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 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.


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.