Back

General Commands and Reports

The general commands and reports are used to communicate using device-independent messages. This means that all universal (common for all the devices) messages, such as errors and warnings are presented here. Furthermore, a general structure of command and report messages is given here. This structure is used for all MQTT2GO messages (both command and report ones).

Topics Structure

The general MQTT2GO topic structure is created to be as efficient as possible, generating a reasonable amount of subtopics and therefore following the MQTT best practices. The main topic structure itself is then composed as follows:

<home_id>/<gateway_id>/<dev_id>/<entity>/<msg_direction>

• where the <home_id> stands for the unique identificator of the home (this is used for the identification of a group of users, that are sharing one or more SH-GWs and corresponding amount of devices connected to them),
• <gateway_id> is the unique identificator of the SH-GW,
• <dev_id> is device’s own unique identificator,
• <entity> is the unique identificator of the message information (i.e., humidity),
• and <msg_direction> defines the direction of the communication, where in stands for the communication going to the device (i.e., commands) and out represents the responses from the device to the gateway / controller.

To access a multiple devices or all of their entities, wildcard masks from the MQTT standard have to be used. If we want to substitute only one level, a + wildcard can be used. This means that the topic would look like:

<home_id>/<gateway_id>/+/<entity>/<msg_direction>

which means that the subscription will be done to all devices, where the <entity>/<msg_direction> matches inserted data.

If the subscription should be to a larger group of end devices, a # wildcard mask is used. This means that all topics starting at the # and further are subscribed:

<home_id>/<gateway_id>/#

Some examples of the whole topic structure are as follows:

• Information topic of a device:

<home_id>/<gateway_id>/<dev_id>/about/<msg_direction>

• Topics used to switch on/off either the device or its relay and to report the status from the device back to the controller:

<home_id>/<gateway_id>/<dev_id>/switch/<msg_direction>

• Topic utilized for the humidity reports

<home_id>/<gateway_id>/<dev_id>/humidity/out

MQTT Commands

The commands are composed of three fields: (i) type, providing information about the type of the command, (ii) timestamp, and (iii) value containing the actual command. The command itself can be either a simple name-value pair or a complex structure, which is usually used for complex operations such as device setup.

{
    "type": "command_type",
    "timestamp": "timestamp_value",
    "value": "value_body"
}

The timestamp defines the datetime of the event sent within the message. It is in Unix format. The type defines what information should be expected in the value field. It can be any of the command types defined in the sections Objects MQTT Commands and Controllers MQTT Commands. For example, if the command_type_value contains set, a value of simple commands such as on can be expected. In addition, if command_type_value contains a color keyword, the value should contain an object, which describes the RGB information needed to set up the chosen color.
Based on previous examples, the value field can contain either a simple command such as on, off and similar, or more advanced commands represented by an object (i.e., the object for RGB information for setting the light color).

The general query commands common for all devices are defined as follows:

• A topic used for controlling the on/off status of the device (below, the on example is shown):

<home_id>/<gateway_id>/<dev_id>/switch/<msg_direction>

• A topics used to query the battery level and report the value back:

<home_id>/<gateway_id>/<dev_id>/battery/<msg_direction>

• A topic used to query current state of the device and report the value back:

<home_id>/<gateway_id>/<dev_id>/state/<msg_direction>

• A topic to query the tamper status of selected device and report the value back:

<home_id>/<gateway_id>/<dev_id>/tamper/<msg_direction>

• A topic used to query the status of the device and report the value back:

<home_id>/<gateway_id>/<dev_id>/status/<msg_direction>

MQTT Reports

The report message structure is used for replies coming from the devices. The report messages can also contain a periodic update from the device. They are marked by the report type, that helps to differentiate between aforementioned report types. Furthermore, the priority level field enables devices to divide messages by their priority (1) (such as alarms), replies to commands (2), and standard periodic messages (3).

{
    "type": "report_type_value",
    "priority_level":"priority_level_value",
    "timestamp":"timestamp_value",
    "value":"value_body" 
}

The priority_level is used to set a message priority. It can be between 1-4, where 1 denotes the lowest and 4 the highest. The report_type defines the type of report, there are four types of reports:

1. Status,
2. CommandResponse,
3. PeriodicReport,
4. Error.

The timestamp defines the datetime of the message sent event. It is in Unix format.

Back