MQTT device management

Initializing Table Of Contents...

Introduction

This page explains how to manage your devices with AirVantage when using MQTT.

You may use MQTT for application communication (pushing values to AirVantage and receiving commands or settings). Most of the time you are using one of our bit-pipe modems (HL) or a legacy 3rd party hardware.

In such case, you need to upgrade the firmware and software (Linux or MCU behind the bit-pipe modem) of your device in order to fix security issues, deploy new features … Implementing an OMA-DM or LWM2M stack is seen as overkill for what is a simple command with a URL to send to the MQTT client.

Let’s outline some simple workflows for managing the firmware/software of devices connected using MQTT.

Software management

Install

You can use AirVantage to send install and uninstall software commands to your MQTT client. Your application model needs to have the device management actions MQTT_SW_INSTALL and MQTT_SW_UNINSTALL. To install an application you must use the application manager MQTT_SW.

<?xml version="1.0" encoding="ISO-8859-1"?>
<app:application 
        xmlns:app="http://www.sierrawireless.com/airvantage/application/1.0" 
        type="com.test.dm.airvantage.app" 
        name="Software Management with AirVantage"
        revision="0.1">
  <capabilities>

    <communication>
      <protocol comm-id="SERIAL" type="MQTT" />
    </communication>

    <dm>
      <action impl="MQTT_SW_INSTALL"/>
      <action impl="MQTT_SW_UNINSTALL"/>
    </dm>
  </capabilities>
 
  <application-manager use="MQTT_SW"/>
</app:application>

For more details about the application model, see: Application model reference .

The AirVantage server sends installation/uninstallation tasks using the {IMEI or SN}/tasks/json topic.

Here’s an example of an install task, using the topic format:

[
   {
      "uid" : "e87b35c3c2e2417b902277ff9d049d70",
      "timestamp" : 1416324560869,
      "swinstall" : {
        "type":"My Application",
        "revision": "1.1",
        "url":"https://eu.airvantage.net/devicev4/dl/b79e1772482b4d70a6bca18c461163d2/4e51d63280b6489a90b3a5c6c75d3189/full.bin"
      }
    },
    ...
]

The command name is swinstall, the arguments are: the application type and the download URL:

type: is the unique identifier of your application. If an application of this type is already installed you must replace it.
revision: the revision of the application to install.
url: the URL for downloading the binary package to be installed.

Success and error must be reported in the same way as for other tasks by publishing on {IMEI or SN}/acks/json.

The application type should be unique per device, so if an application with the same application type is already installed, it should be replaced (upgraded) by the new one.

Uninstall

Here’s an example of the swuninstall command:

[
   {
      "uid" : "e87b35c3c2e2417b902277ff9d049d70",
      "timestamp" : 1416324560869,
      "swuninstall" : {
        "type":"My Application",
      }
    },
    ...
]

If an application of the given type is installed, you must uninstall it and report success/failure on {IMEI or SN}/asks/json.

Software synchronization

Optionally, the device may expose some data about the installed software to the server for synchronizing.

The data DM.SW should contain the list of installed software separated by “;” like: “MYAPP;MONITORING_APP”

The data DM.SW.VER should contain the list of versions corresponding to the installed software separated by “;” like: “123.5.6;v2-beta

Connectivity & device monitoring

With the MQTT protocol you can use JSON messages to publish and subscribe to device data messages. A list of supported data Fields are listed below: