Searching...

Matching results

MQTT device management

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:

Data	Type	Description	Data	Type	Description
_APN	string limited to 255 char	The APN used by the device	_OPERATOR	string limited to 255 char	The network operator used by the device to communicate
_BYTES_SENT	long	Number of bytes sent by the device	_PACKETS_SENT	long	Number of packets sent by the device
_BYTES_RECEIVED	long	Number of bytes received by the device	_PACKETS_RECEIVED	long	Number of packets received by the device
_CELL_ID	string limited to 255 char	Cell identifier use for the cellular communication	_RSSI	double	The Received signal strength indicator (between -70 and -100)
_ECIO	double	The signal quality (values between -5 and -15).	_RSSI_LEVEL	string	The level of RSSI computed from the raw value: EXCELLENT (min : -70), GOOD (min: -85, max: -70), FAIR (min: -100, max: -85), POOR (max: -100).
_ECIO_LEVEL	string	The level of Ec/Io computed from the raw value: EXCELLENT (min: -5), GOOD (min: -10, max: -5), FAIR (min: -15, max: -10), POOR (max: -15).	_RSRP	double	(LTE only) The Reference Signal Received Power (dBm) - in 1⁄10 dBm.
_ICCID	string limited to 30 char		_RSRP_LEVEL	string	The level of RSRP computed from the raw value: EXCELLENT (min : -90), GOOD (min: -105, max: -90), FAIR (min: -120, max: -105), POOR (max: -120).
_IP_ADDRESS	string limited to 100 char	The IP Address used by the device to communicate with AirVantage	_RSRQ	double	(LTE only) The Reference Signal Received Quality (dB) - in 1⁄10 dB.
_LATITUDE	double	Format: Signed degrees format (DDD.dddd). A latitude with 8 decimal places pinpoints a location to within 1 millimeter,( 1⁄16 inch): Prefix South latitudes with a minus sign. Latitudes range from -90 to 90. Example: 41.25	_RSRQ_LEVEL	string	The level of RSRQ computed from the raw value: EXCELLENT (min : -9), GOOD (min: -12, max: -9), FAIR_TO_POOR (max: -12).
_LONGITUDE	double	Format: Signed degrees format (DDD.dddd). A longitude with 8 decimal places pinpoints a location to within 1 millimeter,( 1⁄16 inch): Prefix West longitudes with a minus sign. Longitudes range from -180 to 180. Example: -120.9762	_SIM_OPERATOR	string limited to 50 char	The operator which provided the SIM
_MOBILE_NUMBER	string limited to 30 char		_SIGNAL_BARS	integer	NO_REPORT(null), NO_SIGNAL(0), VERY_LOW(1), LOW(2), GOOD(3), VERY_GOOD(4), EXCELLENT(5)
_NETWORK_SERVICE_TYPE	string limited to 255 char	Type of wireless service the device uses: “None”, “GPRS”, “EDGE”, “UMTS”, “HSDPA”, “HSUPA”, “HSPA”, “1X”, “EV-DO Rev.0”, “EV-DO Rev.A”, “LTE”, “Unknown”