Broker

The MQTT broker is used to broker the ADS commands between the routers. The topic structure used is described in Architecture.

General

Any MQTT broker can be used for ADS-over-MQTT with suitable support of, for example, RETAIN and QoS.

Appropriate measures must be taken if this broker needs to be protected in terms of security because the ADS messages need to be protected. The security configuration on the TwinCAT side and, for example, for the Eclipse Mosquitto Broker is described in Security.

Tc-Plugin TcMqttPlugin.dll for the Eclipse Mosquitto Broker

In order to define a virtual network of ADS devices in the MQTT broker, there is an extension for the Eclipse Mosquitto Broker. Using this extension, access rights can be set by PreSharedKey on the broker and accesses between the TwinCAT routers can be set by means of an ACL (AccessControlList).

Broker 1:

The plugin is supplied with the TwinCAT installation and is located in the folder C:\TwinCAT\AdsApi\TcMqttPlugin or C:\TwinCAT\AdsApi\x64\TcMqttPlugin if a 64-bit Mosquitto Broker is used.
The plugin is integrated in the Mosquitto configuration as follows:

auth_plugin <Path>TcMqttPlugin.dll
auth_opt_xml_file <Path>ACL.xml

The Mosquitto configuration file is specified when starting the Mosquitto broker by means of the parameter "-c", which loads the plugin including the configuration.

The file ACL.xml is thereby described in the following sections and provides the access configuration by PreSharedKey on the broker itself as well as the configuration of the communication between the connected TwinCAT routers.

Configuration of "Virtual Ams Network"

The plugin TcMqttPlugin offers the option of configuring virtual Ams networks. To do this, specify which device can access which other device for each target device.
Unlike classic ADS routes, these connections are directional: A target therefore has no right at the same time to access the source.

<TcMqttAclConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\TwinCAT\3.1\Config\Modules\TcMqttAclConfig.xsd" AnonymousLogin="true"> 
<!-- PSK Elements, if used -->
    <Ams>
        <Topic>VirtualAmsNetwork1</Topic>
        <User>
            <Name>EngineeringStation</Name>
        </User>        
        <User>
            <Name>CX-123456</Name>
            <Access>EngineeringStation</Access>
        </User>
        <User>
            <Name>CX-567890</Name>
            <Access>EngineeringStation</Access>
        </User>
    </Ams>
</TcMqttAclConfig>

The name of the Ams network is defined within an <Ams> node. It is used in the MQTT topics employed for the identification of the networks.
Individual <User> elements describe the devices. These elements have a <Name> element that describes the MQTT identity with which the connection was established – in the normal case the name of the device. In addition, access-entitled devices are defined via the <Access> element.
In the example, "EngineeringStation" can thus access two CX devices, but the CX devices can access neither the "EngineeringStation" nor each other.

The file is cyclically reloaded so that a broker restart is unnecessary.

As no encryption is foreseen in this explanation, AnonymousLogin=“true“ is used.

Restrictions with regard to the AmsNetId to be registered

With this configuration each validly connected device can assume an arbitrary AmsNetID and thus an identity from the point of view of ADS. This can be restricted:

<User>
  <Name>CX-567890</Name>
  <Access>EngineeringStation</Access>
  <NetId>192.168.56.1.1.1</NetId>
</User>

As soon as at least one NetId is specified, only one NetId can be registered from this list.

Mosquitto settings

In connection with the configuration by means of TcMqttPlugin, it is important to observe some of the settings on the Mosquitto Broker side. These include:

psk_hint Designates the psk_hint for the establishment of the connection. Not currently checked on the TwinCAT side.
port <1883|8883> The port designates the network port provided by the broker. Typically, 1883 is unencrypted and 8883 encrypted.
require_certificate <true|false> Indicates the necessity of certificates.
use_identity_as_username true Indicates whether the identity is used by certificates as a user name at MQTT level. This is used in order to use the TcMqttPlugin, therefore it must be set to true.

Minimum configuration examples are described in the corresponding sections according to the TLS connection used.