 |
Documentation
|
|
Documentation
|
The MQTT protocol is a lightweight, publish/subscribe messaging protocol used for machine to machine communication. Messages can be transfered between client and broker (server) or between two brokers (broker bridge).
A MQTT message consists of the data and a topic, which specifies data location on the broker. If one client publishes data to a topic, all other clients who subscribed to this topic will get the message automatically from the broker.
For more information see the official mqtt website,
MKC devices use the MQTT v3.1 specification.
The structure of published data, the layout of the topics and their relations are not defined in the MQTT specification itself. The data as well as the topics to which the data is sent to can be arbitrary. Therefore a structure of data and topics has to be defined, such that it matches the purpose of the data, is still lightweight and is machine (and in best case human) readable. For this purpose we chose to use the homie convention v4.0.0.
The Homie convention is used mainly for IoT devices and provides a way to publish self-describing data in a machine and human readable form.
The main topic layout described by the convention is
For a detailed description please read the specification v4.0.0.
The convention defines the first topic level to be the static string 'homie'. This has the purpose for machines to easily identify devices which use the homie convention. These could just subscribe to all devices under the 'homie' topic and so would get all the devices, which publish there.
We decided to give the user the ability to change this value. Since at the 'device' topic level there has to be the '$homie' variable, machines can simply subscribe to the wildcard '+/+/$homie' in order to automatically find devices which use the homie convention. Additionaly it gives the user the capability of sorting devices into groups under different first level topics.
The 'device' topic level has to be unique for every device. For this purpose we choose to set it to the lowercase device name (eNetCube = enetcube, eNetIO = enetio, ...) appended with a hyphen and either the last 6 hex characters of the MAC address or the partnumber of the device.
example: eNetCube with a MAC address of '01:23:45:67:FE:DC' publishes to the device topic 'enetcube-67fedc'. An IOCard of an eNetVario device with the part number 123456, will publish its data to the device topic 'iocard-123456'.
The attribute '$name' can be set using the REST API. It is the name of the process found at '/api/v1/process/name'.
The 'node' topic level in MKC devices corresponds to the index of the device's IO in the REST API. This means, for example the node '3' is the IO, which you can access by HTTP at '/api/v1/data/entries/3' and '/api/v1/process/entries/3'.
The attribute '$name' of the node is the process name of the corresponding IO, which can be changed using the REST API. For example the name of node '3' can be changed by setting the '/api/v1/process/entries/3/name'.
The attribute '$type' corresponds to the Json+typeName variable of the IO's data object in the REST API (/api/v1/data/entries/*X*/Json%2BtypeName). This means:
digital inputs have the type 'MkcJsonLib.jDataDi'.
digital outputs have the type 'MkcJsonLib.jDataDo'.
analog inputs have the type 'MkcJsonLib.jDataAi'.
analog outputs have the type 'MkcJsonLib.jDataAo'.
The IO's of MKC devices do always have 2 volatile properties:
The attribute '$name' corresponds to the pin variable of the IO's configuration (/api/v1/process/entries/*X*/pin). This cannot be changed. The attribute '$unit' is either the unit of the analog IO from its configuration (/api/v1/process/entries/*X*/unit) or 'boolean' for digital IOs.
1.9.5