MQTT¶
Connecting the Platform via MQTT (Message Queuing Telemetry Transport), a small and popular protocol for M2M (Machine to Machine) communication, can use any MQTT Library that supports the device in use. MQTT connection requires 4 parameters: Host, Client ID, Username and Password, specifying each value as follows:
Host |
mqtt.nexiiot.io |
Port |
1883 (mqtt), 1884 (mqtts) |
Client ID |
Client ID of the Device created in NEXIIOT |
Username |
Device Tokens generated in NEXIIOT |
Password |
Not yet specified (used for cases where additional verification is required) |
MQTT API has a Publish/Subscribe usage pattern. Publish is sending data to the desired Topic. Subscribe is waiting to receive data in the desired Topic. Ordering to Subscribe to any Topic only once will receive data in that Topic until you order to Unsubscribe to that Topic or the connection to the Platform is stopped.
Note
Enable field is the field used to set the enable/disable status of the Device. If the Toggle shows a blue bar, it means that the Device is normally enabled. But if the Toggle shows a gray bar, it means that the Device is disabled, which means that the Key cannot be used to connect to the Platform. Or if there is a connection, it will be automatically disconnected. This is used in cases where you want to disable a remote device that you cannot directly manage on the Device, etc.
The Resync Status button is used to update the Platform connection status correctly. If the display on the Portal page is not correct, click on the button to update the status.
Caution
The Subscribe Topic should be ordered before the Publish Topic is ordered to receive the data sent. The data received will only be the data resulting from the Publish after the Subscribe.
An important element to know for using the MQTT API is the Topic because Publish/Subscribe requires specifying the desired Topic. Topic acts like an Endpoint on the MQTT Broker for MQTT Clients to connect and communicate with each other. It supports the following features:
QoS (Quality of Service) 3 levels are an agreement between the sender (Publisher) and the receiver (MQTT Broker) to guarantee the delivery of data.
QoS Level 0 : The transmission of data with the lowest level of guarantee or data that requires fast transmission, i.e., does not require a response that the data has reached the MQTT Broker.
QoS Level 1 : Guaranteed delivery of data at a level where every time data is sent, there must be a response confirming that the data has reached the MQTT Broker. If the response is lost, the sender will retransmit the data until a response is received. This means that the MQTT Broker will definitely receive the data at least once, but the same data may be received more than once.
QoS Level 2 : Highest level of guaranteed data transmission. Data is very important, i.e. every time data is sent, it is confirmed that it was definitely sent to the MQTT Broker and received only once.
Shared Subscription is the distribution of data to all nodes that subscribe to the same topic.
Transparent Virtual Host is Publish / Subscribe to the same Topic. If the Device is in different groups, it will be like a different Topic.
Topic structure in NEXIIOT Platform can be divided into 3 types as follows:
Message API Topic¶
It is a setting of Topic for Publish / Subscribe data to communicate between Devices in the same Group. The usage format is to start Topic with @msg followed by the desired Topic structure as follows:
publish |
publish |
subscribe |
subscribe |
Topic example |
|
As you can see, Topics can be specified hierarchically by separating them with "/". In addition to specifying specific Topics, Wildcard Topics are also supported. There are 2 types:
Multi-level Wildcard # is a wildcard character that matches any number of levels within a topic. When using a multi-level wildcard, it must occupy an entire level and must be the last character of the topic, for example:
Subscribe Topic |
Publish Topics that messages can be sent to |
|---|---|
|
@msg/{any topic (multi-level)} such as |
|
@msg/room/{any topic (multi-level)} such as |
Single-level Wildcards + is a wildcard character that matches only one topic level. When using a single-level wildcard, the single-level wildcard must occupy an entire level, for example:
Subscribe Topic |
Publish Topics that messages can be sent to |
|---|---|
|
@msg/{any topic (single-level)} such as |
|
@msg/room/{any topic (single-level)} such as |
|
@msg/home/{any topic (single-level)}/light such as |
|
@msg/home/{any topic (single-level)}/{any topic (single-level)}/door such as |
Note
Wildcard Topic
'#' must be specified at the end of the Topic hierarchy only. Nothing else can be added after it.
'#' may or may not specify a Topic from that position, but the '+' sign requires it to be specified in that hierarchy.
'#' and '+' can be used in combination, but '#' must be at the end of the Topic hierarchy, for example:
@msg/home/+/bedroom/+/#
Shadow API Topic¶
MQTT Topic related to Device Shadow management can be divided into Publish and Subscribe. Publish is used when requesting data or updating data in Device Shadow. Subscribe is waiting to receive data when Publish requests data or when Device Shadow data is changed and has been subscribed. The usage details are as follows:
1. Private Channel Topic Private Channel Topic is a special channel for receiving responses or monitoring any activity related to itself, such as changes to its own Device Shadow. To use this, start the Topic with @private in the following format:
@private/{response topic}. This is for Subscribe only. The available Response Topics for subscribing to @private are as follows:
Subscribe Topic |
Description |
|---|---|
|
Subscribe for all information published to the Topic starting with @private/ including news that the Platform wants to inform will be published to this Topic. |
|
Subscribe for Device Shadow Data when requested |
|
Subscribe for a response message in case of a Shadow Batch Update |
Shadow Topic is a topic used to manage Device Shadow of itself and other Devices in the same group. If it is another Device, the name (Alias) of that Device must be specified. There are both Publish (edit Shadow data) and Subscribe (wait to receive Shadow data). Related Topics are as follows:
Publish Topic |
Description |
|---|---|
|
This is a request to retrieve all of its own Shadow Data. To receive the data, subscribe to the Topic |
|
This is an update to the Shadow Data by sending the following payload:
|
|
This is an update to the Shadow in the form of a data batch (Shadow Batch Update) |
Note
Publish Topic : Refers to sending a message to the specified Topic.
Subscribe Topic : Refers to receiving a message to the specified Topic.
Shadow Batch Update : Details and usage will be explained in the following section.
Tip
Publish Topic @shadow/data/update — In cases where the field is configured in the Datatag to be stored in the Timeseries Database, if you want to specify the timestamp of the data point yourself, include the timestamp in the payload. If not specified, the server’s receive time will be used. For example:
MQTT topic : @shadow/data/update
MQTT payload : { "data" : { "temp" : 21.5 }, "timestamp": 1566450000000 }
With the condition that if the provided timestamp is older than the latest timestamp in the Shadow Data, the Shadow Data will not be updated. Also, if a Device Trigger is configured, no Shadow Updated event will be triggered. The data will only be stored in the Timeseries Database, creating a historical data point at the specified time.
Shadow Batch Update¶
It is used in cases where the IoT Device cannot send data to the Cloud Platform at the specified time, such as due to internet connection problems, etc. This causes the IoT Device to store data in its own memory first, such as on an SD Card, etc. When the Cloud Platform can be connected, all stored data is sent to the Cloud Platform again. Values can be sent to the Platform at multiple points at the same time.
There are 3 ways to write batch shadows:
MQTT is a batch data writing method that uses Topic and Payload as shown in this example.
Publish topic |
|
Payload |
{
"batch" : [
{"data":{"temp":25.9, "humid":9.6}, "ts":-90000},
{"data":{"temp":25.3, "humid":9.8}, "ts":-60000},
{"data":{"temp":24.5, "humid":9.1}, "ts":-30000},
{"data":{"temp":26.8, "humid":8.2}, "ts":0}
],
"merged": true
}
|
This method does not return a response, but if you want a response to confirm the operation was successful, you need to add an ackid field, which can be any value, such as a number or a string. Every response will be repeated with the same ackid value, so that the user can match the request with the response. Here is an example:
Publish topic |
|
Payload |
{
"ackid" : 1839,
"batch" : [
{"data":{"temp":25.9, "humid":9.6}, "ts":-90000},
{"data":{"temp":25.3, "humid":9.8}, "ts":-60000},
{"data":{"temp":24.5, "humid":9.1}, "ts":-30000},
{"data":{"temp":26.8, "humid":8.2}, "ts":0}
],
"merged": true
}
|
To wait for a reply message, you must subscribe to the specified topic, as follows:
Subscribe Topic |
|
Payload |
|
In the time field that specifies each data point to be written to the Shadow, it is in milliseconds. You can use the word ts or timestamp as the field name. If the value is less than 1000 * 2^23 = 8388608000, it will be considered a relative time with the current time. If the value is greater, it will be considered an absolute time. You can use negative values to represent the past time, which is suitable for updating past data points. For example, if ts or timestamp is set to -90000 and the current timestamp is 1619075885, the time that the data point occurred will be 1619075885 - 90000 = 1618985885 (90 seconds back from the present).
Note
The merged field specified in the payload when writing to the Shadow determines the data writing method—whether to merge or overwrite.
If
merged : trueis set, the data will be merged.If
merged : falseis set, the data will be overwritten.If this field is not specified in the payload, the default value is true, meaning the data will be merged.
The operation of the Expression defined in the Schema and Trigger when writing to the Shadow in batch mode.
The Expression will still be calculated according to the formula defined for each data set, similar to a For Loop writing to the Shadow. However, when writing to the Shadow in batch mode, the Shadow read/write quota will only be deducted as 1 operation. The Shadow Expression quota will still be deducted according to the number of data sets. For example, if 100 data points are sent for storage and there is 1 field with an Expression set, the number of Shadow Expressions deducted will be 1 x 100 = 100 operations.
For Triggers, they will only operate on the data set with the latest value (the highest timestamp). The quota will be deducted as if writing only a single data set.
REST API is a data writing in batches, which is done through a REST API, which can be written in either a merge or overwrite format. See Shadow Batch Update
CoAP API is a batch write operation that is performed via CoAP Protocol, which can be either merged or overwritten. See Shadow Batch Update
Caution
The limitation of writing to the Shadow in batch mode is that the number of data sets sent for writing at a time must not exceed 100 data sets (the batch field in the JSON array). For example, the payload sent for writing data is:
{ "ackid" : 1839, "batch" : [ {"data":{"temp":25.9, "humid":9.6}, "ts":-90000}, {"data":{"temp":25.3, "humid":9.8}, "ts":-60000}, {"data":{"temp":24.5, "humid":9.1}, "ts":-30000}, {"data":{"temp":26.8, "humid":8.2}, "ts":0}], "merged": true }
This means there are 4 data sets, for example. If the number of data sets sent exceeds the specified limit, none of the data will be saved, and a warning message will be returned in JSON format as follows:
{"ackid":140,"errcode":429,"message":"batch size exceeds 100","inputsize": 102}
This means that the Batch write with ackid 140 sent more than 100 data sets, specifically 102 data sets.