ALEOS AF AirVantage Application Services

Jun 26, 2012 - Author: Sierra Wireless - 3937 Views

Introduction

The ALEOS Application Framework provides the means to create embedded applications that run inside ALEOS devices. These embedded applications can interact with the ALEOS parameters and can access attached devices or assets. In the ALEOS AF, the AirVantage library provides access to the AV Application Services. These services provide the means to send data from the embedded application to the AV server, and from the server to the embedded application to set variable values on the device and send commands to be executed on the device.
Data models are used to define the data types and the commands used in the interchange between the embedded application and the server.

 

Initializing the AirVantage Library

The AirVantage library must be included in the application using the require feature. This makes the library functions available to the application.

local airvantage = require 'airvantage'

Then the library must be initialized using the init() function:

airvantage.init()   -- Initialize the library

Next an asset instance of the library is created with the newAsset('id') function, where the id argument is a string.

myAsset = airvantage.newAsset('newassetid')
Note
The names myAsset and newassetid are arbitrary and can be named however desired. But newassetid must be the same ID string entered in the data model in the Asset's ID.

Next the newly created instance, myAsset, must be registered with the ReadyAgent using the start() function.

assert (myAsset:start(), 'Can't register the Agent')
  • The assert function will catch an error, if one occurs, and print the trailing error message.

 

Data Model

In order to handle data and commands between the application and the server, a data model is required to define each variable or command. A data model is created using the Developer Studio for ALEOS. See the Developer Studio for ALEOS User Guide and the AirVantage ALEOS AF Tutorial for examples of using the IDE to create data models.

  • When a new data model is created, it will create an Asset Container.
  • In that Asset Container, a New ChildAsset can be created.
  • In that Asset's properties' view, entries for the Default Label and the Id can be entered.
    Note
    The Id string must be the same as what is entered for the newassetid in the newAsset statement above.
  • A New Child can be added to this Asset
    • There are 4 types of Asset children:
      1. Setting - Variables that can be set or written to from the server
      2. Variable - Data that will be sent to the server
      3. Command - Commands are sent from the server to be executed in the application
      4. Node - Adds a branch to the Asset to which more children can be added

        Child Properties

  • Setting
    • Default Label - The name for this setting
    • Default Value - Initial value
    • Description - The description of this setting
    • History - all, last, or change
    • Path - Path for this setting, e.g., "downlink.name"
  • Variable
    • Default Label - The name for this variable
    • Description - The description of this variable
    • History - all, last, or change
    • Path - Path for this variable, e.g., "uplink.name"
    • Type - Variable type: string, int, double, date, boolean, or binary
  • Command
    • Default Label - The name for this command
    • Description - The description of this command
    • Path - Path for this command, e.g., "name"
      Note
      It is not necessary to use "commands.name" in the path
      The server prepends "commands" to "name" when the command is sent from the server.
  • Command Parameters - can be added to Command types
    • Default Label - The name for this parameter
    • Default Value - Initial value
    • Id - String for the parameter ID
    • Optional - Whether this parameter is optional "true" or required "false"
    • Type - Variable type: string, int, double, date, boolean, or binary
  • Node
    • Default Label - The name for this node
    • Description - The description of this node
    • Path - Path for this node
    • Reset - Whether to reset children under this node to defaults true, false

 

Asset Tree Paths

All data elements, either sent to the server or received from the server, are identified by a path in the asset's data tree. The root of the path is the application's asset instance. If the asset instance is created with the following:

myAsset = airvantage.newAsset('newassetid')

then newassetid is the root of the tree, and is always implied in a path, so it is not necessary to specify, e.g., newassetid.uplink.xyz, instead uplink.xyz is all that is required.

 
 

Sending Data to the AV Server

The simplest way to send data to the server is to use the pushData function for sending "undeclared" data. There is no need to establish the path and name of a data element before using it in the pushData statement in the application. However, it is necessary for each data element and its path to be entered into the data model in order for the data elements to be utilized in the server. So, in a sense, the data elements are being declared in the data model.
The pushData function has the following form:

myAsset:pushData (path, data, sendpolicy)
where:
path is the path relative to the myAsset's root. path can be omitted in the statement using the empty string "", in which case, the data is stored at myAsset's root with no path.
data is the table containing the data set to be sent. The table may contain one or more elements.
sendpolicy defines when to send the data. See below for a discussion of send policies.
 

pushData Examples

  • Send myAsset.info.x=1, myAsset.info.y=2
    myAsset:pushData ('info', {x=1, y=2})
  • Send myAsset.info.x=1 using the "now" sendpolicy
    myAsset:pushData ('info.x', 1, 'now')
  • Send data elements in myAsset.uplink path using the "hourly" sendpolicy
    local uplinkData = {MessageCount=count, FloatingPoint=randomnumber, String=stringvalue, timestamp=os.time()}
    	myAsset:pushdata ("uplink", uplinkData, "hourly")
  • Send myAsset.x=3 using the default sendpolicy
    myAsset:pushData ("", x=3)

Sending Policies Control When Data is Sent to the Server

Send policies determine when data will be sent to the server. Usually, there is a set of send policies that are included in the default configuration. These are:

  • "default" is manual which is only sent when requested using triggerPolicy
  • "ondemand" is also manual
  • "never" is also manual
  • "now" is usually within 5 seconds
  • "hourly" will connect at least once per hour
  • "daily" will connect at least once per day

Sending can be forced at any time with the triggerPolicy function. It has the form:

myAsset.triggerPolicy(policy)
  • Will force sending of the data attached to the specified policy
  • If policy is "*", then all policies are flushed.

 

Receiving Data Elements

Data sent from the server will be written into an asset's data tree under the designated path. If a function is found in the designated path, that function will handle the data, otherwise, the data element is written into the data tree. These functions in the data tree are called "data handlers".

Data Handlers

Data handlers are functions that will handle the data sent by the server. The handler will handle all data elements in the path at its level and below it. For example, if a handler, handleDownLink is registered at:

myAsset.tree.downlink = handleDownLink

Then the handleDownLink function will be called when either of the following are written to from the server:
myAsset.tree.downlink.x1
	myAsset.tree.downlink.next.y2

More typically, the handler will be at a single element:

myAsset.tree.downlink.x1 = Handle_x1

The handlers have the form:

local function Handle_x1 (assetInstance, value, path)
  • Where assetInstance is the asset instance.
    value is a table containing one or more key/value pairs. The key would be the relative path from the node where the handler is attached for values further down the path.
    path is where the handler is attached.
  • The handlers must return "ok" or 0 to note success, or a non-zero status code followed by an error code to signal failure.

 

Register Data Elements and Handlers

Individual data elements and handlers need to be registered in the asset's data tree before starting the asset. Note the order in the example below:

local airvantage = require 'airvantage'
	airvantage.init()   -- Initialize the library
	myAsset = airvantage.newAsset('newassetid')

	-- Register the data path elements before starting the asset
	myAsset.tree.downlink = {}
	myAsset.tree.downlink.Var1 = var1CallBack  -- where var1CallBack is a function

	myAsset:start()
 

Receiving Commands

Commands may be sent from the server to be executed in the application. Commands are simply functions installed on the special path myAsset.tree.commands where myAsset is the current asset instance. The commands functions have the same form as the handlers:

local function CommandX (assetInstance, value, path)
  • Where assetInstance is the asset instance.
    value is a table containing one or more key/value pairs.
    path is where the command is attached.
  • The command functions must return "ok" or 0 to note success, or a non-zero status code followed by an error code to signal failure.
  • Similar to the handlers, the commands must be registered prior to starting the asset.
    myAsset.tree.commands.DoSomething = DoSomethingCallBack
    	myAsset:start()

Comment

Related items

ALEOS Application Framework
ALEOS Application Framework (AAF) provides developers a complete set of building blocks and tools for creating applications that run inside Sierra Wireless AirLink Gateways. AAF extends the proven ALEOS built-in embedded intelligence and integrates with the AirVantage Cloud Platform in order to offer developers and customers a platform for creating tailored end-to-end M2M solution.
ALEOS AF AirVantage Hello World Code Sample
This code sample demonstrates how to exchange data with the AirVantage Cloud Platform
ALEOS AF with AirVantage Tutorial
This tutorial will guide you in creating an ALEOS AF application that leverages the AirVantage Application Services platform to transmit, receive and remotely store data
©2017 Sierra Wireless. All rights reserved.
×
Get updates on this product
You have been successfully subscribed to this product. To access your subscription click here.
You have been successfully unsubscribed to this product. To access your subscription click here.