Skip to content

Install and Configure Update Factory Client packages for Embedded Android

Overview

Kynetics provides the "UF Android Client Service" and "UF Service API Reference Implementation" as Android Package files (.apk) for side-load installation. The UF Android Client Service must be installed as a SYSTEM application to work correctly, which is guaranteed by signing it with the platform key. The platform key can either be:

  • the test version included in the Android build system
  • a custom one created for production purposes

Please refer to this Technical Note for more information regarding how to sign system applications. Also, a signing example is provided in section Signing the UF Android Client Service APK.

Note

For a successful installation, this guide assumes that you've powered on your device, have debug/developer mode enabled in Android, and have connected your device to your computer so that the adb utility can be used to side-load (install) APKs and copy the ufConf.conf file to your device.

Download the APKs

The latest version of the UF Android Client applications are available from the Github Releases page

Note

We've pre-signed the UF Android Client Service APK with the:

  • AOSP platform key: use this for development Android OS builds based on AOSP and Android emulator (only variant without Google APIs)
  • NXP platform key: use this for development Android OS builds based on NXP BSP
  • Rockchip platform key: use this for development Android OS builds based on Rockchip BSP

Signing the UF Android Client Service APK

In the case that you need to sign the UF Android Client Service APK with a different platform key, you will need the following standard key files that were also used to sign your Android OS image:

  • platform.pk8
  • platform.x509.pem

You also will need the signapk.jar utility, which can be found in the Android OS build system (out/host/linux-x86/signapk.jar) .

Once you have all the required files, run the following command to sign the UF Android Client Service (adapt paths and file names as needed): 

java -jar signapk.jar platform.x509.pem platform.pk8 uf-client-service-v1.5.1.apk uf-client-service-signed-vv1.5.1.apk

Preparing the ufConf.conf configuration files

If you have the ufConf.conf file defined, the UF Service API Reference Implementation will automatically obtain the configuration and not require user input for configuration in the app.

Learn more about the parameters in the ufConf.conf configuration file and its installation path in the Client configuration page.

Side-loading APKs

Proceed to side-load the signed UF Android Client Service APK. In this example, it is called: uf-client-service-signed-v1.5.1.apk. 

adb install uf-client-service-signed-v1.5.1.apk

After installation of the UF Android Client Service, you will need to run the following once to enable the background service:

adb shell am startservice -a com.kynetics.action.BIND_UF_SERVICE

Optionally, you can also install the UF Service API Reference Implementation APK:

adb install uf-service-api-reference-implementation-kynetics_key.apk

Once installed successfully, you can find the Update Factory app in the Android launcher.

Warning

SELinux Security Framework may block operations like installation of updates or read access to configuration files. Please set SELinux to permissive mode or configure it in your Android OS to grant the required permissions to the UF Android Client Service.

For more information about SELinux on Android see the official documentation.

Updating the UF Android Service

The UF Android Client Service can be updated either directly using an application update or by bundling it in a system update. In both cases the apk of UF Android Client Service should be signed with the appropriate signature.

Using updated versions of the API (e.g. v1.2) requires running an UF Android Client Service version (e.g. v1.5.1) which supports them, as specified in the API compatibility table.

The following strategies provide the recommended ways to perform API upgrades.

Application update

The UF Android Client Service can be installed using an application update by including the apk in the Software module.

Depending on the version of the UF Android Client Service installed on the device we recommend the following strategies.

UF Android Service ≥ 1.3.0

Starting from v1.3.0 the UF Android Client Service prioritizes updating itself over other apks in the same Application update Software module. This approach ensures that support for the latest version of the third party API is installed before any application that may use such API.

Example

If the UF Android Client Service 1.3.0 (or any later version) is already installed in the device, a single application update including the following Software Module artifacts can be installed directly:

  • UF Android Client Service v1.5.1 supporting API v1.2
  • customer application using API v1.2
  • other applications

UF Android Service < 1.3.0

If UF Android Client Service v1.2.0 or earlier is installed, the API upgrade can be performed as follows:

  • create a rollout to update to the latest UF Android Client Service (e.g. v1.5.1)
  • create a target filter to filter devices that have an out of date application and a UF Android Client Service that supports the specified API (e.g. attribute.client_version_code=ge=35 ensures v1.5.1 or later is installed and thus API v1.2 are supported). This filter can then be used to auto assign a distribution with the latest version of the application that uses the desired API version

System update

The UF Android Client Service can be installed or upgraded using a system update by including the apk in the Android OTA package.