Matching results

Application Format Reference

This document described AirVantage Application Model.

Initializing Table Of Contents...

Introduction

This document explains how to write an application model used to declare the capabilities of an application to AirVantage.

In order to use an application in AirVantage, an application package must be generated and deployed on the Cloud.

An application is a package (a simple zip file) which contains an application model (the Contract) and binaries for remote update (full binary, delta and/or reverse delta).

You can find sample in the last section .

What is an application package?

An application package is the set of resources required to declare an application and upgrade it for a given version.

To release an application in AirVantage, you need to provide a zip file with:

  1. At least one application model file: extension “.app”
  2. The application model file can reference other files to describe the capabilities to simplify human reading using the directive “include”. This document explains how to write this file.
  3. Zero or multiple binary files with the software images associated with this application.

Want know more about application management ? See Application Management User Guide .

What is an application model?

You can refer to AirVantage user guide to learn more about what an Application means in AirVantage and how it is used: The embedded Application model .

An application model is an XML file defining the communication contract between AirVantage and an embedded application:

  • the protocol to use with the configuration (security). See Communication section protocols for a description.
  • the data and commands supported by the device application. See next section for more information.
  • what manages this application. See section Application manager for a description.
  • the binaries to use to upgrade from an older version to this version. See section Binaries for a description.

General information

The application model is divided in multiple blocks:

Block Description
Header Identify the application
Capabilities

Define the capabilities supported by the application. That means how the application can communicate, the data, event and commands the application handle with, the device management action allowed. More information about this section here .

Binaries Define the software images as binary files to be used to update the application.
Application Manager Define the application manager in charge of the life cycle of this application.

Example:

     <app:application xmlns:app="http://www.sierrawireless.com/airvantage/application/1.0" type="{APPLICATION_TYPE}" name="{APPLICATION_NAME}" revision="{APPLICATION_REV}">
       <capabilities>
         <communication>
           <protocol comm-id="SERIAL" type="M3DA">
             <parameter name="authentication" value="{SECURITY_TYPE}"/>
             <parameter name="cipher" value="{CIPHER}"/>
           </protocol>
         </communication>
         <data>
           <encoding type="M3DA">
             <asset default-label="my Asset" id="theasset">
               <setting default-label="value 1" path="one" />
               <setting default-label="value 2" path="two" />
               <setting default-label="value 3333" path="3333" />
               <command path="simpleCmd" default-label="some testing command">
                 <parameter id="p1" type="string"></parameter>
               </command>
               <command path="complexCmd" default-label="some testing command">
                 <parameter id="param1" type="string"></parameter>
                 <parameter id="param2" default-value="2000" type="int"></parameter>
               </command>
               <command path="open" default-label="Open the door" >
                 <parameter id="openP1" type="int"></parameter>
               </command>
               <command path="slam" default-label="Slam the door" >
                 <parameter id="slamP1" type="int" optional="true" ></parameter>
               </command>
               <command path="close" default-label="Close the door" />
               <setting default-label="value 4" path="four" type="int" />
             </asset>
             <asset default-label="The second asset" id="theasset2">
               <setting default-label="node 1" path="nodeOne" />
               <setting default-label="node 2" path="nodeTwo" />
             </asset>
           </encoding>
         </data>
         <dm>
           <action impl="MIHINI_DM_REBOOT" />
           <action impl="MIHINI_APPCON_INSTALL"/>
           <action impl="MIHINI_ASSET_INSTALL"/>
           <action impl="MIHINI_APPCON_START"/>
           <action impl="MIHINI_APPCON_STOP"/>
           <action impl="MIHINI_APPCON_UNINSTALL"/>
           <action impl="MIHINI_DM_RESET"/>
         </dm>
       </capabilities>
       
       <application-manager use="MIHINI_APPCON" />
      
       <binaries>
         <binary file="binary.tar"/>
       </binaries>
     </app:application>

Header

Identify the application with the following attributes:

  • Name (required): identify the application
  • Revision (required): identify the revision of application
  • Type (required): identify the type of application

The name and type must be unique in AirVantage.

The Revision must be strictly consistent with the revision number declared in the dwl.

Best Practices:

  • Type must be unique in AirVantage. There is a single type for each module application so it should have to be the customer short name with the application short name like SWIR_OpenAT. Don’t hesitate to add your company name for software application.
  • Name: it should be clearer to be application name like Open AT Framework. The name is just used to be displayed on the UI.
  • Revision: this field must be filled with the application version. For Sierra Wireless, it must be consistent with what the FW sent to AirVantage. For Open AT module, you can check with the ati9 command: . (For example: R1.2.0.2014XXXXX).

Capabilities

