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.

Homie Convention

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.

structure/layout mqtt

the root topic

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.

multiple devices in 'mkc' root topic

the device topic

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'.

attributes of a device
The IOCards on the eNetVario device are seen as separate devices even if they are a part of the eNetVario device. This allows to publish the data of different IOCards to different root topics and different brokers. Since the IOCards do not have MAC addresses, the partnumber is used for the device topic naming.

the node topic

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'.

attributes of a node

the property topic

The IO's of MKC devices do always have 2 volatile properties:

  • error: the error code of the pin
  • pin: the value of the IO

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.

attributes of a property
No other properties of devices/nodes are published. The MQTT procotol is used only for the data of the IO's. Changes to the device settings or the IO configurations have to be made with the REST API.

Configuration Example for an eNetCube