These slides will provide a brief introduction to MQTT, its usage, and best practices for message topics and payload design. Additionally, it will include examples of publishing and persisting messages.
for Message Queuing Telemetry Transport. It is a lightweight messaging protocol for use in cases where clients need a small code footprint and are connected to unreliable networks or networks with limited bandwidth resources.
a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.
- The Standard for IoT Messaging A lightweight messaging protocol for small sensors and mobile devices, optimized for high-latency or unreliable networks, enabling a Connected World and the Internet of Things https://mqtt.org
messages Read- only or fan- in data of measurements transmitted from a device to be persisted and eventually processed by an application Emitted regularly by the device No acknowledgements (QoS=0), no response messages State messages State- Information data transmitted from a device or an application, so that any other application can process or act on that information Emitted regularly by device or requested by an application Acknowledgements (QoS=1), maybe request & response messages Command messages Instruction data transmitted from an application to instruct a target application to do something. Requested by an application, responded by the target application Acknowledgements (QoS=2), request & response messages D DB D A response request A A response request A
MQTT messaging is an agreement between sender and receiver on the guarantee of delivering a message. There are three levels of QoS: 0 - at most once 1 - at least once 2 - exactly once
to a broker, the client determines the QoS level for that message. When the broker sends the message to a subscribing client, the QoS set by the first client for that message is used again. So effectively the original publisher of any message determines the QoS of the message all the way to the final recipients.
most once This is the simplest, lowest- overhead method of sending a message. The client simply publishes the message, and there is no acknowledgement by the broker.
least once This method guarantees that the message will be transferred successfully to the broker. The broker sends an acknowledgement back to the sender, but in the event that that the acknowledgement is lost the sender won't realise the message has got through, so will send the message again. The client will re- send until it gets the broker's acknowledgement. This means that sending is guaranteed, although the message may reach the broker more than once.
once This is the highest level of service, in which there is a sequence of four messages between the sender and the receiver, a kind of handshake to confirm that the main message has been sent and that the acknowledgement has been received. When the handshake has been completed, both sender and receiver are sure that the message was sent exactly once.
message per topic. If a client subscribes to a topic, it will receive the last published message from the broker immediately. This is very useful for state messages where apps act on state information from devices. One more thing: Retained messages
rules apply to Topic Names and Topic Filters: All Topic Names and Topic Filters MUST be at least one character long Topic Names and Topic Filters are case sensitive Topic Names and Topic Filters can include the space character A leading or trailing ‘/’ creates a distinct Topic Name or Topic Filter A Topic Name or Topic Filter consisting only of the ‘/’ character is valid Topic Names and Topic Filters MUST NOT include the null character (Unicode U+0000) [Unicode] Topic Names and Topic Filters are UTF-8 Encoded Strings; they MUST NOT encode to more than 65,535 bytes Message Topics
with a topic prefix Add routing information towards the device & the device/application name that produces the message's payload Add the type of data you transmit or request from the device or application Prefixes for types of messages could be: tlm for telemetry sta for state information cmd for commands 1. 2. 3. Message Topics Best Practices
of message tlm = Telemetry Routing information Residence > Room > Heater Type of data / Measurement Temperature Name of device First Heater Temperature of the first heater in the third bathroom of my second vacation residence
Type of message sta = State information Routing information Residence > Room > Light Type of data Request the switched- on status Name of device Ceiling light 1 Is the ceiling light switched on in my third bathroom of my second vacation residence? sta/mobile/iphone05/app/residence- commander/res/light/switched- on Type of message sta = State information Routing information Device / application Type of data Response to a switched- on request of a light Name of application Residence Commander Respond to the "Residence Commander" app on my fifth iPhone, please!
of message sta = State information Routing information Residence > Room > Light Type of data Instruction to dim the light Name of device Ceiling light 1 Please dim the ceiling light in my third bathroom of my second vacation residence. cmd/mobile/iphone05/app/residence- commander/res/light/dim Type of message sta = State information Routing information Device / application Type of data Response to a dim request of a light Name of application Residence Commander Respond to the "Residence Commander" app on my fifth iPhone, please!
do not overlap on the same topic Messages of each type can be processed individually regarding their purpose Devices and applications have distinct hierarchical routing information for each message type Wildcard subscriptions are possible at every logical group of the topic Devices and applications can be added without conflicts Topics reflect the domain's naming, structure and capabilities Message Topics Best Practices
as possible Transmit only data that is relevant for one specific data point Omit units, because the name of the measurement and the value should implicitly define the unit, respectively the processing application must know the units Add meta data only if necessary and if it does not fit into the message topic. Express clearly that it is meta data and don't encode multiple meta information in one key or value. Payload is expressed in JSON format and should have a JSON schema for validation Telemetry message payloads Example payload for a message with the topic tlm/residence/vacation02/room/bath03/heater/heater01/temperature { "timestamp": 1693406941326, "T": 21.5000000000002, "meta": { "device_serial": "65ebb617- b4a2-4c93" } } The data point consists of one T value. The device serial number (dsn) is meta information.
as possible The requester creates a unique request ID in order to match the response message in return. The requester tells the target topic to which the response should be published to. Payload is expressed in JSON format and should have a JSON schema for validation The responder must include the request ID in the response and transmit the response to the given response topic. The response payload contains a timestamp and the requested status Optionally meta data can be added to the response State message payloads Example payload for a status request message with the topic sta/residence/vacation02/room/bath03/light/ceiling01/req/switched- on { "req- id": "758b1b2c-4c5b-4a6a-8dfc- b4af7425e6fa", "res- to": "sta/mobile/iphone05/app/residence/..." } Example payload for a status response message with the topic sta/mobile/iphone05/app/residence- commander/res/light/switched- on { "req- id": "758b1b2c-4c5b-4a6a-8dfc- b4af7425e6fa", "timestamp": 1693406941326, "SwitchedOn": false, "meta": { "message": "No light bulb installed" } }
as possible The requester creates a unique request ID in order to match the response message in return. The requester tells the target topic to which the response should be published to. Payload is expressed in JSON format and should have a JSON schema for validation The responder must include the request ID in the response and transmit the response to the given response topic. The response payload contains a timestamp, the a success indicator and a response message. Optionally meta data can be added to the response. Command message payloads Example payload for a command message with the topic cmd/residence/vacation02/room/bath03/light/ceiling01/req/dim { "req- id": "758b1b2c-4c5b-4a6a-8dfc- b4af7425e6fa", "luminosity": 0.5, "res- to": "cmd/mobile/iphone05/app/residence/..." } Example payload for a status response message with the topic cmd/mobile/iphone05/app/residence- commander/res/light/dim { "req- id": "758b1b2c-4c5b-4a6a-8dfc- b4af7425e6fa", "timestamp": 1693406941326, "success": false, "message": "Light was already dimmed to 50% luminosity", "meta": { "error": "Too much power consumption, dimming down." } }
telemetry message should contain only one data point and should be sent to one specific topic. A datapoint can consist of more than one value, for example geo- coordinates. Telemetry data points are always measured numbers or booleans expressed as numbers (0 or 1), but never strings.
21.5000000000002, "meta": { "device_serial": "65ebb617- b4a2-4c93" } } Single value data point { "timestamp": 1693406941326, "Lat": 52.581860, "Long": 13.527040 "meta": { "host": "portrino GmbH" } } Multi value data point (geo coordinates)
messages to InfluxDB line protocol The topics and messages as described can be mapped to InfluxDB's line protocol directly using: Telegraf's standard MQTT consumer plugin with topic parsing capabilities https://github.com/influxdata/telegraf/tree/master/plugins/inputs/mqtt_consumer Telegraf's standard JSON input data format parser https://github.com/influxdata/telegraf/tree/master/plugins/parsers/json