AirVantage Data

API Reference
How To Manage Data

This API provides a data service to allow apps to manage app-specific data on the AirVantage server.

Data is setup as assets -- a collection of fields that can be managed by the AirVantage server.

An asset field is a single piece of information that can be managed by the AirVantage server. There can be multiple fields in an asset.

A field can be:

  • variable allows an app to set the value, and can be read from the AV server.
  • setting allows the AV server to set the value, and can be read by an app.
  • command allows the AV server to invoke a command or function in the app.

All fields have names. Variable and setting fields also have a type. The possible field types, along with the default value are:

  • string (empty string)
  • integer (0)
  • float (0.0)
  • boolean (false)
  • binary (zero-length block).

Default values can be overwritten in the asset definition. Currently, string, integer, float and boolean fields are supported; binary fields will be supported in the future.

Asset Data Instances

An app that needs to send data to the AirVantage server must first create an asset instance using le_avc_Create() with the name of the asset definition. Once an asset instance is created, the app can begin accessing the instance's fields.

Multiple instances of the same asset can be created, as well as multiple instances of different assets.

Asset definitions are specified in the assets section of the app's cdef file.

Field Values and Activity

Set functions are available to set variable field values. Get functions are available to get settings fields' values.

An app can register a handler so that it can be called when activity occurs on a field. This is optional for variable and setting fields, but is required for command fields.

  • variable called when the field is read by the AV server. The app can then call the appropriate set function to provide a new value for the field.
  • setting called when the field has been updated by the AV server with a new value. The app can use the appropriate get function to retrieve the new value.
  • command called when the AV server wants to invoke a command. The app should perform an appropriate action or call a function to execute this command.

Read action handlers are only called when the server performs the read on a specific field of an asset instance. i.e, a handler registered on a variable field will be called if the server reads only that field; it will not be called when the server reads the whole instance of an asset. Write action handlers are called on write to asset instance or individual fields.

An app can request to open avms session and register a handler to get notified of avms session events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to open an avms session and close an avms session respectively. If the session was initiated by an user app, avms session will be closed when all apps release their session reference. le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add and remove notification handlers.

Leaving it optional to register handlers for variable and setting fields allows an app to decide how it wants to access variable and setting fields. It can decide to only do something in response to the AV server, or it can work independently of the AV server updating variables when it has a new value, and reading settings only when it needs the value.

Observe

If the Observe is enabled, the AirVantage Server will send observe requests on all user-defined assets of an app.

Whenever an app (asset) changes a field value by using le_avdata_Set*(), it'll trigger a notify if Observe is enabled on that asset. The notify contains only the value of the changed field.

Time Series

Time series is an AirVantage-specific LWM2M feature built on top of LWM2M Observe. This feature enables user apps to collect sensor data when the device is offline. You control starting and stopping time series data on a resource through the user app. le_avdata_StartTimeSeries() starts time series data on a resource, and le_avdata_StopTimeSeries() stops collecting time series data on a resource. User apps can open an avms session, and push the collected history data using le_avdata_PushTimeSeries().

The buffer size allocated for history data per resource is 1024 bytes. Bytes transmitted over the air can be reduced by choosing an appropriate factor. For example, if the sampled integer data is a multiple of 1000, the encoded data will be smaller if a factor of 0.001 is used. For float fields, if a factor other than 1 is used, the data will be encoded as integer to save bytes transported over the air. For example, if the resolution of float data is 0.01, a factor of 100 can be used to represent .01 as 1, and encoding this as integer thus saving memory.

Note
System time is used as timestamp for history data in le_avdata_Set*(). It's up to the target device administrator to ensure system time is up-to-date before starting time series. Alternatively, le_avdata_Record*() can be used to pass a user-specified timestamp.

le_avdata_RecordInt(), le_avdata_RecordFloat(), le_avdata_RecordBool() and le_avdata_RecordString() can be used to pass an user specified time stamp. The user specified time stamp must be in milli seconds elapsed since epoch.

Note
Observe has to be enabled on the resource before time series can be pushed out. User apps can use le_avdata_IsObserve() to know if Observe is enabled on a resource.
LEGATO_FEATURE_TIMESERIES is enabled by default for all WP products. The time series feature depends on the cbor libraries in yocto. Hence, yocto image has to be updated on the device together with the legato image. Users who want to update legato only without the Yocto image should turn off time series in targetdefs.

Fatal Behavior

An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable) and will result in the client app being terminated.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.