Searching...

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