OTA Connect Developer Guide

Posix Secondaries: bitbaking and usage of Primary and Secondary images

The goal of this doc is to guide a reader on bitbaking of two type of images primary and secondary that are targeted for QEMU or RPi and running of which on the target makes it act as Primary and Secondary ECU of a single device.

Refer to the Uptane standard in order to grok the meaning of the Primary and Secondary terms in the given context from a theoretical standpoint. Check out this doc to understand these terms from a practical standpoint and to learn how Primary and Secondary can be emulated locally on an user’s host. It is highly advisable to follow the doc instructions and play with emulated Primary and Secondary prior to running steps described further in this doc.

Bitbaking

It is assumed that a reader is familiar with Yocto and bitbaking in general as well as bitbaking of Aktualizr images in particular, details of which are out of scope of this doc and can be found in the following guides:

Primary

To bitbake an image for Primary run the following:

bitbake primary-image
Table 1. Primary configuration variables
Name Default Description

PRIMARY_IP

"10.0.3.1"

An IP address to assign to one of the Primary’s NIC for communication with Secondaries

PRIMARY_PORT

"9040"

A TCP port that Primary aktualizr listens on for connections from Secondaries

PRIMARY_WAIT_TIMEOUT

"120"

Time (seconds) to wait for connections from Secondaries. Note that, while a Primary can still function if some Secondaries failed to connect, it will only provision if all its Secondaries have connected before this delay.

PRIMARY_SECONDARIES

"10.0.3.2:9050"

A space separated list of TCP/IP addresses of the Secondaries to be included into the list of ECUs served by the given Primary

Note that PRIMARY_SECONDARIES can be a list of TCP/IP addresses in order to fulfill multiple secondaries use case. For example, PRIMARY_SECONDARIES = "10.0.3.2:9050 10.0.3.3:9050 10.0.3.4:9050".

Secondary

To bitbake an image for Secondary run the following:

bitbake secondary-image
Table 2. Secondary configuration variables
Name Default Description

SECONDARY_IP

"10.0.3.2"

An IP address to assign to A Secondary NIC for communication with Primary

SECONDARY_PORT

"9050"

A TCP port that Secondary listen on for connections from Primary

Multiple secondaries use case

In order to support multiple secondaries use case an user should:

  • repeat the secondary bitbaking procedure corresponding number of times, each time

    • specifying unique TCP/IP address by means of SECONDARY_IP and SECONDARY_PORT configuration variables

    • copying and naming uniquely the resultant image file (e.g. cp tmp/deploy/images/qemux86-64/secondary-image-qemux86-64.ota-ext4 secondary-images/secondary-image-qemux86-64.ota-ext4-001)

  • bitbake the primary image with PRIMARY_SECONDARIES listing the corresponding secondaries TCP/IP addresses

  • run the primary by following the guide in Running

  • run the secondaries by running the command specified in Running with a parameter pointing to corresponding secondary image. For example,

../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network secondary-images/secondary-image-qemux86-64.ota-ext4-001

../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network secondary-images/secondary-image-qemux86-64.ota-ext4-002

Specifics of bitbaking for Raspberry Pi

It is assumed that a reader is a familiar with bitbaking for Raspberry Pi in general, see Build a Raspberry Pi image.

The aforementioned/above guide is relevant and applicable to building a Raspberry images of Primay and Secondary. The following is specifics of building such images targeting RPi.

  • run source meta-updater/scripts/envsetup.sh raspberrypi3 to get the build environment set up from a root of the yocto project (updater-repo)

  • specify type of NIC to use for Primary for connection to Internet/backend. There are two options, ethernet NIC or Wifi. By default ethernet NIC is used which implies that Raspberry Pi is connected to LAN with an access to Internet. To use WiFi NIC the following configuration variables should be defined in your local configuration (local.conf):

Table 3. WiFi configuration variables
Name Default Description

RPI_WIFI_ENABLE

"0"

A flag to enable/disable (default) WiFi on RPi board.

RPI_WIFI_SSID

N/A (mandatory if wifi is enabled)

SSID of a WiFi network to connect to. The SSID is case sensitive.

RPI_WIFI_PWD

N/A (mandatory if wifi is enabled)

Password to connect to the WiFi network router.

RPi networking details in a context of Posix secondaries support

IP/Posix secondaries support implies that a single primary ECU connected to two IP networks:

  • an IP network with an access to Internet for communication with the OTA backend;

  • an IP network that does not have access to Internet for communication with secondary ECU(s). The secondaries should be connected to this internal network.

