Quick Start

This documentation article is intended to allow you an initial, quick start in how to use this product. Carry out the following steps to establish an ADS-over-MQTT connection to an MQTT message broker and to send and receive ADS messages.

	Message Broker installation This document assumes that you have a locally installed and working MQTT message broker. As an example we use the Mosquitto Message Broker here, but you can use any message broker.

Overview

For demonstration purposes, two TwinCAT devices are to establish an ADS-over-MQTT connection with the message broker. We then use TwinCAT XAE (Engineering) on the first device to establish a connection to the second system via the ADS-over-MQTT route. To keep the installation scenario as simple as possible, both devices should be on the same network.

Device 1:

Mosquitto Message Broker
TwinCAT 3 XAE

Device 2:

TwinCAT 3 XAE or XAR

Note the IP address or the host name of Device 1. In the latter case, make sure that the name resolution works in your network.

Message Broker setup

The Mosquitto Message Broker has been delivered since version 2.x with a configuration that requires security measures to be set up to ensure secure operation of the message broker. In the following, we will show you how to modify the Mosquitto Message Broker configuration so that an unsecured communication connection can be established with the broker. However, this should be done exclusively for testing purposes in a trusted operating environment. For productive operation, we recommend using a secure broker configuration.

1. Install the Mosquitto Message Broker on your system.

2. Make a backup of the mosquitto.conf file from the Mosquitto installation directory. This is typically located at C:\Program Files\mosquitto.

3. Open the mosquitto.conf file with a text editor of your choice and remove the existing content. Add the following content and save the file.

listener 1883
allow_anonymous true

4. Restart the Mosquitto Message Broker, either via the corresponding Windows service or manually via the console or mosquitto.exe.

You have now configured the Mosquitto Message Broker to listen for incoming client connections on port 1883 and it does not require any security (neither user authentication nor client certificates).

	Windows firewall on Device 1 Please enable the standard MQTT port 1883/tcp as an incoming port in the Windows firewall of Device 1 so that Device 2 can establish a connection to the message broker.

You can now start configuring TwinCAT.

Configuration of the first TwinCAT device

The TwinCAT ADS router on this device should now establish a route to the local message broker. Create a new XML file, e.g. with Notepad, and insert the following content.

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

Save this XML file under any name in the following directory and restart TwinCAT for the changes to take effect.

\TwinCAT\3.1\Target\Routes

Configuration of the second TwinCAT device

The TwinCAT ADS router on this device should establish a route to the message broker on device 1. Create a new XML file, e.g. with Notepad, and insert the following content.

<?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">%IPAddress%</Address>
    <Topic>VirtualAmsNetwork1</Topic>
    </Mqtt>
  </RemoteConnections>
</TcConfig>

Replace the entry %IPAddress% with the IP address or the host name of device 1. Save this XML file under any name in the following directory and restart TwinCAT for the changes to take effect.

\TwinCAT\3.1\Target\Routes

Connecting the engineering

Now start TwinCAT XAE on Device 1 and create a new TwinCAT project. Alternatively, you can also open an existing project. For this tutorial, we only need the toolbar to establish a connection to a remote ADS device.

You will now find TwinCAT Device 2 in the toolbar and can establish a connection to it.

Next steps

After you have successfully established an ADS-over-MQTT connection to the message broker, we recommend that you reset the Mosquitto Message Broker to its default settings. For this, please take the backup file of mosquitto.conf that you created in the previous steps. This file, together with the broker documentation, is a good basis for further steps, e.g. to set up a secure message broker operating environment considering client/server certificates and user authentication.