AAF To AirVantage Tutorial
AAF To AirVantage Tutorial
AAF To AirVantage Tutorial
[7.0]
[August 2014]
Important Notice
Due to the nature of wireless communications, transmission and reception of data can never be
guaranteed. Data may be delayed, corrupted (i.e., have errors) or be totally lost. Although significant
delays or losses of data are rare when wireless devices such as the Sierra Wireless modem are used
in a normal manner with a well-constructed network, the Sierra Wireless modem should not be used
in situations where failure to transmit or receive data could result in damage of any kind to the user or
any other party, including but not limited to personal injury, death, or loss of property. Sierra Wireless
accepts no responsibility for damages of any kind resulting from delays or errors in data transmitted or
received using the Sierra Wireless modem, or for failure of the Sierra Wireless modem to transmit or
receive such data.
The driver or operator of any vehicle should not operate the Sierra Wireless modem while in control of
a vehicle. Doing so will detract from the driver or operator’s control and operation of that vehicle. In
some states and provinces, operating such communications devices while in control of a vehicle is an
offence.
Limitations of Liability
This manual is provided “as is”. Sierra Wireless makes no warranties of any kind, either expressed or
implied, including any implied warranties of merchantability, fitness for a particular purpose, or
noninfringement. The recipient of the manual shall endorse all risks arising from its use.
The information in this manual is subject to change without notice and does not represent a
commitment on the part of Sierra Wireless. SIERRA WIRELESS AND ITS AFFILIATES
SPECIFICALLY DISCLAIM LIABILITY FOR ANY AND ALL DIRECT, INDIRECT, SPECIAL,
GENERAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES INCLUDING,
BUT NOT LIMITED TO, LOSS OF PROFITS OR REVENUE OR ANTICIPATED PROFITS OR
REVENUE ARISING OUT OF THE USE OR INABILITY TO USE ANY SIERRA WIRELESS
PRODUCT, EVEN IF SIERRA WIRELESS AND/OR ITS AFFILIATES HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES OR THEY ARE FORESEEABLE OR FOR CLAIMS BY ANY
THIRD PARTY.
Notwithstanding the foregoing, in no event shall Sierra Wireless and/or its affiliates aggregate liability
arising under or in connection with the Sierra Wireless product, regardless of the number of events,
occurrences, or claims giving rise to liability, be in excess of the price paid by the purchaser for the
Sierra Wireless product.
Copyright
© 2013 Sierra Wireless. All rights reserved.
Trademarks
Sierra Wireless™, AirCard™, AirPrime™, AirLink™, AirVantage™, Watcher™ and the Sierra Wireless
logo are trademarks of Sierra Wireless.
Windows® and Windows Vista® are registered trademarks of Microsoft Corporation.
Macintosh and Mac OS are registered trademarks of Apple Inc., registered in the U.S. and other
countries.
®
QUALCOMM is a registered trademark of QUALCOMM Incorporated. Used under license.
Other trademarks are the property of the respective owners.
1
If you purchased your product from an AirLink Distributor or Reseller, please contact them for
first line technical support.
Consult our website for up-to-date product descriptions, documentation, application notes, firmware
upgrades, troubleshooting tips, and press releases: www.sierrawireless.com
8. APPENDIX ......................................................................................................... 22
8.1. Uncommented source code ............................................................................................ 22
8.2. Full commented source code .......................................................................................... 24
8.3. Link to AAF APIs ............................................................................................................. 27
2. Device Setup
Check that these items have been done:
• Latest Aleos firmware version installed on your device
• Latest Developer Studio for ALEOS installed and Remote Explorer View connected to your
device (Window>Open Perspective>Remote Explorer View).
• With ACEmanager or AVMS:
- enable AAF (menu Applications>Aleos Application Framework)
- enable SNTP (menu Services>Time (SNTP))
3. Platform Setup
Check that these items have been done:
• Device registered and appearing in the monitor tab
• M3DA password has been configured.
You will find the default password on the device locally in ACEmanager, menu
Applications>Aleos Application Framework>Advanced (menu will be available only if AAF has
been enabled). Copy it and paste it in the platform into menu
Inventory>YourDevice>Edit>Credentials(”locker”icon)>M3DA Password, then save.
This step is needed in order to execute the authentication to the platform for the install job in
forth-coming section.
We will now add variables, command, and settings to the Asset Model.
Double click on the “datamodel.data” file in your script explorer view. A new window with the data
model opens. Right click on the Asset Container and select New Child > Asset
Set the Default Label to e.g. "Embedded_App_LoopCount", Description: "Total number of loop
iterations", Path: "uplink.CountPath", Type: "int"
Similarly add a second variable with Path “uplink.FloatingPointPath” and add the info as below:
Add a fourth variable with Path "uplink.StatePath" and add the info as below:
Then select your command by highlighting it, and do right click > New Child and add a command
parameter:
Note the Id of your command parameter which will be part of the command path and allow you to
access it.
Beware that all default values provided in the data model will be only used to populate the
corresponding fields on the platform GUI.
The default values from the data model are not reflected on the LUA script side.
If you need/want to provide default values on the script side, do such in the script as well.
Needed libraries.
- AirVantage Library: contains all the functions that are used for the interaction between the
device and the server.
- Scheduler: allows to execute, call, schedule and link the different tasks related to the
application.
- Device Tree: allows to access to the device parameters. Required in this case for accessing
the asset variables, settings and command.
- System: library needed upon call of restart function.
Main function.
What we want to achieve through this application is collecting locally data into a queue, then sending
this data to the platform at a given period using a policy. This implies 3 things:
- generating data
- collecting data
- creating a custom policy
Generating data:
Generating data is achieved through increment of a counter and generation of a random number.
Note a seed (based on OS time) is used to initialize the random algorithm in order to make it more
robust.
Collecting data is achieved through pushing into a queue the generated data and the fix variables
which do not change upon time (Embedded_App_String and Embedded_App_State).
Note that in order to assign a value to a Variable or a Setting in your application tree you must assign
this value to the corresponding Path in the application tree. For instance in order to give value ‘1’ to
Variable ‘Embedded_App_State’, you must assign this value to the corresponding Variable Path in the
application tree: helloasset.tree.uplink.StatePath = 1. Do not use the Variable/Setting name or
Default Label.
This whole process is done within a “while(true)” loop which makes in sort data is generated and
collected continuously. At the end of each loop a 3 minutes timer is set in order to wait before
triggering the next instance of the loop.
Select “Next” and enter a Package Version. Browse to an output directory, select Finish. This creates
a zip file with the uploadable package, containing script of the application as well as Data Model and
other information pertaining to the communication protocol between the application and the platform.
Click the Release button (blue vertical arrow) to open a dialog box to select your exported package.
A released application is an application loaded on the platform and available in the application list.
Still this application is not available for deployment onto live units. In order to have the application
available in the different menus for attribution to devices, you must publish it.
You can publish the application from the release prompt using the check box available in the
advanced menu, or you can publish it afterwards by selecting your application in the list and using the
Publish button from the main page.
This step can also be executed by simply remotely installing your application from the platform onto
your system (from Monitor tab select “More” button and “Install application”).
If your application contains variables which are not declared in the Data Model or if path provided in
the push API of the script is not matching the one populated in the Data Model, then your
Variable/Setting will not appear in this view.
To access the application view, select your system, then to the bottom of the detail page, browse to
your application and click on the hyperlink.
To create a template go to Configure>Templates tab and hit the “create” button (‘+’ icon).
In the Application/Firmware field start typing your application name and select it and hit “continue”
(note process for template creation is the same for creating a template for an application or an Aleos
FW, hence the common field).
After this you will be prompted to set the value of the Setting(s) available in your application. Populate
the desired value, check the Setting box, and save the template.
Template will now appear in the Template list in Configure>Templates tab.
Template will be applied upon next connection of your system to the platform, as defined in the
Configure Communication menu. Note that in the case your system is equipped with reachable SIM
cards / IPs and you have configured the platform with its IP / FQDN, then template can be
immediately pushed to your device.
Starting Aleos 4.3.6 a dedicated GUI button in AceManager is available allowing to trigger connection
on the fly to the AirVantage platform. Use the connect button in menu Services>AVMS>AAF if you do
not want to wait until next scheduled connection.
In order to check the new applied setting, after the template has been executed either go on the
platform to the configure application view or check on the Studio in the console logs, or in the admin
logs of AceManager, application subsystem.
More information on accessing the console logs and using debug mode can be found at:
http://developer.sierrawireless.com/en/Resources/Resources/AirLink/ALEOS_AF/Tutorial_AAF_Gettin
g_Started.aspx
Upon next connection of the device to the platform, command will be executed. In our case command
will trigger the printing of the Message content onto the console in the Studio (in case application
executed in run mode) or in the AceManager Admin logs if application is installed and running on the
device.
Here again use the connect button in menu Services>AVMS>AAF if you do not want to wait until next
scheduled connection.
----------------------------------------------------------------------------------
local function PrintCallback (assetInstance, commandArgumentsList,
path_commands_PrintMessage)
print ("inside PrintCallback, new message received:")
-- Note the Command Parameter Id (in our case "Message") after argument
"commandArgumentsList"
-- This is the Id as defined in the command parameter of the command, within the
DataModel
print("command message:", commandArgumentsList.Message)
return "ok"
end
----------------------------------------------------------------------------------
local function main ()
dev.init()
sys.init()
helloasset:start()
helloasset:pushdata("uplink", {StatePath=1, timestamp=os.time()}, "now")
math.randomseed(os.time())
while true do
count = count + 1
local randomnumber = math.random()
helloasset:pushdata("uplink", {CountPath=count,
FloatingPointPath=randomnumber,
StringPath= "Hello AirVantage from my embedded app",
StatePath=1,
timestamp=os.time()}, "15mnpolicy")
sched.wait(180)
end
end
sched.run(main)
sched.loop()
local count = 0
----------------------------------------------------------------------------------
----------------
local function PrintCallback (assetInstance, commandArgumentsList,
path_commands_PrintMessage)
print ("inside PrintCallback, new message received:")
-- Note the Command Parameter Id (in our case "Message") after argument
"commandArgumentsList"
-- This is the Id as defined in the command parameter of the command, within the
DataModel
print("command message:", commandArgumentsList.Message)
return "ok"
end
----------------------------------------------------------------------------------
----------------
local function main ()
dev.init()
sys.init()
-- define what the application will do upon reception of command from the
platform
helloasset.tree.commands.PrintMessage = PrintCallback
-- initialize random generator using seed (in this case current time)
-- using a seed will allow generating more undeterministic random value
math.randomseed(os.time())
-- create a cyclic 3 minutes loop in the main which will store data locally
-- and send those data to the platform at the frequency defined in the above
custom push policy
while true do
-- Sleep 3 minutes
sched.wait(180)
end
end
sched.run(main)
sched.loop()
-- Note:
-- if instead of putting the data into a queue for a later flush according
to the set policy,
-- user wants to send all data immediately from all defined queues and not
waiting for the policy defined period, use:
-- airvantage.triggerpolicy("*")