Update Factory Client for Embedded Android¶
Update Factory Android Client is an open-source project by Kynetics. The project provides:
- UF Android Client Service: an
apkthat, when installed on an embedded Android device, implements a background service that:
- UF third-party integration APIs: an
aarlibrary that allows third party applications to configure, manage and monitor the UF Android Client Service
- UF Service API Reference Implementation: an
apkthat allows to configure, manage and monitor the UF Android Client Service from a simple Android User Interface. The app provides a third-party integration reference code for customer to integrate Update Factory in their own application. The app can be used also for debugging purposes.
Supported update types¶
The Android Client is able to apply two kind of updates: Application and System updates.
The client installs (or updates) Android applications.
An Application Software module must:
- have the Application type
- include one or more Android application(s) (
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.
The client installs an Android OS update. The UF Android Client 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.
Artifacts Download retry policy¶
The UF Android Clients 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.
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)|
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 the client is 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)|
The UF Android Client Service allows the user to force a poll by sending the Force Ping message.
UF Android Client Service version ≥ 1.5.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 Client 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.
Installation time windows¶
The time windows feature for forced updates is supported by client 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
- Cron expression:
0 15 10 ? * MON
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 Update Factory Android Client ≥ 1.3.0 sends three new target attributes to the Update Server:
time_windows_cron_expression: the cron expression used, if any
time_windows_duration: the duration used, if any
time_zone: the device time zone (e.g.
utc_offset: the UTC offset (e.g.