Generic MQTT Client

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 docid\ hbfsowtyt29n7kdu oqio export module the messages sent use the generic iot data model docid\ kecs0ojeas7l0o5gxzaof 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 user available user accounts the user account to be used when accessing the data it is thus possible to restrict the export of devices or access to commands connection mode socket socket websocket selection whether a tcp or web socket connection is used broker ip or dns name of the broker without protocol or port example test mosquitto org the broker to which the connection should be established port 1883 1 65535 the port to use when establishing a connection auth user user name for authentication at the broker auth password password for authentication at the broker ssl off on trust all off option whether an encrypted connection should be established with the option "trust all" it is possible to trust all certificates ssl server crt in ssl mode, the server certificate is used to validate the connection to the broker ssl client crt in ssl mode, the client certificate is used to validate the client ssl client key in ssl mode, the private client key is used to authenticate to the broker ssl client key password in ssl mode this password is used to unlock the client key https hostname verification on on off in ssl mode, the hostname used is explicitly checked in the broker's certificate qos 0 0 1 2 the qos value determines how messages are delivered the higher the qos value, the greater the latency of message delivery qos 0 means that the messages are sent without confirmation of receipt a classic "fire & forget" qos 1 , on the other hand, sends the message until a confirmation of receipt is received by the broker the client can be sure that the broker has received the message it is possible that a message is sent or delivered multiple times qos 2 uses a double confirmation to ensure that a message is delivered only once for this purpose, the broker confirms receipt to the client, and the client in turn confirms receipt of the confirmation to the broker thus client and broker both know that the message was delivered correctly and only once by using event ids and timestamps in the message containers used by this implementation, it is possible to deal with duplicate messages and thus avoid the high latencies of qos 2 and implement similar security with qos 1 in principle, qos 0 can also be used in environments with stable connections retain messages on on off specifies whether the last messages for a topic should be cached on the broker other clients will then receive these messages directly after their login this way the last known state can be effectively cached on the broker timeout (s) 90 0 10 15 30 60 90 120 150 180 300 600 1200 1800 3600 time in seconds which is waited to establish a successful connection otherwise this is interpreted as an error the value 0 deactivates the timeout, it will be waited until the connection could be established successfully keep alive interval (s) 60 0 10 15 30 60 90 120 150 180 300 600 1200 1800 3600 maximum time in seconds that may elapse before a data packet must be sent if there is no regular data traffic within this time, a ping is automatically sent the value 0 deactivates this monitoring max inflight 10000 1 65000 in qos modes 1 and 2, this value determines the maximum number of messages that can be sent without an acknowledgement of receipt being received this value may have to be increased in very large operating environments 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 representation of a device acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183 { &#x9;"nodeid" "acdbda59e9cf", &#x9;"eventid" "igu16ksjlsu6m80v", &#x9;"timestamp" 1636543467229, &#x9;"thing" { &#x9; "id" "b9f09ef8 3c3f 459e 841f 66bdaedff183", &#x9; "name" "fsb14", &#x9; "channelgroups" \[{ &#x9; "channelgroupid" "sensor group", &#x9; "channeldescriptiondata" null, &#x9; "channels" \[{ &#x9; "channelid" "jalousie", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie", &#x9; "en us" "shutters" &#x9; } &#x9; }, &#x9; "value" "29 0", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "number double", &#x9; "unit" "%", &#x9; "min" 0 0, &#x9; "max" 100 0, &#x9; "stepping" 1 0, &#x9; "decimalpartdigits" 1, &#x9; "possiblevalues" null &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousie", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "jalousie", &#x9; "tsystems >type" "value" &#x9; } &#x9; }, { &#x9; "channelid" "jalousiestate", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie", &#x9; "en us" "shutters" &#x9; } &#x9; }, &#x9; "value" "unknown", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "up" { &#x9; "de de" "herauf", &#x9; "en us" "up" &#x9; }, &#x9; "down" { &#x9; "de de" "herunter", &#x9; "en us" "down" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousiestate", &#x9; "message >count" "0", &#x9; "eoap >changeable" "false", &#x9; "message >enabled" "false", &#x9; "sensor name" "direction", &#x9; "tsystems >type" "state" &#x9; } &#x9; }, { &#x9; "channelid" "priority", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "switch", &#x9; "label" { &#x9; "de de" "priorität", &#x9; "en us" "priority" &#x9; } &#x9; }, &#x9; "value" "off", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "on" { &#x9; "de de" "an", &#x9; "en us" "on" &#x9; }, &#x9; "off" { &#x9; "de de" "aus", &#x9; "en us" "off" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#priority", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "priority", &#x9; "tsystems >type" "state" &#x9; } &#x9; }, { &#x9; "channelid" "jalousieslat", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie (lamellen)", &#x9; "en us" "shutters (slats)" &#x9; } &#x9; }, &#x9; "value" "unknown", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "up" { &#x9; "de de" "herauf", &#x9; "en us" "up" &#x9; }, &#x9; "down" { &#x9; "de de" "herunter", &#x9; "en us" "down" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousieslat", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "jalousieslat", &#x9; "tsystems >type" "state" &#x9; } &#x9; }] &#x9; }], &#x9; "state" "online", &#x9; "parametergroups" null, &#x9; "metainfos" { &#x9; "alexa >alexa live updates" "false", &#x9; "monitoring >monitorable" "true", &#x9; "teachin >group displayname" "test", &#x9; "bsc >short info" "fsb14", &#x9; "metainfo >id" "adevice#b9f09ef8 3c3f 459e 841f 66bdaedff183", &#x9; "teachin >reference id" "enocean eltako fsb14", &#x9; "eoap >activated" "true", &#x9; "teachin >transmission id" "default=4291820288", &#x9; "lastmodified" "1636543466499", &#x9; "eoap >alarm" "false" &#x9; } &#x9;} } single channel value acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183/jalousie/value { "nodeid" "acdbda59e9cf", "eventid" "igu16ksjlsu6m80v", "timestamp" 1636543467229, "value" "29 0" } raw channel value acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183/jalousie/value/raw 29 0 meta information 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" } } 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 change value { "type" "change value", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0", "channelid" "dimmer", "newvalue" "73" } } auto pairing { "type" "auto pairing", "parameters" { "pairingenabled" "true", "targetgrpid" "0", "enabledforsec" "90" } } delete thing { "type" "delete thing", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0" } } change parametervalue { "type" "change parametervalue", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0", "channelid" "2718db30 21c5 4d63 879b c6392ae04c6d", "newvalue" "false" } } 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 examples connected { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "oi2advu5fmptvmk6", &#x9;"timestamp" 1649843546682, &#x9;"version" "3 3 1", &#x9;"connected" true, &#x9;"metainfos" {} } disconnected { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "disconnect", &#x9;"timestamp" 1, &#x9;"version" "3 3 1", &#x9;"connected" false, &#x9;"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 example notification object { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "ce40i927ri52lcm7", &#x9;"timestamp" 1649843666187, &#x9;"msg" "admin\@smartnode this is a test message\nthe test was performed successfully\nline breaks are allowed" }