Generic MQTT Client

18min

Introduction
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.
Configuration
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
﻿
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.
Base data of messages
All messages, except RAW messages, are transmitted as JSON objects.
Basic information for message assignment is available in all objects.
Base fields
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.
Device topics
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
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.
Change values
The change of  values can be triggered via an especially provided sub topics. A distinction is made between channel and parameter values:
Channel values
/<Thing ID>/<Channel ID>/value/set
Parameter values
/<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.
Examples
ACDBDA59E9CF/things/b9f09ef8-3c3f-459e-841f-66bdaedff183
{
	"nodeId": "ACDBDA59E9CF",
	"eventId": "igu16ksjlsu6m80v",
	"timestamp": 1636543467229,
	"thing": {
		"id": "b9f09ef8-3c3f-459e-841f-66bdaedff183",
		"name": "FSB14",
		"channelGroups": [{
			"channelGroupId": "Sensor Group",
			"channelDescriptionData": null,
			"channels": [{
				"channelId": "Jalousie",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie",
						"en_US": "shutters"
					}
				},
				"value": "29.0",
				"valueDescriptionData": {
					"valueType": "NUMBER_DOUBLE",
					"unit": "%",
					"min": 0.0,
					"max": 100.0,
					"stepping": 1.0,
					"decimalPartDigits": 1,
					"possibleValues": null
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#Jalousie",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Jalousie",
					"TSYSTEMS->type": "value"
				}
			}, {
				"channelId": "JalousieState",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie",
						"en_US": "shutters"
					}
				},
				"value": "UNKNOWN",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"UP": {
							"de_DE": "Herauf",
							"en_US": "up"
						},
						"DOWN": {
							"de_DE": "Herunter",
							"en_US": "down"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#JalousieState",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "false",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Direction",
					"TSYSTEMS->type": "state"
				}
			}, {
				"channelId": "Priority",
				"channelDescriptionData": {
					"channelTypeEnum": "SWITCH",
					"label": {
						"de_DE": "Priorität",
						"en_US": "priority"
					}
				},
				"value": "OFF",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"ON": {
							"de_DE": "An",
							"en_US": "on"
						},
						"OFF": {
							"de_DE": "Aus",
							"en_US": "off"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#Priority",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Priority",
					"TSYSTEMS->type": "state"
				}
			}, {
				"channelId": "JalousieSlat",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie (Lamellen)",
						"en_US": "shutters (slats)"
					}
				},
				"value": "UNKNOWN",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"UP": {
							"de_DE": "Herauf",
							"en_US": "up"
						},
						"DOWN": {
							"de_DE": "Herunter",
							"en_US": "down"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#JalousieSlat",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "JalousieSlat",
					"TSYSTEMS->type": "state"
				}
			}]
		}],
		"state": "ONLINE",
		"parameterGroups": null,
		"metaInfos": {
			"ALEXA->ALEXA_LIVE_UPDATES": "false",
			"MONITORING->MONITORABLE": "true",
			"TEACHIN->GROUP_DISPLAYNAME": "Test",
			"BSC->SHORT_INFO": "FSB14",
			"METAINFO->id": "ADevice#b9f09ef8-3c3f-459e-841f-66bdaedff183",
			"TEACHIN->REFERENCE_ID": "enocean.eltako.fsb14",
			"EOAP->ACTIVATED": "true",
			"TEACHIN->TRANSMISSION_ID": "default=4291820288",
			"lastModified": "1636543466499",
			"EOAP->ALARM": "false"
		}
	}
}
{
	"nodeId": "ACDBDA59E9CF",
	"eventId": "igu16ksjlsu6m80v",
	"timestamp": 1636543467229,
	"thing": {
		"id": "b9f09ef8-3c3f-459e-841f-66bdaedff183",
		"name": "FSB14",
		"channelGroups": [{
			"channelGroupId": "Sensor Group",
			"channelDescriptionData": null,
			"channels": [{
				"channelId": "Jalousie",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie",
						"en_US": "shutters"
					}
				},
				"value": "29.0",
				"valueDescriptionData": {
					"valueType": "NUMBER_DOUBLE",
					"unit": "%",
					"min": 0.0,
					"max": 100.0,
					"stepping": 1.0,
					"decimalPartDigits": 1,
					"possibleValues": null
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#Jalousie",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Jalousie",
					"TSYSTEMS->type": "value"
				}
			}, {
				"channelId": "JalousieState",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie",
						"en_US": "shutters"
					}
				},
				"value": "UNKNOWN",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"UP": {
							"de_DE": "Herauf",
							"en_US": "up"
						},
						"DOWN": {
							"de_DE": "Herunter",
							"en_US": "down"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#JalousieState",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "false",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Direction",
					"TSYSTEMS->type": "state"
				}
			}, {
				"channelId": "Priority",
				"channelDescriptionData": {
					"channelTypeEnum": "SWITCH",
					"label": {
						"de_DE": "Priorität",
						"en_US": "priority"
					}
				},
				"value": "OFF",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"ON": {
							"de_DE": "An",
							"en_US": "on"
						},
						"OFF": {
							"de_DE": "Aus",
							"en_US": "off"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#Priority",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "Priority",
					"TSYSTEMS->type": "state"
				}
			}, {
				"channelId": "JalousieSlat",
				"channelDescriptionData": {
					"channelTypeEnum": "SHADING",
					"label": {
						"de_DE": "Jalousie (Lamellen)",
						"en_US": "shutters (slats)"
					}
				},
				"value": "UNKNOWN",
				"valueDescriptionData": {
					"valueType": "STATE",
					"unit": null,
					"min": null,
					"max": null,
					"stepping": null,
					"decimalPartDigits": null,
					"possibleValues": {
						"UNKNOWN": {
							"de_DE": "Unbekannt",
							"en_US": "unknown"
						},
						"UP": {
							"de_DE": "Herauf",
							"en_US": "up"
						},
						"DOWN": {
							"de_DE": "Herunter",
							"en_US": "down"
						}
					}
				},
				"writeable": false,
				"metaInfos": {
					"METAINFO->id": "ASensor#b9f09ef8-3c3f-459e-841f-66bdaedff183#JalousieSlat",
					"MESSAGE->COUNT": "0",
					"EOAP->CHANGEABLE": "true",
					"MESSAGE->ENABLED": "false",
					"Sensor.Name": "JalousieSlat",
					"TSYSTEMS->type": "state"
				}
			}]
		}],
		"state": "ONLINE",
		"parameterGroups": null,
		"metaInfos": {
			"ALEXA->ALEXA_LIVE_UPDATES": "false",
			"MONITORING->MONITORABLE": "true",
			"TEACHIN->GROUP_DISPLAYNAME": "Test",
			"BSC->SHORT_INFO": "FSB14",
			"METAINFO->id": "ADevice#b9f09ef8-3c3f-459e-841f-66bdaedff183",
			"TEACHIN->REFERENCE_ID": "enocean.eltako.fsb14",
			"EOAP->ACTIVATED": "true",
			"TEACHIN->TRANSMISSION_ID": "default=4291820288",
			"lastModified": "1636543466499",
			"EOAP->ALARM": "false"
		}
	}
}
﻿
ACDBDA59E9CF/things/b9f09ef8-3c3f-459e-841f-66bdaedff183/Jalousie/value
{
    "nodeId": "ACDBDA59E9CF",
    "eventId": "igu16ksjlsu6m80v",
    "timestamp": 1636543467229,
    "value": "29.0"
}
{
    "nodeId": "ACDBDA59E9CF",
    "eventId": "igu16ksjlsu6m80v",
    "timestamp": 1636543467229,
    "value": "29.0"
}
﻿
ACDBDA59E9CF/things/b9f09ef8-3c3f-459e-841f-66bdaedff183/Jalousie/value/raw
29.0
29.0
﻿
ACDBDA59E9CF/things/b9f09ef8-3c3f-459e-841f-66bdaedff183/metaInfos
{
    "nodeId": "ACDBDA59E9CF",
    "eventId": "igu16ksjlsu6m80v",
    "timestamp": 1636543467229,
    "metaInfos": {
        "ALEXA->ALEXA_LIVE_UPDATES": "false",
        "MONITORING->MONITORABLE": "true",
        "TEACHIN->GROUP_DISPLAYNAME": "Test",
        "BSC->SHORT_INFO": "FSB14",
        "METAINFO->id": "ADevice#b9f09ef8-3c3f-459e-841f-66bdaedff183",
        "TEACHIN->REFERENCE_ID": "enocean.eltako.fsb14",
        "EOAP->ACTIVATED": "true",
        "TEACHIN->TRANSMISSION_ID": "default=4291820288",
        "lastModified": "1636543466499",
        "EOAP->ALARM": "false"
    }
}
{
    "nodeId": "ACDBDA59E9CF",
    "eventId": "igu16ksjlsu6m80v",
    "timestamp": 1636543467229,
    "metaInfos": {
        "ALEXA->ALEXA_LIVE_UPDATES": "false",
        "MONITORING->MONITORABLE": "true",
        "TEACHIN->GROUP_DISPLAYNAME": "Test",
        "BSC->SHORT_INFO": "FSB14",
        "METAINFO->id": "ADevice#b9f09ef8-3c3f-459e-841f-66bdaedff183",
        "TEACHIN->REFERENCE_ID": "enocean.eltako.fsb14",
        "EOAP->ACTIVATED": "true",
        "TEACHIN->TRANSMISSION_ID": "default=4291820288",
        "lastModified": "1636543466499",
        "EOAP->ALARM": "false"
    }
}
﻿
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
true
false
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.
Examples
Status topic
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.
Status Object
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.
Connected
Disconnected
{
	"nodeId": "ACDBDA59EB17",
	"eventId": "disconnect",
	"timestamp": -1,
	"version": "3.3.1",
	"connected": false,
	"metaInfos": {}
}
{
	"nodeId": "ACDBDA59EB17",
	"eventId": "disconnect",
	"timestamp": -1,
	"version": "3.3.1",
	"connected": false,
	"metaInfos": {}
}
﻿
Notification Topic
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".
Notification object
Field
Data type
Description
msg
String
The text of the push notification.

It may contain \n for line breaks.
Notification object
{
	"nodeId": "ACDBDA59EB17",
	"eventId": "ce40i927ri52lcm7",
	"timestamp": 1649843666187,
	"msg": "Admin@SmartNode: This is a test message\nThe test was performed successfully\nLine breaks are allowed"
}
{
	"nodeId": "ACDBDA59EB17",
	"eventId": "ce40i927ri52lcm7",
	"timestamp": 1649843666187,
	"msg": "Admin@SmartNode: This is a test message\nThe test was performed successfully\nLine breaks are allowed"
}
﻿
﻿

Parameter	Default value	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.

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.

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.

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

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.

Field	Data type	Description
msg	String	The text of the push notification. It may contain \n for line breaks.

Updated 25 Mar 2024

Did this page help you?

Generic Web Export

IoT Core MQTT Client

Generic MQTT Client

Introduction

Configuration

Parameter

Base data of messages

Base fields

Device topics

Sub topics

Change values

Channel values

Parameter values

Examples

Representation of a device

Single channel value

RAW channel value

Meta information

Command topic

Examples

Status topic

Status Object

Examples

Notification Topic

Notification object

Example