Skip to content

Installing Update Factory Service for Embedded Android

Overview

Kynetics provides the "UF Android Service" and the "UF Service API Reference Implementation" as Android Package files (.apk) for side-load installation. The UF Android 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 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 Service apk can be downloaded from the following links. The APKs are pre-signed using some common platform keys. If you use your own private platform key refer to section Signing the UF Android Service APK.

  • AOSP platform key: use this for development Android OS builds based on AOSP and Android emulator (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 Service APK

If you need to sign the UF Android Service APK with your own platform key, you will need the following standard key files that were used to sign your Android OS image:

  • platform.pk8
  • platform.x509.pem

You also will need the apksigner utility, which is part of the Android SDK Build tools.

Note

Make sure you have:

  1. installed the Android SDK with the latest version of the Build tools
  2. configured the ANDROID_HOME variable, as specified in the SDK Tools Environment variables documentation

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

$ANDROID_HOME/build-tools/<build-tools-version>/apksigner sign --key platform.pk8 --cert platform.x509.pem --in uf-client-service-v1.6.1.apk --out uf-client-service-signed-v1.6.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.6.1.apk. 

adb install uf-client-service-signed-v1.6.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-v1.6.1-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 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 Service should be signed with the appropriate signature.

Using updated versions of the API (e.g. v1.2.1) requires running an UF Android Service version (e.g. v1.6.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 Service can be installed using an application update by including the apk in the Software module.

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

UF Android Service ≥ 1.3.0

Starting from v1.3.0 the UF Android 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 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 Service v1.6.1 supporting API v1.2.1
  • customer application using API v1.2.1
  • other applications

UF Android Service < 1.3.0

If UF Android 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 Service (e.g. v1.6.1)
  • create a target filter to filter devices that have an out of date application and a UF Android Service that supports the specified API (e.g. attribute.client_version_code=ge=10601 ensures v1.6.1 or later is installed and thus API v1.2.1 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 Service can be installed or upgraded using a system update by including the apk in the Android OTA package.