Search by Tags

Update Your Device Using HERE OTA Connect


Article updated at 18 Sep 2020
Compare with Revision

Subscribe for this article updates

Warning: the Torizon OTA is a project currently under development at Toradex Labs. It is still an experimental project in it's early stages which is subject to changes without notice. This might impact new releases and/or iterations.


HERE OTA Connect is an over-the-air update software management solution. This article goes through how to use it for updating your device, from account creation to board setup.

This article complies to the Typographic Conventions for Torizon Documentation.


You will need:

Create a HERE OTA Connect Account

You can create an account for HERE OTA Connect at In your account settings download which is required for provisioning.

Prepare Device for Update

Attention: You will need to execute the commands as root. You can login as root or (better) use sudo command when logged in with a regular user to do it.

First, make sure that aktualizr is stopped on the board so it won't interfere while creating configuration files:

# systemctl stop aktualizr.service

Import Credentials and Generate Certificates

You can use the aktualizr-cert-provider tool to import security information from the file that you can download from the portal.

Attention: You should not copy this file to the device because it contains your private keys, during device setup you may access it from a USB thumbdrive or SD card. If you have to copy it, ensure that you delete the file after you executed the command below.

# aktualizr-cert-provider -c <path to removable media>/ -l / -u -r
# cp /gateway.url /var/sota/import/gateway.url

Attention: Note the device id in the first line of output of aktualizr-cert-provider command. Your device will show as this id in the "Devices" tab on HERE OTA Connect.

Add Unique Device ID

You should set a unique id for your device to do this you have to edit a configuration file, but first you have to copy it to a different folder to be able to modify it.

# cp /usr/lib/sota/conf.d/40-hardware-id.toml /etc/sota/conf.d/
# vi /etc/sota/conf.d/40-hardware-id.toml

You can find your device unique id inside the proc filesystem:

# cat /proc/device-tree/serial-number

In the hardware-id file you will have to add a line with the id:

[provision] primary_ecu_hardware_id = colibri-imx6 primary_ecu_serial = <your unique id>

Add secondary system (optional)

If you plan to also push Docker Compose files to the device, you can add a Docker compose specific secondary. First create directory where secondary system information will be located:

# mkdir /etc/sota/secondary

Create the secondary JSON file:

# vi /etc/sota/secondary/docker-test.json

Paste this into the file:

{ "docker-compose": [ { "partial_verifying" : false, "ecu_hardware_id" : "docker-compose", "full_client_dir" : "/var/sota/storage/docker-compose", "ecu_private_key" : "sec.private", "ecu_public_key" : "sec.public", "firmware_path" : "/var/sota/storage/docker-compose/docker-compose.yml", "target_name_path" : "/var/sota/storage/docker-compose/target_name", "metadata_path" : "/var/sota/storage/docker-compose/metadata" } ] }

Next we need to tell aktualizr to use this file. For this you have to edit a configuration file, but first you have to copy it to a different folder to be able to modify it.

# cp /usr/lib/sota/conf.d/20-sota-device-cred.toml /etc/sota/conf.d/
# vi /etc/sota/conf.d/20-sota-device-cred.toml

Add following lines to the end of the file:

[uptane] secondary_config_file = "/etc/sota/secondary/docker-test.json"

Allow/block updates

Before applying an update, aktualizr will attempt to acquire a lock on /run/lock/aktualizr-lock using flock. You can have custom code in your application(s) that acquire and release this lock to help control when updates are applied (see flock (2) man page).

In the command line, it is possible to apply an advisory lock on a open file using the command flock. For example, the command below will apply an advisory lock on /run/lock/aktualizr-lock for 30 seconds:

# sudo flock --verbose -x /run/lock/aktualizr-lock -c "sleep 30"

Enable automatic reboot

After update aktualizr creates a file in /run/aktualizr-session/need_reboot. If you want the system to automatically reboot after a successful update, TorizonCore provides a systemd path unit configuration. Enable the path unit path like this:

# systemctl enable ostree-pending-reboot.path
# systemctl start ostree-pending-reboot.path

Start aktualizr

Our image has a systemd service which starts aktualizr.
To check your configuration it's better to start aktualizer interactively and check its output.
To run the tool you can just type:

# aktualizr --loglevel 1

On the output you will see what files are parsed and the requests made to the server:

Aktualizr version 1.0+gitAUTOINC+505627bbf4 starting
Reading config: "/usr/lib/sota/conf.d/20-sota_implicit_prov_ca.toml"
Reading config: "/etc/sota/conf.d/40-hardware-id.toml"
Current directory: /sysroot/home/torizon
Use existing SQL storage: "/var/sota/sql.db"
Checking if device is provisioned...
ECUs have been successfully registered to the server
... provisioned OK
Reporting network information
No installation result to report in manifest
got SendDeviceDataComplete event
Reporting network information
No installation result to report in manifest
No new updates found in Uptane metadata.
Reporting network information
No installation result to report in manifest
No new updates found in Uptane metadata.

Above you can see the output of a successful execution.
If you need to report issues, please include aktualizr output to help support in understanding the reasons for failure.

Once you have tested that Aktualizr can connect to the server you may reboot your device and start deploying updates to it.


To see in more detail what aktualizr is doing, you can stop the systemd service and start aktualizr manually, e.g. with an increased loglevel for debugging:

# systemctl stop aktualizr
# aktualizr --loglevel 1

To provision the device again, make sure to stop aktualizr, remove the device and the secondary storage entirely and start aktualizr again:

# rm /var/sota/sql.db
# rm -rf /var/sota/storage/

Common issues

If you see the following message:

response http code: 400
response: "An error occurred: Missing entity: Ecu"
could not put manifest

Make sure to properly delete the storage of the secondary (see above).

Deploy a Docker Compose yml file

version: '3' services: redis: image: "redis:alpine" restart: always

Upload it to OTA HERE Connect at Software Versions -> Upload Software -> Choose file, specify a "Software Name" and "Version" and select "docker-compose" under "Control unit types".

Create an update at Software updates -> Create update, specify "Software update name" and "Description" and select "docker-compose" under "Select multiple control unit types"

Trigger an update at Devices -> -> SECONDARY CONTROL UNITS -> docker-compose -> Software -> Software Name/Version -> Install

After update file is located inside:

# cat /var/sota/storage/docker-compose/docker-compose.yml

Aktualizr will call docker-compose automatically, hence the new containers should get started shortly after the update.