Define the capabilities supported by the application.

  • Data: used to define the tree of data that can be exchange between the device and the server. More information about this section here .
    • Encoding: used to specify the encoding of all its child nodes. Most of the time, a tree can only be exchanged using one protocol: the element encoding is used to define this protocol.
    • Each node or value is a tree element. A tree element can be:
      • A node which contains other elements below.
      • A setting which allows to configure the device from the server.
      • A variable which contains a data value sent by the device to the server (the server can not modify it).
      • An event
      • A command to be executed on the device side.
  • Communication: capabilities of the application. Includes a list of protocols supported by the application. For each protocol, you can define parameters useful to configure the way the protocol is integrated in the application.
    • MQTT: Default protocol to be used to send your business data on AirVantage.
    • REST: Protocol to be used to send your business data on AirVantage if you don’t care about bandwidth consumption or you want to create a quick Proof of Concept.
    • M3DA (deprecated): used by the AirVantage Agent based on Open source project Mihini - http://www.eclipse.org/mihini/ and ALEOS Application framework.
      • Uses either TCP (44900) or HTTP
    • AWTDA (deprecated): used by user defined applications using the AirVantage Agent on Sierra Wireless Open AT AirPrime modules, AirLink programmable modems.
  • Device Management: supported actions by the application:

Action Icon in the system details toolbar
Reboot

Application install

Application un-install

Application Start

Application Stop

Reset factory default

Wakeup

AT command

Firmware upgrade

Synchronize

Configure Heartbeat

  • Include a file to import capabilities in the current application model
    • file name and extension is free, we recommend to use the extension .cp
<include>
   <file name="myDataModel.cp"/>
</include>

Binaries

Define the software images as binary files to be used to update the application.

Optional and can be multiples. The files have to be provided in the application package (.zip file). The images provided can have the following formats:

  • Full image: can be used to install the application on a system
  • Delta: can be used to upgrade an application already installed sending only the difference (it is independent from the technology used)
    • Can include the reverse delta to enable device auto recovery if the new revision is not stable

The binary node can have the following specific parameters:

Name Default value Comments
file

Required
type FULL Can be FULL or DELTA.
reverse false Define if the binary go back to a previous version or to a next version.
revision

Specify the revision. If reverse is false, the revision defines the source version where the binary can be applied. if reverse is true, the revision defines the final version.

Example for an application model for version 1.0.0:

<binaries>

    <binary file="my_file.bin"/>

    <!-- delta to upgrade from version 0.9 to version 1.0.0 -->

    <binary file="my_delta.tar" type="DELTA" revision="0.9"/>

    <!-- Delta to downgrade from version 1.0 to version 0.9 -->

    <binary file="my_delta2.tar" type="DELTA" revision="0.9" reverse="true"/>

</binaries>

Application Manager

In case your application is using AirVantage Agent (deprecated) or Legato, you have to define the application manager in charge of the life cycle of this application: install, upgrade, start, stop, uninstall.

Optional, if defined, must be one of the Application Manager supported by AirVantage:

  • Mihini application container (MIHINI_APPCON)
  • Open AT application running on AirPrime module using OMA DM protocol (SOFT_IDS)
  • AirVantage Agent running in ALEOS AF (ALEOS_LINUX)
  • Generic MQTT installed software (MQTT_SW)
  • Legato framework LWM2M (LWM2M_SW)

Example:

<application-manager use="LWM2M_SW" />

Available Device management actions break down by Application Manager and Protocol

Application manager READYAGENT_APPCON SOFT_IDS MIHINI_APPCON MQTT_SW LWM2M_SW
Protocol AWTDA2_HTTP OMADM_HTTP M3DA_TCP MQTT LWM2M
Install READYAGENT_APPCON_INSTALL

MIHINI_APPCON_INSTALL MQTT_SW_INSTALL LWM2M_SW_UPDATE
Uninstall READYAGENT_APPCON_INSTALL

MIHINI_APPCON_INSTALL MQTT_SW_UNINSTALL LWM2M_SW_UNINSTALL
Start READYAGENT_APPCON_START

MIHINI_APPCON_START

LWM2M_SW_START
Stop READYAGENT_APPCON_STOP

MIHINI_APPCON_STOP

LWM2M_SW_STOP
WakeUp READYAGENT_DM_CONNECT

Reboot READYAGENT_DM_REBOOT

MIHINI_DM_REBOOT

LWM2M_REBOOT
Synchronize READYAGENT_DM_SYNCHRONIZE

MIHINI_DM_SYNCHRONIZE

LWM2M_SYNCHRONIZE
Configure READYAGENT_CONFIGURE_HEARTBEAT

MIHINI_CONFIGURE_HEARTBEAT

LWM2M_CONFIGURE_HEARTBEAT
Reset to factory default

MIHINI_DM_RESET

LWM2M_RESET

Communication section protocols

MQTT

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

AWTDA

<protocol comm-id="IMEI" type="AWTDA2" >
    <parameter name="sms-binary" value="false" />
</protocol>

sms-binary must always be at false.

M3DA

<protocol comm-id="IMEI" type="M3DA" >
    <parameter name="authentication" value="HMAC-MD5" />
    <parameter name="cipher" value="aes-ctr-128" />
</protocol>

Note: Here the following list you can define for encryption and authentication:

  • AUTHENTICATION_TYPE = hmac-md5 or hmac-sha1 or none (if you select none for authentication, you must select none for encryption).
  • ENCRYPTION_TYPE = aes-cbc-128 or aes-cbc-256 or aes-ctr-128 or aes-ctr-256 or none.
TOP