AirVantage Connector API

API Reference
AirVantage Connector Platform Service

The AirVantage connector service provides an API to communicate with the AirVantage Server to download and install updates.

Firmware/Application Updates

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.

Example of registering an AVC handler and starting a session with fault checking: 

// Start AVC Session
LE_INFO("AirVantage Connection Controller started.");
le_avc_AddStatusEventHandler(avcStatusHandler, NULL);    //register a AVC handler
 
//Start AVC session. Note: AVC handler must be registered prior starting a session
le_result_t result = le_avc_StartSession();
if (LE_FAULT == result)
{
    le_avc_StopSession();
    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.

Pending Updates

There can only be one pending update at a time. To query the type of update, use le_avc_GetUpdateType(). App updates can call le_avc_GetAppUpdateName() to retrieve the App name.

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.

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.

switch (updateStatus)
     {
         case LE_AVC_DOWNLOAD_PENDING:
             LE_INFO("Accepting %s update.", GetUpdateType());
             res = le_avc_AcceptDownload();
             if (res != LE_OK)
             {
                 LE_ERROR("Failed to accept download from AirVantage (%s)", LE_RESULT_TXT(res));
             }
             break;
 
         case LE_AVC_INSTALL_PENDING:
             LE_INFO("Accepting %s installation.", GetUpdateType());
             res = le_avc_AcceptInstall();
             if (res != LE_OK)
             {
                 LE_ERROR("Failed to accept install from AirVantage (%s)", LE_RESULT_TXT(res));
             }
             break;
 
         case LE_AVC_UNINSTALL_PENDING:
             LE_INFO("Accepting %s uninstall.", GetUpdateType());
             res = le_avc_AcceptUninstall();
             if (res != LE_OK)
             {
                 LE_ERROR("Failed to accept uninstall from AirVantage (%s)", LE_RESULT_TXT(res));
             }
             break;
 
         case LE_AVC_REBOOT_PENDING:
             LE_INFO("Accepting device reboot.");
             res = le_avc_AcceptReboot();
             if (res != LE_OK)
             {
                 LE_ERROR("Failed to accept reboot from AirVantage (%s)", LE_RESULT_TXT(res));
             }
             break;
 
         default:
             // No action required
             break;
     }
Note
that even if an App calls le_avc_AcceptInstall(), the install may still be blocked by another App using the Application Installation 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.

Accepting Installs/Uninstalls

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 Installation 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 Installation 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.

Timers

Poling timers sets the time that the Target will communicate with the AirVantage Server to check for new jobs. Retry timers will try and re-establish a connection to the AirVantage Server in accordance with the times that are declared.

Polling Timer

The target will periodically initiate a connection to the AirVantage Server according to the settings for the polling timer to check if there are any pending jobs.

If you need to disable the poling timer call le_avc_SetPollingTimer() and set the value to 0.

The polling timer accepts ranges from 0 to 525600 minutes and is persistent across reboots and upgrades.

To read the polling timer call: le_avc_GetPollingTimer()

To write a new value to the polling timer call: le_avc_SetPollingTimer()

Retry Timers

If an error occurs during a connection to the Device Services server (WWAN DATA establishment failed and an http error code is 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 new session must be initiated again by calling le_avc_startSession() after the expiry of the retry timer.

The retry timer values are persistent (reboots and updates do not effect the retry timers). If you wish to disable a retry timer set the timer value to 0. You must always pass in at least 8 values to the retry timers.

Retry timer values range from 0 to 20160 minutes. The function le_avc_GetRetryTimers() reads the retry timers in an array and the function le_avc_SetRetryTimers() writes the retry timers. When writing to the retry timers, values of all the 8 timers have to be defined.

Example of calling retry timers, the session will be retried after 15 minutes, 1 hour, 4 hours, 8 hours, 1 day and 2 days, the last two retries are disabled: 

uint16_t RetryTimers[LE_AVC_NUM_RETRY_TIMERS] = {15, 60, 240, 480, 1440, 2880, 0, 0};
le_avc_SetRetryTimers(RetryTimers, LE_AVC_NUM_RETRY_TIMERS);

Device reboot

The AirVantage server can request to reboot the device. If a reboot is requested a notification is sent to the registered Apps. The App can either accept the reboot with le_avc_AcceptReboot() or defer it for a specified number of minutes with le_avc_DeferReboot(). After the defer time has elapsed, the pending reboot notification will be re-sent. This allows the registered app to make a new decision or defer the reboot again.

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

Credential Status

The device is provisioned with bootstrap credentials from factory. The Device Management (DM) credentials are provisioned by AirVantage Bootstrap Server. This API is used to retrieve the status of credentials provisioned on the device.

Connection required

The AirVantage agent can request a connection to the AirVantage server, especially when a firmware package is 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().

Data routing

By default the AirVantage connection uses the default mobile data profile and the default route set by the data connection service.

If the user wishes to control the network configuration, e.g. to use the AirVantage agent with multi-PDP contexts, they should first bind the application to the data connection service: 

bindings:
{
   clientExe.clientComponent.le_data -> dataConnectionService.le_data
}

The data connection service should then be configured before launching the AirVantage connection:

  • le_data_SetCellularProfileIndex() allows to change the data profile to use.
  • le_data_GetDefaultRouteStatus() indicates if the default route is activated in the data connection service. This default route can be deactivated in the data connection service configuration database, as explained in Default route. If the default route is deactivated, the AirVantage agent will automatically add routes to be able to reach the AirVantage server through the connection used by AirVantage.

Service Configuration Tree

The configuration database path for the activityTimeout is: 

/
    apps/
        avcService/
                 activityTimeout

After an AirVantage session is started, if there's no activity between the device and the server within the timer interval, then LE_AVC_NO_UPDATE state will be returned to the app. However, this activity timeout can be overridden by setting an integer value for /apps/avcService/activityTimeout. The 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 activityTimeout.

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

Copyright (C) Sierra Wireless Inc.