Technical details¶
Topics format¶
MQTT topics are a one way packet transport system. More advanced communication scheme need using multiple topics with some specific interfaces.
This section describes the different communication mechanisms used, topic naming conventions and message format.
Channels¶
Two way stream require having one topic for one communication side and one for the other. This includes serial port forwarding where one topic is used to read from the serial port and one to write to it.
| input topic: | {resourcetopic}/data/in |
|---|---|
| output topic: | {resourcetopic}/data/out |
Example¶
For a resource at {prefix}/resource/1, the channels topics will be:
# Topic for writing to the resource
{prefix}/resource/1/data/in
# Topic where the resource writes its output
{prefix}/resource/1/data/out
Request model¶
Requests allow executing commands on a resource is a form of two way stream, one to do the request and one to give the result. As a response must correspond to the right request and the right client, a per request/client topic should be specified.
The chosen format is the following:
| request topic: | {resourcetopic}/ctl/{command}/request/{clientid}/{requestid} |
|---|---|
| reply topic: | {resourcetopic}/ctl/{command}/reply/{clientid}/{requestid} |
In practice, by using wildcard topic subscribtion, only one subscribe is necessary per agent/client/request/command:
# Agent subscribe
{prefix}/resource/topic/ctl/{command}/request/+/+
# Client subscribe
{prefix}/resource/topic/ctl/{command}/reply/{clientid}/+
For clientid I recommend using a readable identifier concatenated to an
UUID to ensure both readability and unicity.
Error topic¶
As not all the following communication mechanisms have a response, asynchronous errors or failures happen on an error topic.
The errors are sent to a subtopic from the agent error topic. They are published to the concatenation of the agent error topic and the topic where error happend relative to the agent topic:
{agenttopic}/error/relative/topic/where/problem/occured
| payload: | utf-8 encoded strings. |
|---|
Clients subscribe to errors for this agent with:
{agenttopic}/error/#
Example¶
An error in resource {agenttopic}/resource/1 will be published to:
{agenttopic}/error/resource/1
An error in the general agent to the will be published to:
{agenttopic}/error/ # With the trailing `/`
Sending both UTF-8 and binary in a message¶
If in a message, both text (e.g., a json) and a binary data need to be sent,
it has been chosen to separate the UTF-8 string from the binary payload
using one 0xFF byte.
<UTF-8 encoded JSON string> 0xFF <Binary data>
In fact, 0xFF is never used in a UTF-8 encoded string wikipedia:utf-8
so the payload can safely be split on the first occurence of 0xFF without
requiring to first decode the string.