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:

At least one application model file: extension “.app”
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.
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>

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.

Matching results