Enable a connection to AirVantage using MQTT
Searching...
This article explains the different steps to enable AirVantage connection for any device using MQTT.
Step 1: Setup Hardware
- Plug the device to USB.
- Set up Internet on your device with an ethernet cable.
- Install the device developer tools
Step 2: Design your application
An application model aims to explain to AirVantage how to deal with the device about communication and authentication and managing the data: variable, settings or commands. If you don’t supply such information, the server will ignore all the communication from your device.
The first step to create the application model is to create a file named model.app with the following content. You just need to change the type value with a unique identifier for your application and the name and revision with the apprioriate value for your use case.
- First of all, to be able to send and receive data, you have to describe your data to AirVantage. Here is the description, you just need to change the type value with a unique identifier for your application and the name and revision with the appropriate values for your use case.
- You can modify the
<data>area. Once it matches your needs, save everything as model.app.
Don’t modify the asset id as it is used in the code source application or modify it accordingly
<?xml version="1.0" encoding="ISO-8859-1"?>
<app:application
xmlns:app="http://www.sierrawireless.com/airvantage/application/1.0"
type="com.demo.airvantage.app"
name="Generic Greenhouse"
revision="1.0">
<capabilities>
<communication>
<protocol comm-id="SERIAL" type="MQTT" />
</communication>
<data>
<encoding type="MQTT">
<asset default-label="Greenhouse" id="machine">
<variable default-label="Temperature" path="temperature"
type="double"/>
<variable default-label="Luminosity" path="luminosity"
type="double"/>
<setting default-label="Threshold" path="threshold"
type="int"/>
</asset>
</encoding>
</data>
</capabilities>
</app:application>
Edit your system
- Go to Monitor > Systems
- Select your system and click on the Edit icon
Search your application
- Click on Search application
- In the new dialog box, select the My Application tab
- Search your application using its name (Generic Greenhouse)
Associate your application to your system
- Click on the application to select it.
- Click on the padlock and configure the password.
- Click on Save in the right top corner
Step 3: Implementing an application
Once your device is registered in AirVantage, you can start developing the embedded application that will use the MQTT protocol to communicate with AirVantage. You can use several MQTT clients to develop the embedded client: Paho , MQTT for node . Here are the different calls to integrate in the embedded application to send and receive data with AirVantage:
Server
AirVantage exposes an MQTT broker on the default MQTT port (1883). It means that if you are connecting managing your device through https://na.airvantage.net, you will need to connect to the broker
at the following URL: tcp://na.airvantage.net:1883.
Authentication
The MQTT protocol support on AirVantage uses Username and Password to authenticate devices. So you need to specify the username and the password when you connect the client to the broker (AirVantage). The username is the serial number of the gateway in AirVantage and the password is the one set during the creation of the system.
You can check the device is connected on AirVantage by checking the timeline from the System Details view. For each connection, you should see a new line with 0 data.
Send data to AirVantage
You can publish on the <username>/messages/json topic to send your data to AirVantage, where the username is the is the serial number of the gateway in AirVantage. The data shall be encoded
in JSON using the same format as the one used by the REST API for devices: a message can contain several data and several datapoints for one data. Then you can easily send a complete status or
historical values in one message.
Note: you must be consistent between the serial number supplied on AirVantage, in the username and in the topic name below.
Publish on the <username>/messages/json topic
[
{
"machine.temperature": [{
"timestamp" : 1349907137,
"value" : "23.2"
},
{
"timestamp" : 1349908137,
"value" : "24.5"
},
{
"timestamp" : 1349909137,
"value" : "22.9"
}]
},
{
"machine.threshold": [{
"timestamp" : 1349907137,
"value" : "30"
}]
}
]
This message sends 3 values for the temperature with different timestamp and one value for the threshold parameter.
Timestamp must be in ms.
Once AirVantage receives this message, data is stored and can be accessed by the Data API on System (Last datapoints, Historical aggregated datapoints, Historical raw datapoints, Export datapoints).
The timestamp values are optional. When the server will received the values, it will add a timestamp. The format is
{ "machine.temperature": 23.2, "machine.humidity": 70 }
How to check your communication?
If your payload is not well-formed, your communication won’t be displayed in the timeline at all. Check it by using online json chcker & formater.
Receive tasks from AirVantage
A device can not only push data to AirVantage but you can also use AirVantage to subscribe to new tasks to be executed. Currently the MQTT protocol supports 2 kinds of tasks: read and write.
A read task requests the device to send back to the server the current values for a set of data. It’s a way for a user to request the device to “refresh” the value of a data on the server. This operation is only for variables and settings. To create this operation from AirVantage API, you need to call the “Retrieve data” API (see documentation of System API).
A write task requests the device to change the value of a data locally on the device. It’s a way to interact with the device and change the behaviour of the embedded application. This operation is only available for settings. To create this operation from AirVantage API, you need to call the “Apply settings” API (see documentation of System API).
The device needs to subscribe to the <username>/tasks/json topic, where the username is the is the serial number of the gateway in AirVantage.
Payload received from a subscription to the <username>/tasks/json topic
[
{
"uid" : "3c12547b613740adb686271bdc8f097c",
"timestamp" : 1348836320188,
"read" : ["machine.temperature"]
}
]
Or
[
{
"uid": "8006cc58ba2141f69161a78f1bfdea1d",
"timestamp": 1348836320566,
"write" : [{"machine.threshold" : 25}}]
}
]
Or
[
{
"uid": "8006cc58ba2141f69161a78f1bfdea1d",
"timestamp": 1348836320566,
"command" : {id: "machine.toggleOn", params: {"light": "On", "water": "On"}}
}
]
In this example, AirVantage is asking to the device to send the current temperature and requests to change the value of the threshold to 25. Once the API is called, AirVantage assumed the tasks have been retrieved by the device and then acknowledge automatically the tasks. In the current example, the device will probably directly call the message API to send back to AirVantage the last value of the temperature.
Acknowledging incoming commands
Upon receiving an incoming MQTT command (sent by AirVantage), the device shall return an acknowledge message. This latter must enclose “uid” and “status” keys, the optional “message” key may be provided. Below is a sample ack message to the incoming message as shown in the previous section.
[{
"uid":"8006cc58ba2141f69161a78f1bfdea1d",
"status":"OK"
}]
This ack message is JSON encoded and must be published to {IMEI or S/N}/acks/json topic:
* *uid* is the unique id of the incoming MQTT command to be acknowledged
* *status* being OK or ERROR
* optional *message* key may be included to provided information on the error
Next Step
Continue the tutorial by using tools supplied by AirVantage to test your communication with your device.