AirVantage Connector

Type/Function Reference
Air Vantage Platform Service

The AirVantage connector service provides an API to communicate with the AirVantage server.

Firmware/Application Update

The API for firmware/application update is divided into two parts:

  • Allow an app to contact the server for pending updates. If available, can select to download or install the update.
  • Allow an app to block an update from being installed. An app may need this if it's performing a critical operation that can't be interrupted (e.g., eCall). This is necessary as installing an update will cause the app to restart (either the app itself needs to restart or a firmware change causes the modem to reset).

Update Control

Any app can start a session with an AirVantage server to determine if there is a pending update. This is done with le_avc_StartSession(). The current session can be stopped using le_avc_StopSession(). This cancels any query for pending update, or suspends a download in progress; however, it won't stop an install in progress.

The status of a pending update is sent to all apps registered for receiving a notification. An app can use le_avc_AddStatusEventHandler() to register a handler function to receive this notification. The notification will be received after a session is started using le_avc_StartSession(). Sometimes, avcService may decide to start a session with the AirVantage server; for instance if a call to le_avc_AcceptDownload() when the session is stopped, avcService will open a session to proceed with the download. In this case, a session started notification could also be received, even if le_avc_StartSession() is not called explicitly.

There can only be one pending update. To query the type of update, use le_avc_GetUpdateType(). If it's an app update, then le_avc_GetAppUpdateName() can be used to get the name of the app.

If a download is pending, then le_avc_AcceptDownload() can be used to allow the update to be downloaded. If this API is called while no AirVantage session is active, calling this API will initiate an AirVantage session. To defer the decision, le_avc_DeferDownload() can be used to defer the download for the specified number of minutes. After the defer time has elapsed, the pending download notification will be re-sent again to all registered apps.

Once an update has been downloaded, a new notification will be received to indicate that an install is pending. Apps can then use le_avc_AcceptInstall() to allow the install to proceed. Note that even if an app calls le_avc_AcceptInstall(), the install may still be blocked by another app using the Application Blocking functions. To defer the decision, an app can use le_avc_DeferInstall() to defer the install for the specified number of minutes. After the defer time has elapsed, the pending install notification will be re-sent to allow apps to make a new decision, or again defer.

If an uninstall is pending, then le_avc_AcceptUninstall() can be used to allow the uninstall to proceed. To defer the decision, le_avc_DeferUninstall() can be used to defer the uninstall for the specified number of minutes. In case of an upgrade, the existing application will not be uninstalled after le_avc_AcceptUninstall() is called. le_avc_AcceptUninstall() is only used to signal the server to start downloading the new application. To proceed with an upgrade process, accept the uninstall of the existing version followed by accepting the download and install of the new version.

Accepting an app install or uninstall will not initiate an AirVantage session if no session is active. An app should start an AirVantage session before accepting an app install/uninstall, to ensure the process is completed, and the server is updated.

If no app has registered for notifications using le_avc_AddStatusEventHandler(), then any pending downloads and installs will happen automatically, subject to any restrictions imposed by app using the Application Blocking functions.

There is no restriction on the number of apps registering for notifications.

In case of any error incurred during app download/install, an error code will be set which can be retrieved by calling le_avc_GetErrorCode().

Application Blocking

When an app is about to perform a critical operation, it can block the installation of an update with le_avc_BlockInstall(), and after it's finished with the critical operation, it can unblock the install with le_avc_UnblockInstall().

What constitutes a critical operation depends on the app. An eCall app might block installs for the duration that it runs. A data collection app that wakes up once an hour might block installs while it collects and stores and/or transmits a new data sample, and then unblock installs just before it goes to sleep again.

If an install can't be applied because it's blocked, another attempt to apply the install will be made at a later time.

An app can add a session control handler using le_avc_AddSessionRequestEventHandler(). Requests by user apps to open or close session will be forwarded to the session control handler. If no app has registered a session request handler, avc session can be opened or closed anytime by user apps.

Polling Timer

The embedded module will periodically initiate a connection to the Device Services server according to the polling timer. The device initates the connection periodically, so that it can poll the server if there are any pending jobs. Writing 0 to the polling timer disables polling mode. Polling timer values range from 0 to 525600 minutes. The polling timer value is persistent. le_avc_GetPollingTimer() reads the polling timer and le_avc_SetPollingTimer() writes the polling timer.

Retry Timers

Warning
This API should not be used for new applications and will be removed in the future

If an error occurs during a connection to the Device Services server (WWAN DATA establishment failed, http error code received), the embedded module will initiate a new connection according to the values defined in the retry timers. The timers are tried in sequence until a connection is established, or all enabled retry timers are exhausted. After all the enabled timers are exhausted, a connection will be initiated only on a command from user (le_avc_startSession() ) or at the expiry of the polling timer. The retry timer values are persistent. Writing 0 to one of the retry timers will disable it. Retry timer values range from 0 to 20160 minutes. The api le_avc_GetRetryTimers() reads the polling timers in an array and the api le_avc_SetRetryTimers() writes the polling timers. When writing to the retry timers, values of all the 8 timers have to be defined.

Device reboot

The AirVantage server can request to reboot the device: in this case a notification is sent to registered apps, which can either accept the reboot with le_avc_AcceptReboot() or defer it for the specified number of minutes with le_avc_DeferReboot(). After the defer time has elapsed, the pending reboot notification will be re-sent, to allow the registered app to make a new decision or defer again.

If no app has registered for notifications using le_avc_AddStatusEventHandler(), then any pending reboot will happen automatically.

Connection required

The AirVantage agent can request a connection to the AirVantage server, especially when a firmware package was installed (after a platform reboot). In this case a notification is sent to the control app, which can start the connection with le_avc_StartSession().

Service Configuration Tree

The configuration database path for the modemActivityTimeout is: 

/
    apps/
        avcService/
                 modemActivityTimeout

After an AirVantage session is started, if there's no activity from the modem within the timer interval, then LE_AVC_NO_UPDATE state will be returned to the app. However, this modem activity timeout can be overridden by setting an integer value at /apps/avcService/modemActivityTimeout. The modem activity timer is initialized only when the avcService starts. If a valid entry >0 is found, then it will be used instead of the default value of 20 seconds. The following steps should be used to set the modemActivtyTimeout.

config set /apps/avcService/modemActivityTimeout xx
app restart avcService
Note
Everytime a new value is written to modemActivityTimeout, the avcService needs to be restarted to read the new value.

Copyright (C) Sierra Wireless Inc.