IoToad MQTT design

In this section we will explain what is the design behind all the communications through this technology; how the topics are organized and constructed, and how the messages are formatted.

Topics

There are three topics hierarchies:

• command: channels where control commands are published. For example: switch off/on a SmartPlug

• query: channels where data queries are published. For example: what the SmarPlugs consumption is.

• data: channels where collected data is published. For example: a SmartPlug has consumed 5 Watts

command

topic structure: command/<module>/<subpath>

• <module>: it is the name of the module the message is published for.

• <subpath>: it specifies where the message is headed inside the module. For example: sp_command may have sp_command/row/<row:n> or sp_command/<smartplug-id> as a subpath.

examples

• command/sp_command/w.r1.c1

• command/sp_command/row/1

• command/sp_command/column/1

• command/sp_command/m1

query

topic structure: query/<module>/<subpath>

• <module>: it is the name of the module the message is published for.

• <subpath>: it specifies where the message is headed inside the module. For example: influx_query may have :code:`query/influx_query/<influx-database>/<influx-measurement>`as a subpath.

examples

• query/influx_query/sp/power

• query/influx_query/sp/status

data

topic structure: data/<module>/<source>/<source-subpath>

• <module>: it is the name of the module the message is published for. The <module> is the first subtopic on pourpose so that data/+/<source>/<source-subpath> can be used when subscribing.

• <source>: it specifies module that published the message. This is intended so that the topics give information about the data that is being published. For example: if the <source> is sp_data, others know that the data is related to SmarPlugs.

• <source-subpath>: it specifies the details about the data that is being published. For example: sp_data may have data/<module>/sp_data/<smartplug-id> or data/<module>/sp_data/row/<row:n> as a subpath.

examples

• data/influx_data/sp_data

• data/+/sp_data

• data/influx_data/sp_data/w.r1.c1

• data/influx_data/sp_data/row/1

Payload

All MQTT payloads are JSONs that contain these three fields: data, error and response_topic. MQTT payloads can have all of these fields or only one or two, depending on the specific case.

So a MQTT payload format is…

{
    "response_topic": "<response-topic>",
    "data": "<data>",
    "error": "<error>"
}

• data: this field can contain anything: a dictionary with the query parameters, the collected consumption from a Smartplug, etc.

• error: this field contains a string that is used to indicate whether there was an error or not. For example: this can be used for knowing if a command was executed.

• response-topic: this field conatains a MQTT topic string, which is used when a message that an answer is expected is published. For example whenever a query message is published, a result is expected. So the <response-topic> indicates where to publish the result.

Examples

SmartPlug consumption query

query/influx_query/sp/power

{
     "response_topic": "responses/api/809bd939baa44f1f87fdd1099ea05a62",
     "data": {
         "operation": "sum",
         "type": "w",
         "from": 1585217932.2041745
     }
}

SmartPlug consumption query reply

responses/api/809bd939baa44f1f87fdd1099ea05a62

{
     "data": [
         {"bn": "w.r1.r2", "unit":"W"},{"v": 10.4, t: 12345678},{"v": 20.1, t: 12345679}
   ]
}

SmartPlug status command

command/sp_command/w.r1.c0

{
     "response_topic": "responses/api/42694cca24614db48ad12f8f89be642b",
     "data": {"status" : "OFF"}
}

SmartPlug status command reply

responses/api/42694cca24614db48ad12f8f89be642b

{
     "error": "The SmartPlug is unreachable",
}