Skip to content

Update Factory Client for Embedded Android

Overview

Update Factory Android Client is an open-source project by Kynetics. The project provides:

  1. UF Android Client Service: an apk that, when installed on an embedded Android device, implements a background service that:
    1. handles all the communication to and from the Update Factory platform
    2. manages the installation of updates files
  2. UF third-party integration APIs: an aar library that allows third party applications to configure, manage and monitor the UF Android Client Service
  3. UF Service API Reference Implementation: an apk that 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 three kind of updates: Application, System and Device Control updates.

Application

The client installs (or updates) Android applications.

An Application Software module must:

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

Device Control

The client 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.

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.

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:

  1. 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
  2. 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)
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.

Note

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

Note

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:

Example

  • Cron expression: 0 15 10 ? * MON
  • Duration: 3600 seconds

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:

  1. time_windows_cron_expression: the cron expression used, if any
  2. time_windows_duration: the duration used, if any
  3. time_zone: the device time zone (e.g. America/Los_Angeles)
  4. utc_offset: the UTC offset (e.g. -07:00)

References

Kynetics - Update Factory

Kynetics Technical note on Update Factory

Kynetics Slideshare