MQTT APIs
Overview
MQTT (Message Queuing Telemetry Transport) is a smaller and more popular protocol for M2M (Machine to Machine) communications that runs over TCP, making it the most ideal for various IoT devices. More information regarding MQTT can be found here . MQTT is a publish-subscribe messaging protocol; publish sends information to the specified Topic and subscribe receives information on the desired Topic until unsubscribed. Subscribing to any Topic is made only once, and they will receive messages in the Topic until they unsubscribe or disconnect from the server; more information is available here:
The component of the MQTT API is Topic, because Publish - Subscribe messaging needs to specify a Topic to be similar to Endpoint. MQTT Broker is qualified to guarantee QoS (Quality of Service) 3 levels are
QoS Level 0 (Lowest Level Guarantee) is the most demanding data transmission speed. Does not wait for a response from MQTT Broker that the data has reached its destination.
QoS Level 1 (Intermediate Guarantee) is always a reply. To confirm that message has been sent to MQTT Broker, when no response is received, the message will be resumed until response is received
QoS Level 2 (Highest Level guarantee) is a very important message. Every message sent must be confirmed that it was sent to MQTT Broker and received it once.
Thing Message Format
Magellan supports key-value content in JSON. Key is always a string, while value can be either String, Number, Boolean, Double or Long , Location String ,Array and Base64String to support media files such as images, videos, audio, and files in API version 2.0 For example:
Key-Value JSON Format
1. {
2. "KeyIsString":"VALUE1",
3. "KeyIsNumber":12,
4. "KeyIsBoolean":true,
5. "KeyIsDouble":34.5,
6. "KeyIsLocationString":"13.7834533,100.5459483",
7. "KeyIsNumberArray":"[1,2,3]",
8. "KeyIsImage":"data:image/png;base64,iVBOR...",
9. "KeyIsVideo":"data:video/mp4;base64,AAAAH...",
10. "KeyIsAudio":"data:audio/mpeg;base64,AAAAFG...",
11. "KeyIsFile":"data:text/plain;base64,SGVsbG8..."
12. }
MQTT Connect
After connecting to the MQTT Broker, the client sends a command message to the broker. If this CONNECT message is malformed (according to the MQTT specification), or if too much time passes between opening a network socket and sending the connect message, the broker terminates the connection. You will be able to connect to MQTT using the following information:
HOST: device-entmagellan.ais.co.th
PORT: 1883 (MQTT), 8883 (MQTTS)
MQTT Broker connection requires the parameters specify each value as follows.
Client ID
Username
Password
#To enable SSL encryption, we need to tell Mosquitto where our Let's Encrypt certificates are stored.
mosquitto_pub -d -h $HOST -p 8883 -u $THING_IDENTIFIER -P $THING_SECRET -t "$TOPIC" -m ' ' --cafile ..\certs\caFile.cer --cert ..\certs\certFile.cer --key ..\certs\key.pem --insecure
#How to Quality of Service (QoS)
mosquitto_pub -d -h $HOST -p 8883 -u $THING_IDENTIFIER -P $THING_SECRET -t "$TOPIC" -m ' ' -q $1
#How to Keep Alive
mosquitto_pub -d -h $HOST -p 8883 -u …
Response Status code
MQTT API provides a response status code for every request to the Server. according to the following table
String format args:
$APIName = The name of the API
$PropertyValue = The current value of the property
$NodeName = The name of Node or Endpoint Name
MQTT Status
Response Result
Authentication
Thing can create connection to platform via CoAP protocol with endpoint coap://device-entmagellan.ais.co.th:5683/ by command Authentication. We will use access token device credentials in this article, and they will be referred to later as $THING_TOKEN . The application needs to include $THING_TOKEN as a path parameter into each CoAP request. Which requesting the $THING_TOKEN the details are as follows.
This request from client-side to server for authentication a thing with $THING_IDENTIFIER and $THING_SECRET. The response result is a $THING_TOKEN. You will be able to retrieve this thing token at send POST request to the following URL:
Format JSON
PUBLISH:
#Publish to server for request authentication thing in json or text/plain format.
TOPIC: api/v2/thing/$THING_IDENTIFIER/$THING_SECRET/auth/req
SUBSCRIBE:
#Subscribes to get the response of authentication thing in json format.
TOPIC: api/v2/thing/$THING_IDENTIFIER/$THING_SECRET/auth/resp
Format Plain Text
SUBSCRIBE:
#Subscribes to get the response of authentication thing in plain text format.
TOPIC: api/v2/thing/$THING_IDENTIFIER/$THING_SECRET/auth/resp/pta
***The publish request of plain text is same the json format.
Example via coap-cli command
Content-Format: application/json
#Response thing token in json format.
1. {
2. "Code":"20000",
3. "ThingToken":"eb498ccb-75a8-xxxx-xxxx-f6fe8f5dc34e",
4. }
Content-Format: text/plain
Report Thing Real Time
This request from client-side for sending the message or sensor to server using the $THING_TOKEN (from the authentication command).
The response result is an operation status code. You will be able to send messages in the format JSON or plain text (pta) by sending a POST request to the following URL.:
Format JSON
PUBLISH:
#Publish to server for report message with multi sensor in json format only.
TOPIC: api/v2/thing/$THING_TOKEN/report/persist
PAYLOAD: {"$SENSOR_NAME":"$SENSOR_VALUE"}
***This command not support plain text format.
PUBLISH:
#Publish to server for report message with a sensor in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/report/persist/pta/?sensor=$SENSOR_NAME
PAYLOAD:$SENSOR_VALUE
SUBSCRIBE:
#Subscribes to get the response of report status in json format.
TOPIC: api/v2/thing/$THING_TOKEN/report/resp
Format Plain Text
SUBSCRIBE:
#Subscribes to get the response of report status in plain text format.
TOPIC: api/v2/thing/$THING_TOKEN/report/resp/pta/+
Example via coap-cli command
Content-Format: application/json
#Response report status in json format.
1. {
2. "Code":"20000",
3. }
Content-Format: text/plain
Report Thing Real Time
This request from the client-side for sending the message or sensor includes$UNIXTS (UnixTimestamp) and$SENSOR in the payload to the server using $THING_TOKEN (from the authentication command).***This command does not support plain.
you will be able to send messages by sending a POST request to the following URL:
Format JSON
PUBLISH:
#Publish to server for report message with timestamp in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/report/timestamp/persist
PAYLOAD: [{"UNIXTS":$UNIXTS ,"Sensor":{"$SENSOR_NAME":"$SENSOR_VALUE"}}]
SUBSCRIBE:
#Subscribes to get the response of report status.
TOPIC: api/v2/thing/$THING_TOKEN/report/timestamp/resp
Example via coap-cli command
Content-Format: application/json
#Response report message status.
1. {
2. "Code":"20000",
3. }
Heartbeat
The Server Client must then send a request with $THING_TOKEN (received by device authentication) to the Server. A message or sensor can be sent to the Server by sending a POST command to the following URL. this
Format JSON
PUBLISH:
#Publish to server for heartbeat in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/heartbeat
***The publish request of plain text is same the json format.
SUBSCRIBE:
#Subscribes to get the response of heartbeat status in json format.
TOPIC: api/v2/thing/$THING_TOKEN/heartbeat/resp
Format Plain Text
SUBSCRIBE:
#Subscribes to get the response of heartbeat status in text/plain format..
TOPIC: api/v2/thing/$THING_TOKEN/heartbeat/resp/pta
Example via coap-cli command
Content-Format: application/json
#Response heartbeat status in json format.
1. {
2. "Code":"20000",
3. }
Content-Format: text/plain
Server Config
The client must subscribe (subscribe) to the server with$THING_TOKEN, which is received by device authentication when all device settings information is required. And when you need some data, you can specify $CONFIG_KEY of the setting data. Then the server will reply with the requested device settings data back.
You will be able to publish device setting data in the format JSON or plain text (pta) by sending a command GET to the following URL:
Format JSON
PUBLISH:
#Publish to server for get all configurations in json only.
TOPIC: api/v2/thing/$THING_TOKEN/config/req
***The publish request support json format only.
#Publish to server for get a configuration in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/config/req/?config=$CONFIG_KEY
SUBSCRIBE:
#Subscribes to get the response of server configurations in json format.
TOPIC: api/v2/thing/$THING_TOKEN/config/resp
Format Plain Text
SUBSCRIBE:
#Subscribes to getting the multi configuration of thing in text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/config/resp/pta/+
#Subscribes to getting the a configuration of thing in text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/config/resp/pta/?config=$CONFIG_KEY
Example via coap-cli command
Content-Format: application/json
#Response multi configuration of thing in json format.
1. {
2. "Code":"20000",
3. "Config": {
4. "Lamp_BedRoom":"OFF",
5. "Lamp":"ON"
6. }
7. }
Content-Format: text/plain
Client Config
The device settings with $THING_TOKEN obtained by authenticating the device, to the Server by sending a GET command to the following URL.device, to the Server by sending a GET command to the following URL.
Format JSON
PUBLISH:
#Publish to server for device configuration in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/config/persist
PAYLOAD: {"$CONFIG_KEY":"$CONFIG_VALUE"}
Example via coap-cli command
Content-Format: application/json
Delta
This request from client-side for getting the sensors of thing shadow from server using the $THING_TOKEN(from the authentication command). The response result returns the values of the specified sensor $SENSOR_KEY. You will be able to get the sensors of thing shadow at send GET request to the following URL:
Format JSON
PUBLISH:
#Publish to server for get all sensor of thing shadow in json only.
TOPIC: api/v2/thing/$THING_TOKEN/delta/req
***The publish request support json format only.
#Publish to server for get a sensor of thing shadow in json or text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/delta/req/?sensor=$SENSOR_KEY
SUBSCRIBE:
#Subscribes to get the response of thing shadow in json format.
TOPIC: api/v2/thing/$THING_TOKEN/delta/resp
Format Plain Text
SUBSCRIBE:
#Subscribes to getting the multi sensor of thing shadow in text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/delta/resp/pta/+
***The publish request of plain text is same the json format.
#Subscribes to getting the a sensor of thing shadow in text/plain format.
TOPIC: api/v2/thing/$THING_TOKEN/delta/resp/pta/?sensor=$SENSOR_KEY
Example via coap-cli command
Content-Format: application/json
#Receive sensors of thing shadow in json format. #Received Subscribe (d0, q0, r0, m0,‘api/v2/things/ 488cf288-xxxx-xxxx-a941-7d0e2d3b8517/ delta/resp
1. {
2. "Code":"20000",
3. "Sensor": {
4. "window":"ON",
5. "lamp":"ON"
6. }
7. }