Update Factory Service for Embedded Android¶
Overview¶
Kynetics develops the Update Factory Android Service, an Android application that runs as a background Service to receive and install different types of updates from the Update Factory server. The project provides:
- UF Android Service: an
apkthat implements a background service for embedded Android devices that:- handles all the communication to and from the Update Factory platform
- manages the installation of updates files
- UF Service APIs: an
aarintegration library that allows third party applications to configure, manage and monitor the UF Android Service - UF Service API Reference Implementation: an
apkthat allows to configure, manage and monitor the UF Android Service from a simple Android User Interface. The app provides a UF Service reference implementation code for customer to integrate Update Factory in their own application. The app can be used also for debugging purposes.
Supported update types¶
The UF Android Service is able to apply three kind of updates: Application, System and Device Control updates.
Application¶
The UF Android Service installs (or updates) Android applications.
An Application Software module must:
- have the Application type
- include one or more Android application(s) (
.apk)
An application update will fail under the following conditions:
- the installation of one or more applications has failed;
- some files in the update are not apk files.
Application updates are performed without a system reboot.
System¶
The UF Android Service installs an Android OS update. The UF Android Service is able to automatically detect the type of system updates supported by the device.
A System Software module must:
- have the OS type
- include a single OTA file
The two types of system updates are:
- single-copy updates: older Android devices tend to use this update mechanism where system partitions are not duplicated
- double-copy updates (also known as "AB updates"): recent Android devices tend to use this update mechanism where system partitions are fully duplicated
System updates require a system reboot.
Device Control¶
The UF Android Service installs and executes an Android DCU application.
A Device Control Software module must:
- have the DCU type
- include a single Android DCU application (
.apk)
See the Device Control Update page for more information.
Combined Software Distributions¶
Besides Distributions with a single Update Type, the UF Android Service supports combining system and application Software Modules in a single Distribution.
OS with apps¶
When the UF Android Service receives an OS with app(s) Distribution, it will install the Android system OTA first, and then, after the device has rebooted to the new OS, the applications.
To create such a Distribution:
- create a new Distribution with type OS with app(s)
- associate a System Software Module to the Distribution
- associate an Application Software Module to the Distribution
Artifacts Download retry policy¶
The UF Android Service implement the following artifacts download retry policies in case of download issues (e.g. poor network connection).
Clients ≤ 1.1.2¶
Three subsequent artifact download attempts are performed, with a 30 seconds interval in between. If all the three attempts fail, a download failure is reported to the Update Factory server.
Clients ≥ 1.2.0¶
A "truncated exponential backoff" algorithm is implemented in recent Clients. A maximum of 36 artifact download attempts are performed at increasing intervals, ranging from 10 seconds for the first few attempts, to 1 hour for the last ones. If all the attempts fail, a download failure is reported to the Update Factory server.
Note
When using new Clients the Artifact Download Lifetime should be set to at least 2 days, to make sure the artifact URL doesn't expire before the last download attempt.
Download retry intervals table
This table shows the wait interval that follows each failed artifact download attempt.
| Attempt # | Wait Interval (s) |
|---|---|
| 1 | 10 |
| 2 | 10 |
| 3 | 16 |
| 4 | 32 |
| 5 | 64 |
| 6 | 128 |
| 7 | 256 |
| 8 | 512 |
| 9 | 1024 |
| 10 | 2048 |
| 11 | 3600 |
| 12 | 3600 |
| 13 | 3600 |
| 14 | 3600 |
| 15 | 3600 |
| 16 | 3600 |
| 17 | 3600 |
| 18 | 3600 |
| 19 | 3600 |
| 20 | 3600 |
| 21 | 3600 |
| 22 | 3600 |
| 23 | 3600 |
| 24 | 3600 |
| 25 | 3600 |
| 26 | 3600 |
| 27 | 3600 |
| 28 | 3600 |
| 29 | 3600 |
| 30 | 3600 |
| 31 | 3600 |
| 32 | 3600 |
| 33 | 3600 |
| 34 | 3600 |
| 35 | 3600 |
| 36 | N/A |
Client polling time¶
The UF Android Client Service respects the Polling Time specified by the server in the System Configuration.
There are two exceptions to the rule:
- whenever a poll fails, the Service tries to poll with a "truncated exponential backoff" algorithm with a maximum of 60 seconds interval between a poll attempt and the following. See "Poll retry intervals table" for details
- while downloading the update artifacts, the Service polls every 30 seconds to increase the likelihood of intercepting potential cancel actions from the server
Poll retry intervals table
This table shows the wait interval that follows each failed poll attempt.
| Attempt # | Wait Interval (s) |
|---|---|
| 1 | 1 |
| 2 | 1 |
| 3 | 2 |
| 4 | 4 |
| 5 | 8 |
| 6 | 16 |
| 7 | 32 |
| 8 | 60 |
| 9 | 60 |
| 10 | 60 |
| ... | 60 |
| n | 60 |
Force Ping¶
The UF Android Client Service allows the user to force a poll by sending the Force Ping message.
UF Android Service ≥ v1.6.0 implements a debouncing algorithm that limits the force ping frequency to at most one request every 30 seconds.
Force Ping debouncing algorithm
If the UF Android Service receives a force ping message:
- The message is processed immediately if the last force ping message was received more than 30 seconds ago.
- If multiple force ping messages are sent during the 30-second debouncing period, only the first force ping message is processed, and the others are ignored.
Note
In UF Android Service ≥ v1.6.0 the ForcePing behavior has been updated to provide an explicit NoNewState event when the server state is unchanged. See Force Ping documentation for more details.
Installation time windows¶
Note
The time windows feature for forced updates is supported by UF Android Service version ≥ 1.3.0 and API v1.1.
The time windows feature allows to customize the Android Client installation behaviour of forced updates. When time windows are specified, the UF Android Client Service installs the forced update only when the device time is within the defined time intervals. Once the installation of an update is started, the process will continue until completion. Time windows affect only the installation phase; download is still performed as soon as the update is available.
The Time windows are defined by:
- a cron expression (QUARTZ format), which defines the beginning of the windows
- a duration, which defines the windows size in seconds
Example
- Cron expression:
0 15 10 ? * MON - Duration:
3600seconds
The available forced updates will be installed only every Monday between 10:15 am and 11:15 am in the device's local time zone.
To configure this feature use the timeWindows parameter of communication API v1.1.
The UF Android Service ≥ v1.3.0 sends four new target attributes to the Update Server:
time_windows_cron_expression: the cron expression usedtime_windows_duration: the duration usedtime_zone: the device time zone (e.g.America/Los_Angeles)utc_offset: the UTC offset (e.g.-07:00)
Built-in attributes¶
The UF Android Service sends the following built-in attributes to the server. Additional custom attributes can be provided by the customer application using the dedicated API.
| Attribute name | Attribute description | Example value |
|---|---|---|
android_api_level |
Android OS API level (monotonically increasing integer value). Provided by UF Android Service ≥ v1.6.0 | 33 |
android_build_date |
Android OS build date | 20240408 |
android_build_type |
Android OS build type | eng, userdebug or user |
android_fingerprint |
Android OS build full fingerprint code | Android/verdin_8mp/verdin_8mp:13/1.0-SNAPSHOT-20240408/eng.develo.20240408.102414:userdebug/dev-keys |
android_keys |
Android OS build keys name | dev-keys |
android_version |
Android OS major version | 13 |
client |
OS type | Android |
client_version |
UF Android Service version string | v1.6.1 |
client_version_code |
UF Android Service version code (monotonically increasing integer value) | 10601 |
device_name |
Android OS device name | verdin_8mp |
system_update_type |
Android OS system OTA update type | SINGLE_COPY or AB |
time_windows_cron_expression |
Cron expression to handle time windows feature | * * * ? * * |
time_windows_duration |
Time windows duration | 1h |
time_zone |
Device time zone | America/Chicago |
utc_offset |
Device offset to UTC (can vary during the year depending on daylight saving) | -05:00 |