Generic MQTT Client
The export module "Generic MQTT Client" connects to an MQTT broker and publishes status messages under different topics.
These topics are similar in structure to the URL structure of the Generic REST Server export module.
The messages sent use the Generic IoT Data Model within a container object, which provides message identification information.
Multiple export instances can be created, but only one instance per broker URL.
After the connection to a broker has been established, all available devices are transmitted as an update. This ensures that the current device status has been transmitted.
Messages are always transmitted as strings and are usually formatted as JSON objects.
In the IoT Export area of the Web configuration or the BSC Remote, the export connection can be created and the parameters configured.
TCP/SSL and web socket (http/https) connections are supported. Authentication is possible by username and password or client certificate.
The corresponding certificates or access data can be stored during configuration.
There is a possibility to customize the basic topics for publishing news.
Parameter | Default value | Possible values | Description |
Thing Topic Prefix | GATEWAY_ID/things | | All Thing updates are published in topics with this prefix. |
Command Topic | GATEWAY_ID/cmd |
| Commands can be sent to the gateway under this topic. |
Status Topic | GATEWAY_ID/status |
| Under this topic the gateway publishes its status information. The connection status Connected/Disconnected can be read out here. |
Notification Topic | GATEWAY_ID/msg |
| Push notifications for the selected user will be published under this topic. |
All messages, except RAW messages, are transmitted as JSON objects.
Basic information for message assignment is available in all objects.
Field | Data type | Description |
nodeId | String | A unique ID that identifies the gateway. |
eventId | String | A unique ID that identifies the triggering event. It is possible that multiple messages are generated by the same event and thus receive the same event ID. An example of this would be device updates. There Sub Topics are used, so the individual channel Sub Topics receive messages with the same Event ID. It is guaranteed that an Event ID occurs only once within 24 hours. |
timestamp | Number | Difference, measured in milliseconds, between the current time and 01/01/1970 00:00 based on the UTC time zone. This timestamp, together with the event ID, can also be used to uniquely identify messages. |
The "Thing Topic Prefix" stored in the configuration serves as the basis for all device updates. An example of this would be "ACDBDA59E9CF/things".
The actual device updates are published via nested sub topics
Sub Topics are notified only when values are changed.
Thus, with the subscription you can specifically decide about which data you will be notified.
Sub topic | Description |
/<Thing ID> | The complete Thing object. |
/<Thing ID>/state | The online/offline status of the device. |
/<Thing ID>/metaInfos | The meta information of the device. |
/<Thing ID>/<Channel ID>/value | The value of a single channel. |
/<Thing ID>/<Channel ID>/value/raw | The value as a plaintext string without messages container. |
/<Thing ID>/parameter/<Channel ID>/value | The value of a single parameter channel. |
/<Thing ID>/parameter/<Channel ID>/value/raw | The parameter value as a plaintext string without messages container. |
The change of values can be triggered via an especially provided sub topics. A distinction is made between channel and parameter values:
/<Thing ID>/<Channel ID>/value/set
/<Thing ID>/parameter/<Channel ID>/value/set
The new value is simply sent as a message to this topic.
As soon as the value has been changed in real, corresponding updates are sent to the sub topics described earlier.
Alternatively, there is also a command object for changing values, for more details see the section on the command topic.
Various commands can be sent to the gateway via the command topic, which is stored in the configuration as "Command Topic".
A command always consists of the command type and some parameters. The parameters are always strings.
Command type | Parameter | Possible values | Required | Description |
CHANGE_VALUE | thingId |
| X | Unique Thing ID of the device. |
| channelId |
| X | The unique channel ID of the channel to be switched. |
| newValue |
| X | The new value to be set. |
AUTO_PAIRING | pairingEnabled |
| X | Indicates whether the automatic startup should be activated. If it is already activated, nothing happens. |
| targetGrpID | Positiver Wert | X | The ID of the group to which new devices are to be added. If no groups are available, 0 must be specified. The devices are thus created without group assignment. |
| enabledForSec | Positiver Wert | X | Time in seconds until the teach-in mode is automatically switched off again. A value of 0 deactivates the automatic switch-off. |
DELETE_THING | thingId |
| X | Unique ID of the thing |
CHANGE_PARAMETER_VALUE | thingId | | X | Unique Thing ID of the device. |
| channelId | | X | The unique parameter channel ID of the channel to be switched. |
| newValue | | X | The new value to be set. |
Status information is transmitted from the gateway via the status topic, which is stored in the configuration as "Status Topic".
The online status is of particular importance here. This indicates whether the gateway is connected to the MQTT broker.
If the gateway is not connected to the broker, the event ID of the status message is set to "disconnect" and the timestamp is set to -1.
Field | Data type | Description |
version | String | The current software version of the gateway. |
connected | Boolean | Status whether the gateway is currently connected. |
metaInfos | Objekt | An object with additional information. Each field is of data type string, the field name acts as the mapping key. |
Push notifications are transmitted via the notification topic, which is stored in the configuration as "Notification Topic".
The push notifications must be specific to the user selected under "User".
Field | Data type | Description |
msg | String | The text of the push notification. It may contain \n for line breaks. |