IoT Export
Connection Template

Simple EnOcean MQTT Client

18min
introduction the export module "simple enocean mqtt client" establishes the connection to an mqtt broker and publishes messages under different topics multiple export instances can be created, but only one instance per broker url 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 enocean topic prefix enocean all thing updates are published in topics with this prefix gateway topic prefix gateway status messages regarding the gateway are published under this prefix data model base data of messages all messages are transferred 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 timestamp number difference, measured in seconds, between current time and 01/01/1970 00 00 based on utc time zone sensors / actuators in addition to the basic fields, the following fields are available in the device object field data type description name string the name stored for the device eurid string the unique enocean eurid of the device refid string a unique internal identifier of the device type channels array a list of available channels and their values the key is also the channel id, the value is either a number or a text example data fsb 14 { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689865668, 	"name" "fsb 14", 	"eurid" "2a3df3d", 	"refid" "enocean eltako fsb14", 	"channels" { 	 "jalousieslat" "unknown", 	 "jalousie" 65 0, 	 "priority" "off", 	 "jalousiestate" "unknown" 	} } fsr 14 { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689865842, 	"name" "fsr14", 	"eurid" "c23df34", 	"refid" "enocean eltako fsr14", 	"channels" { 	 "switch" "on", 	 "priority" "off" 	} } gateway status in addition to the basic fields, the following fields are available in the gateway status object field data type description version string the software version currently in use online boolean indicates whether the device is currently online example data gateway status object { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689864643, 	"version" "3 5 1", 	"online" true } mqtt topics the used topic structure is divided into data and command t data topics the gateway sends its status messages and the status messages of the connected devices via the data topics sensors / actuators the topic stored in the configuration under "enocean topic prefix" serves as the basis this path is extended by the eurid of the device and the device message is published there example topic enocean/513659d gateway the topic stored in the configuration under "gateway topic prefix" serves as the basis this path is extended by the hardware id of the device and the status message is published there example topic gateway/acdbda4512e0 command topics a simple way of controlling the gateway is implemented via the command topics actuators the topic stored in the configuration under "enocean topic prefix" serves as the basis and enables actuators to be switch this path is extended by the eurid of the device and the channel id as payload the new value is expected as string example topic enocean/513659d/switch example payload on off gateway the topic stored in the configuration under "gateway topic prefix" serves as the basis this path is extended by the hardware id of the device and the command to be executed a json object with the corresponding parameters is expected as payload available commands command payload description pairing on or off time specification in seconds on=90 switch the mode for automatic pairing of new devices on or off optionally, a time can be specified in seconds after which the mode is automatically switched off again delete one devices eurid an attempt is made to delete the device example topic gateway/acdbda4512e0/pairing gateway/acdbda4512e0/delete example payload on=90 off 513659d