Skip to content

Configure Update Modes

Enabling OTA and USB update capabilities in a meta-tolomeo-based BSP by setting DISTRO_FEATURES flags.

Table of Contents

Overview

meta-tolomeo provides three DISTRO_FEATURES flags that control which update services and configuration files are installed on the target device. The flags are tool-agnostic — they describe the update capability, not the implementation.

Feature Capability
update-ota OTA updates via a .swu file placed by the management agent
update-ota-streaming OTA updates streamed directly from a URL
update-local Local updates from a USB storage device

Features are additive. A device can have any combination active simultaneously.

Prerequisites

Before enabling any update mode, SWUPDATE_PUBLIC_KEY must point to the RSA public key used to verify update packages:

# In your kas configuration file or local.conf
SWUPDATE_PUBLIC_KEY = "${BSPDIR}/keys/swupdate-sign.pub"

See SWUpdate Package Generation for key generation instructions.

Where to declare DISTRO_FEATURES:

  • Machine .conf (meta-<your-bsp>/conf/machine/<machine>.conf): use when the update capability is tied to the hardware — a specific board always ships with USB support, another always uses streaming.
  • Distro .conf (conf/distro/<distro>.conf): use when the update mode is a platform-wide policy shared across all machines in the distribution.

Enable OTA File Mode

OTA file mode is the base update capability. The management agent downloads a .swu package and places it at a configured path. swupdate.sh picks it up from there.

Add update-ota to DISTRO_FEATURES:

# meta-<your-bsp>/conf/machine/<machine>.conf
DISTRO_FEATURES += "update-ota"

What gets installed on the device:

Path Purpose
/lib/systemd/system/swupdate@.service Templated systemd OTA service
/etc/swupdate/conf.d/00-source.conf Sets SWUPDATE_SOURCE=file
/etc/swupdate/conf.d/10-ota-file.conf Sets UPDATE_FILE=<path>
/etc/default/swupdate Path topology loaded by systemd before service start
/etc/swupdate/certs/public.pem Package verification key

Triggering an update:

The management agent places the signed .swu package at the path configured in SWUPDATE_UPDATE_FILE (default: /data/tolomeo/ota.pkg), then starts the service:

systemctl start swupdate@<machine>.service

Enable OTA Streaming Mode

Streaming mode compiles curl support into the swupdate binary and configures it to fetch the artifact directly from a URL. Requires update-ota.

Add both features to DISTRO_FEATURES:

# meta-<your-bsp>/conf/machine/<machine>.conf
DISTRO_FEATURES += "update-ota update-ota-streaming"

What gets installed on the device:

Path Purpose
/lib/systemd/system/swupdate@.service Templated systemd OTA service
/etc/swupdate/conf.d/00-source.conf Sets SWUPDATE_SOURCE=download
/etc/default/swupdate Path topology loaded by systemd before service start
/etc/swupdate/certs/public.pem Package verification key

10-ota-file.conf is not installed — the file path is irrelevant in streaming mode.

Triggering an update:

The management agent writes the artifact URL to /etc/swupdate/conf.d/descriptor.env, then starts the service:

echo "URL=https://update.example.com/firmware/1.2.0.swu" > /etc/swupdate/conf.d/descriptor.env
systemctl start swupdate@<machine>.service

Enable USB Update Mode

USB mode installs the swupdate-usb@.service and the swupdate-usb.sh helper script. It is independent of OTA — the two modes can coexist on the same device.

Add update-local to DISTRO_FEATURES:

# meta-<your-bsp>/conf/machine/<machine>.conf
DISTRO_FEATURES += "update-local"

What gets installed on the device:

Path Purpose
/lib/systemd/system/swupdate-usb@.service Templated USB update service
<libdir>/swupdate/swupdate-usb.sh USB device scan and handoff script
/etc/default/swupdate Path topology (shared with OTA services if both active)
/etc/swupdate/certs/public.pem Package verification key

Triggering an update:

USB updates are typically triggered by a udev rule or manually by starting the service with a block device name:

systemctl start swupdate-usb@sda1.service

Combining Modes

Features are additive. To support both OTA file mode and USB on the same device:

DISTRO_FEATURES += "update-ota update-local"

Both services are installed and operate independently. The shared /etc/default/swupdate EnvironmentFile is installed once and used by both.

To support OTA streaming and USB together:

DISTRO_FEATURES += "update-ota update-ota-streaming update-local"

Override the Default Update File Path

The default path where the management agent is expected to drop the .swu package is /data/tolomeo/ota.pkg. To change it, set SWUPDATE_UPDATE_FILE:

# In your bbappend, machine conf, or kas local.conf
SWUPDATE_UPDATE_FILE = "/mnt/data/updates/firmware.swu"

This variable only applies when update-ota is active without update-ota-streaming. In streaming mode the artifact is fetched by URL and no local drop path is used.