Taking into account that RPi has two NICs, ethernet and wifi the aforementioned requirements to networking can be fulfilled by applying the following approaches.

Primary uses multihomed ethernet interface, Secondary uses ethernet interface

Both primary and secondary ECUs has wifi turned off and are connected to the same LAN (via switch or router) that has an access to Internet. Primary only network interface is configured in such way that it has two IP addresses assigned to it.

The first one (10.0.3.1 by default) is statically defined (can be configured via PRIMARY_IP configuration variable) and connects the primary to an internal IP network (10.0.3.0/8) that is aimed for communication with secondary ECU(s). Secondary(ies) are connected to the same internal network (10.0.3.0/8) by assigning to their ethernet interface corresponding IP addresses (10.0.3.x, 10.0.3.2 for the default only secondary, SECONDARY_IP configuration variable).

The second IP address assigned to the primary ethernet NIC should be obtained from a DHCP server running on one of the devices (usually a router) that is connected to the given LAN, has an access to Internet and provides each host connected to the given IP network with access to Internet (via NATing IP packets, DHCP and NAT server can be hosted/running on different devices).

The given networking option is enabled by default.

Primary uses both wifi and ethernet interfaces, Secondary uses ethernet interface

Primary has wifi on, and its wifi NIC is connected to a LAN with an access to Internet. Also, Primary ethernet NIC is assigned with an only IP address (10.0.3.1 by default) to connect to the internal network for communication with secondary ECUs. Secondary(ies) are connected to the same internal network (10.0.3.0/8) by assigning to their ethernet interface corresponding IP addresses (10.0.3.x, 10.0.3.2 for the default only secondary, SECONDARY_IP configuration variable).

Primary and Secondary uses wifi, only Primary uses ethernet NIC

In this case, both Primary and Secondary(ies) uses wifi NIC to connect to the internal network (wifi router should not have an Internet access). Secondary doesn’t use ethernet NIC. Primary connects to Internet via ethernet NIC that should be connected to LAN with an access to Internet. (This approach is not supported by meta-updater but can be applied by an advanced user.)

Running

It is assumed that a reader is familiar with details on running of bitbaked images targeted for QEMU, such information can be found in the following docs:

Primary

To launch QEMU VM acting as Primary run the following from your build directory:

../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network primary-image

The --secondary-network option instructs QEMU to add NIC to the VM in order to communicate with Secondary VM(s) via it.

Secondary

To launch QEMU VM acting as Secondary run the following from your build directory:

../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network secondary-image

The --secondary-network option instructs QEMU to add NIC to the VM aimed for communication with Primary.

Usage

Once both Primary and Secondary VMs are running you should see that a new device has been registered at the server and you can start testing it. The following are Tips & Tricks for using & troubleshooting of the Primary and Secondary VMs.

  • run journalctl -f -u aktualizr to see logs that are being output by aktualizr running on Primary VM;

  • run journalctl -f -u aktualizr-secondary to see logs that are being output by aktualizr-secondary (posix/IP secondary) running on Secondary VM;

  • By default, both aktualizr and aktualizr-secondary are running as systemd services. Use systemctl stop|start|restart <aktualizr|aktualizr-secondary> to control aktualizr and aktualizr-secondary daemons/services managed by systemd;

  • To control aktualizr|aktualizr-secondary manually stop corresponding systemd service (see above) and run it from command line: just type aktualizr' | `aktualizr-secondary;

  • By default, both executables output logs of level 1 (INFO), specify log level 0 in their config to see debug logs. In case of running from command line add corresponding parameter <aktualizr|aktualizr-secondary> --loglevel 0. In case of running as a systemd service add corresponding configuration fragment into /etc/sota/conf.d/ folder, e.g. echo -e "[logger]\nloglevel = 0" > /etc/sota/conf.d/50-debug-logs.toml and restart the service;

  • In order to trigger a device re-provisioning, please, remove the DB file on Primary, i.e. rm /var/sota/sql.db

  • If the DB file is removed on Secondary then the device should be re-provisioned (see above), otherwise Primary/aktualizr will refuse to work with a 'new' secondary as it will have a "new" autogenerated ECU serial that doesn’t the one already been registered on Primary.

  • OTA Connect does not support adding/removing secondary ECUs to a device that has been already registered. Thus adding a new ECU to the list of secondaries on Primary won’t take much effect, the new ECU won’t appear on the UI and it will be listed as not registered by aktualizr-info.