OTA Connect Developer Guide

Simulate a device without building a disk image

You can try out OTA Connect without having to build a whole device image. This can be useful for testing the system outside of actual device updates. In this guide, you will install aktualizr (the OTA client software) on your local machine, create a directory with configuration files and credentials for aktualizr to use, and run aktualizr from there.

1. Prerequisites

2. Install aktualizr locally

The first step is to install an aktualizr binary on your system. You can install packages for MacOS (with homebrew), Ubuntu 16.04, or Ubuntu 18.04. If you use a different system, you will need to build from source.

  • Ubuntu 16.04 package

  • Ubuntu 18.04 package

  • MacOS (homebrew)

  • Build from source

Download the release from GitHub
wget https://github.com/advancedtelematic/aktualizr/releases/download/2020.9/aktualizr-ubuntu_16.04.deb
Install the downloaded .deb
sudo apt install ./aktualizr-ubuntu_16.04.deb
Disable the aktualizr system service
sudo systemctl stop aktualizr.service
sudo systemctl disable aktualizr.service
Download the release from GitHub
wget https://github.com/advancedtelematic/aktualizr/releases/download/2020.9/aktualizr-ubuntu_18.04.deb
Install the downloaded .deb
sudo apt install ./aktualizr-ubuntu_18.04.deb
Disable the aktualizr system service
sudo systemctl stop aktualizr.service
sudo systemctl disable aktualizr.service
brew tap advancedtelematic/otaconnect
brew install aktualizr
Install the prerequisites

Modify as needed for your distro. See https://github.com/advancedtelematic/aktualizr for further instructions

sudo apt install asn1c build-essential clang clang-format-10 clang-tidy-10 \
cmake curl doxygen graphviz lcov libarchive-dev libboost-dev \
libboost-filesystem-dev libboost-log-dev libboost-program-options-dev \
libcurl4-openssl-dev libostree-dev libp11-3 libp11-dev libpthread-stubs0-dev \
libsodium-dev libsqlite3-dev libssl-dev python3-dev python3-openssl \
python3-venv sqlite3 valgrind
Clone the sources from GitHub
git clone --recursive -b 2020.9 https://github.com/advancedtelematic/aktualizr
cd aktualizr
Build and install
mkdir build
cd build
cmake ..
make install

3. Prepare an environment for a simulated device

Make a directory for each device that you want to simulate. This directory will store your configuration files for that device, plus the device metadata and keys.

Each directory should contain the following:

  • credentials.zip

  • sota_local.toml — a config file for aktualizr

  • (Optional) A virtualsec.json file containing the configuration for one or more Secondary ECUs.[1]

An example directory is below:

  • Directory structure

  • sota_local.toml

  • virtualsec.json

├── credentials.zip
├── virtualsec.json
└── sota_local.toml
provision_path = "credentials.zip"
primary_ecu_hardware_id = "local-fake"
# This setting is for testing purposes only. Do not use in a real device.
mode = "SharedCredReuse"

loglevel = 1

path = "storage"

type = "none"
images_path = "storage/images"

secondary_config_file = "virtualsec.json"
  "virtual": [
                        "partial_verifying": false,
                        "ecu_hardware_id": "demo-virtual",
                        "full_client_dir": "storage/demo-vsec1",
                        "ecu_private_key": "sec.private",
                        "ecu_public_key": "sec.public",
                        "firmware_path": "storage/demo-vsec1/firmware.bin",
                        "target_name_path": "storage/demo-vsec1/target_name",
                        "metadata_path": "storage/demo-vsec1/metadata"
                        "partial_verifying": false,
                        "ecu_hardware_id": "demo-virtual",
                        "full_client_dir": "storage/demo-vsec2",
                        "ecu_private_key": "sec.private",
                        "ecu_public_key": "sec.public",
                        "firmware_path": "storage/demo-vsec2/firmware.bin",
                        "target_name_path": "storage/demo-vsec2/target_name",
                        "metadata_path": "storage/demo-vsec2/metadata"


Aktualizr’s config file format changed with version 2019.5, released July 12, 2019. These instructions apply only to version 2019.5 and later.

4. Run aktualizr in the prepared directory

From the directory you’ve created, run aktualizr and point it to the current directory for its configuration:

aktualizr -c .

This will start aktualizr in its normal mode: it will provision with the server using the credentials.zip provided, then start listening for updates. You can also selectively trigger aktualizr or use any of the other options; you just need to specify -c . each time.

You should now be able to see your simulated device provisioned into your OTA Connect account, with two Secondary ECUs listed.

Because the aktualizr config we’ve given uses relative paths, you must run aktualizr from the directory you created. However, if you prefer, you can use absolute paths in the config file instead. The reason we’ve chosen to use relative paths is to make it easy to simulate multiple distinct devices, by simply making a copy of the whole directory.

1. The terms "Primary" and "Secondary" ECU are used in the Uptane specification. For more information about the difference between Primary and Secondary ECUs, see our overview of the Uptane framework.