Configuration file

The TwinCAT ADS router is configured by an XML file to establish an ADS-over-MQTT connection with a message broker. This configuration file is stored under any name in the following directory:

\TwinCAT\3.1\Target\Routes

In the Samples chapter, you will find sample configuration files for all the use cases described below.

Configuration file 1:

Activating a new ADS-over-MQTT configuration

New or changed ADS-over-MQTT configurations are only adopted when the TwinCAT ADS router is initialized. This takes place, for example, in the TwinCAT transitions from RUN to CONFIG or CONFIG to CONFIG.

Configuration file 2:

Path information

Please ensure that you use the correct spelling for your operating system for any path details in the configuration file.

Basic configuration

The basic configuration always contains the following elements:
Address of the message broker, its TCP port and the name of the virtual network.
The address of the broker and the TCP port at which it can be reached are specified via the <Address> node. The virtual network is defined via the <Topic> node. In the following example, a connection is established to a locally (127.0.0.1) installed message broker and TCP port 1883. "VirtualAmsNetwork1" is defined as the virtual network".

<?xml version="1.0" encoding="ISO-8859-1"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.beckhoff.com/schemas/2015/12/TcConfig">
 <RemoteConnections>
  <Mqtt>
   <Address Port="1883">127.0.0.1</Address>
   <Topic>VirtualAmsNetwork1</Topic>
  </Mqtt>
 </RemoteConnections>
</TcConfig>

NoRetain

The communication flow for device discovery can be customized via the NoRetain attribute. By setting NoRetain = true, the device search function is no longer based on retain messages. Instead, a handshake mechanism is used to identify all connected ADS devices.

Configuration file 3:

Unidirectional

Incoming ADS messages can be blocked for this system via the unidirectional attribute. A typical use case could be an engineering system, for example, which should be able to reach the runtime systems via ADS, but not vice versa.

Configuration file 4:

TLS

The <TLS> node can be used to define settings for securing the transport channel via TLS. Various connection options are available, e.g. the configuration of client certificates or PSK. Our samples show all possible configuration variants.

TLS IgnoreCn

The IgnoreCn attribute can be used to disable the verification of the CommonName (CN) from the server certificate.

Configuration file 5:

TLS PSK

When using TLS with a Pre-Shared Key (PSK), you can either specify the PSK as a hex-coded, 64-character string, or leave the conversion to TwinCAT internally using Sha256(Identity + Pwd). In the latter case, the IdentityCaseSensitive attribute can be used to specify that TwinCAT should use the identity as the UpperCase for the calculation. Our samples show both possible configuration variants.

User

<?xml version="1.0" encoding="ISO-8859-1"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.beckhoff.com/schemas/2015/12/TcConfig">
 <RemoteConnections>
  <Mqtt>
   <Address Port="1883">127.0.0.1</Address>
   <Topic>VirtualAmsNetwork1</Topic>
   <User>CX-12345</User>
  </Mqtt>
 </RemoteConnections>
</TcConfig>

The <User> element specifies an identity that can be used in the TcMqttPlugin to configure access rights between ADS devices. However, the identity is usually defined by other means, e.g. the CommonName (CN) of a client certificate.

Optionally, the <Mqtt> element can contain a ClientId attribute to specify the MQTT ClientID. This is otherwise formed from the <User> and an arbitrary string.