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 a control 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

A control 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 the control app using a notification. The control 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, the modem firmware may decide to start a session with the AirVantage server. In this case, the notification could also be received, even if the control app has not explicitly called le_avc_StartSession().

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, to allow the control app to make a new decision, or again defer.

Once an update has been downloaded, a new notification will be received to indicate that an install is pending. The control app can then use le_avc_AcceptInstall() to allow the install to proceed. Note that even if the control app calls le_avc_AcceptInstall(), the install may still be blocked by an app using the Application Blocking functions. To defer the decision, the control 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 the control app 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. During an upgrade process the control app has to 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. The control app should start an AirVantage session before accepting an app install/uninstall, to ensure the process is completed, and the server is updated.

If a control app doesn't register 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. Also, only the control app registered for notifications will be allowed to use the other update control API functions.

Only one control app is allowed to register for notifications. Any subsequent attempts by either the same app, or a different app is treated as a fatal error (i.e. non-recoverable) and will result in the client app being terminated.

In case of any error incurred during app download/install, an error code will be set and the control app can retrieve it 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.

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

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.

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.