About AirVantage

AirVantage is a very interesting IoT platform from Sierra Wireless. Among the features it exposes, we notably find device management; monitoring and alerts; and data storage capabilities. The platform seamlessly integrates with Sierra devices (gateways and routers) and uses MQTT for communicating with third party hardware. Last but not least, AirVantage also exposes most of its features through an extensive REST API, part of which we wrapped into a connector, described in a dedicated post in this blog.

In the current article, we explain how to use our connector and scriptr.io’s bridges to communicate with your AirVantage devices, through MQTT.

Before we begin

Before learning how to enable MQTT communication between your scriptr.io scripts and your devices on AirVantage, make sure that you have created an account on the latter, as well as a virtual device (if you already have done this or if you actually have physical devices managed by AirVantage, you can skip this section). Otherwise:

Scriptr.io’s bridges to receive MQTT messages

Scriptr.io’s bridges are protocol adapters: they listen to messages sent by clients using one protocol (e.g. MQTT) and inject them into your channels that further dispatch them to all their subscribers.

In AirVantage, a gateway is associated to a topic to which devices can publish data. Subscribing to the topic using scriptr.io’s bridges allows your scripts to receive the data that has been published by the devices, in real time. In order to subscribe to this topic from a bridge, you will need two things:

  • The name of the topic
  • The credentials to use (username and password of the Gateway)

Obtaining the topic name and the MQTT credentials

The name of the topic adopts the following convention: “/messages/json”, whereas the username is the gateway’s serial number and the password is the one set for the application that is automatically allocated to your device, in the AirVantage platform.

To find out what serial number you should use, simply sign-in to your AirVantage account. Once signed-in, click on the “Monitor > System” option in the upper menu. This loads the list of devices you have. From the list, select one device to load its details. From the device details view, click on “More > Edit”.

airvantage_device_detail

In the resulting view, click on “Edit” to get the gateway’s serial number:

airvantage_edit_gateway

Then click on the lock icon near the “Applications” field to get the password:

airvantage_edit_gateway_pwd

Create an MQTT bridge on scriptr.io

To create an MQTT bridge, you first need to configure an endpoint, then assign the endpoint to a bridge you bind to one of your channels. In scriptr.io, a channel is an abstraction of publish/subscribe mechanisms: any message published to a channel – regardless of the protocol initially used to send the message – is broadcast to all its subscribers, whether they are scripts or client applications.

For the following, make sure to sign-in to your scriptr.io workspace before proceeding.

Configure an MQTT endpoint

In your workspace, click on your username in the top-right corner of the screen, then select “settings”. In the settings dialog, click on the “External Endpoint” tab, then on the “+” sign, “Add External Point Configuration”:

  • In the protocol field, select “mqtt”
  • In the name field enter any name
  • In the URL field, enter the URL of the AirVantage MQTT broker, it should normally be “mqtt://eu.airvantage.net” or “mqtt://na.airvantage.net”. Don’t forget to prefix your URL with “mqtt://”!
  • In the Topic field, enter the name of the AirVantage MQTT topic (as described in the above paragraph)
  • Enter any value in the Client Id field
  • In the username field, enter your gateway’s serial number
  • In the password field, enter the password you have copied from the AirVantage account (as described in the above paragraph)
  • Validate your configuration by clicking on the check sign

scriptr_mqtt_endpoint

Link the endpoint to a channel

Once your endpoint is ready, select the channels tab from the settings dialog. If you do not already have a channel, create one by clicking on “+ Add Channel”.

In the channel, select the endpoint you need to use for the bridge from the field on the left, and paste an authentication token in the field on the right. You can use your personal token (Your Username > Account > Token) or any token that was issued for a device you created (You Username > Device directory), but you can’t use your anonymous token. Once this is done, click on “Add Bridge”.

scriptr_mqtt_bridge

Create a script to process the incoming MQTT messages

Once your bridge is ready, it will automatically subscribe to the AirVantage MQTT topic you have specified. As messages are received, the bridge will publish them to the channel it is bound to. In order to process theses messages (e.g. use them in some business process or to feed a dashboard), you need to implement this processing logic into a script that you will subscribe to the channel.

In your workspace, click on “+ New Script” in the bottom left corner of the screen to create a new script. Once your script is subscribed to the channel, it will automatically receive any incoming message along with the request object. A message sent in the JSON format should be obtained using request.body, whereas a text message and/or a stringified JSON is obtained from request.rawBody:

var message = request.body ? request.body : request.rawBody;
// your business logic goes here

To subscribe your script to the channel that is receiving the MQTT messages, the simplest way is to click on the “subscribe” button on the top-right corner of the workspace, scroll to your channel in the channel list, then switch the toggle to “on”.

scriptr_subscribe_channel

Use the connector to send tasks to your AirVantage device

What we have done so far allows you to receive your AirVantage device’s data, as soon as it is available on the AirVantage platform. It is now time to see how to communicate back, notably by sending tasks (instructions) to your device, via MQTT, using the AirVantage connector.

Install the AirVantage connector

Click on the arrow near the “+ New Script” option in the bottom left corner of the screen, then select “Install Module”. If you cannot find “AirVantage” on the list, just click on “Add custom module from Github”, then enter “scriptrdotio” for the Owner name, “airvantage” for the Repository name, “/modules/airvantage” for the path, “master” for the branch and “/modules/airvantage” for the destination folder. Click on install to deploy the connector to your workspace. It will be installed in the “/modules” folder.

Publishing MQTT messages to Airvantage

Once the AirVantage is installed in your workspace, you need to import its “system.js” script into one of your own scripts as follows:

var system = require("/modules/airvantage/system.js");

The system.js module is your main entry point to the AirVantage connector. It notably exposes the “publish()” function that we will use to publish a message to a topic in AirVantage:

// first, create a configuration object
 var someConfig = {
   username:  "", // see "Obtaining the topic name and the MQTT credentials" above
   password: "", // see "Obtaining the topic name and the MQTT credentials" above
   endpoint: "eu.airvantage.net", // usually one of eu.airvantage.net or na.airvantage.net
   deviceId: "", // if using the virtual device, use IMEI (check AirVantage Monitor > System page)
   type: "task" // mandatory when sending a task
 };

// create the Task object
 var task = {
   "write" : [{"machine.status" : "on"}]
 };

// publish the task
var publishTaskResult = system.publish(task, someConfig);