API - MQTT

Every unispa device is equipped with an MQTT protocol serving for a daily communication with the device. Unlike HTTP , MQTT API is not capable of granting full control over the system or program settings. Its designation is limited to:

• Obtaining sensor readings and output states
• Accessing basic program settings, especially times and thresholds
• Sending basic commands

The necessary prerequisite for using the MQTT API is active and stable connection to an MQTT broker. In choosing one, the user can choose from the following two main options:

1. Hosting own broker - this itself contains a wide variety of options ranging from having a microcomputer like Raspberry PI connected to your local area network, to reserving capacity on a professional online server.
2. Using external service - there is a plenty of ready-to-use online MQTT brokers ranging from free to industrial grade services.

A unispa device may connect to all the options contained above. Whatever the final broker choice, all necessary connection details can be provided on the Wireless set-up page. You may also want to check our MQTT connection tutorial for a practical quide and examples.

MQTT Message

The main unit of the MQTT exchange is a message consisting of the Payload carrying the data and the Topic carrying the context. While the Payload of the unispa MQTT messages only contain a simple numeric, logical or time value, Topic of those messages is crucial for addressing the right subject of the right device.

Addressing the device

The first task is to identify the device to communicate with. This purpose is served by setting up the first three levels of the MQTT message topic accessible in the Wireless set-up page. The user may define each of the first three topic levels there. Each may be up to 25 characters long and the first one must not be empty.

• Topic Level 1 is compulsory and serves mainly to identify the user. It is a good practice to set it equal to the broker account user name, or any unique string assigned to this account.
• Topic Level 2 is optional and is intended to identify the place of duty or designation. It is a good practice to briefly describe the device's location here.
• Topic Level 3 is optional and is intended to unambiguously identify the device in case of a larger concentration of devices is used in a single location. It is a good practice to set it equal to the device Name.

By adding another level flagging the message direction - pub for outbound and sub for inbound message from the device perspective - we arrive at the pub/sub Topic roots representing the main basis for the two-way communication with the device. All messages sent by the device then have their topics starting with:
[Topic L1] / [Topic L2]* / [Topic L3]* /pub/

, just as all messages accepted by the device must have topics starting with:
[Topic L1] / [Topic L2]* / [Topic L3]* /sub/

Finally, as long as the Subscription is enabled, the device is automatically subscribed to receive all messages satisfying following topic rule:
[Topic L1] / [Topic L2]* / [Topic L3]* /sub/#

Similarly, the user may receive all messages published by the device by subscribing to:
[Topic L1] / [Topic L2]* / [Topic L3]* /pub/#

Addressing the subject

Once the required Device is identified, the remaining topic levels will address the desired subject of the MQTT message. These can be divided into 3 main groups as detailed out in the following sections:

• Telemetry - sensor readings and output states
• Parameters - basic program settings, especially times and thresholds
• Commands - basic executable instructions

Telemetry

To receive the required telemetry data as a payload, the user needs to subscribe to messages with the following topic:
[Topic L1] / [Topic L2]* / [Topic L3]* /pub/ [TELEMETRY]

All telemetry messages are sent with Retain = true and QoS = 0. For detailed reference on the message Payload and topic's [TELEMETRY] please consult the table below:

Technical messages

Several technical messages are automatically published 30 seconds after a successful connection to an MQTT broker and then repeatedly every 5 minutes for the entire duration of the session:

1. Connection status - with the Payload equal to 1 and the following topic:
   
   [Topic L1] / [Topic L2]* / [Topic L3]* /pub/conn
   * if non-empty

   At the same time, a Testament message is saved within the broker using the same topic and Payload equal to 0.

   The Testament (i.e., Will, or Last Will) message is automatically delivered to all subscribed clients up to 30 seconds after the device's connection with the broker is lost.
2. IP address - with the latest local network IPv4 address as Payload and the topic as follows:
   
   [Topic L1] / [Topic L2]* / [Topic L3]* /pub/ip
   * if non-empty
3. Wi-Fi RSSI - with the Wi-Fi signal strength (RSSI) as Payload and the topic as follows:
   
   [Topic L1] / [Topic L2]* / [Topic L3]* /pub/rssi
   * if non-empty

Subscribe to all technical messages described above to always keep track of the device's status. They can reliably inform you of whether your device is connected and its network location.

Parameters

To set or change the selected program parameter, publish the message with the new value as a payload and the following topic:
[Topic L1] / [Topic L2]* / [Topic L3]* /sub/ [PARAMETER]

Sending the message with Retain = true will allow to keep the respective parameter updates in real time throughout all devices connected to the given topic. For detailed reference on the message Payload and topic's [PARAMETER] please consult the table below:

Commands

To execute the selected command, publish the message with the following topic:
[Topic L1] / [Topic L2]* / [Topic L3]* /pub/ [COMMAND]

For detailed reference on the message Payload and topic's [COMMAND] please consult the table below: