Skip to content

Configure Update Modes

This guide covers enabling the OTA file, OTA streaming and USB update modes.

Prerequisites

Declare the DISTRO_FEATURES of this guide in the distro configuration only. tolomeo.inc assigns DISTRO_FEATURES with =, so a += in a machine configuration is discarded. tlm-update-ota-streaming requires tlm-update-ota; the build stops at parse time otherwise. Every other combination of the three features is valid. The Update Design page explains why the flags name capabilities, not tools.

Enable OTA File Mode

OTA file mode is the base update capability. The ToloMEO Edge agent writes descriptor.env, the OTA monitor notifies tlm-swupdate, and tlm-swupdate downloads the .swu package to a configured path. It then starts a transient swupdate@<timestamp>.service, and swupdate.sh installs the package from that path.

Add tlm-update-ota to DISTRO_FEATURES:

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

What gets installed on the device:

Path Purpose
/usr/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

The package path is SWUPDATE_UPDATE_FILE, which defaults to /data/tolomeo/ota.pkg.

To start an installation by hand, place a signed .swu package at that path and start the service. The instance name after @ is free:

systemctl start swupdate@manual.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. It requires tlm-update-ota. The ToloMEO Edge agent writes the artifact URL to /etc/swupdate/conf.d/descriptor.env, the OTA monitor notifies tlm-swupdate, which downloads the package and starts a transient swupdate@<timestamp>.service. The swupdate.sh launcher ignores that file and streams the URL from descriptor.env.

Add both features to DISTRO_FEATURES:

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

What gets installed on the device:

Path Purpose
/usr/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.

To start an installation by hand, write the URL and start the service:

echo "URL=https://update.example.com/firmware/1.2.0.swu" > /etc/swupdate/conf.d/descriptor.env
systemctl start swupdate@manual.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 tlm-update-offline to DISTRO_FEATURES:

# meta-<your-bsp>/conf/distro/<your-distro>.conf
DISTRO_FEATURES += "tlm-update-offline"

What gets installed on the device:

Path Purpose
/usr/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

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

Combine Modes

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

DISTRO_FEATURES += "tlm-update-ota tlm-update-offline"

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 += "tlm-update-ota tlm-update-ota-streaming tlm-update-offline"

Move the OTA Package Location (Optional)

The default location of the .swu package is /data/tolomeo/ota.pkg. tlm-swupdate writes the package to TLM_OTA_FILE and swupdate.sh reads it from the same path, so set the directory and the filename, not the path itself:

# meta-<your-bsp>/conf/distro/<your-distro>.conf
TLM_OTA_DIR = "/mnt/data/updates"
TLM_OTA_FILENAME = "firmware.swu"

The location applies only when tlm-update-ota is active without tlm-update-ota-streaming. In streaming mode swupdate does not read this path, but tlm-swupdate still downloads to it, so it needs the space. See Configure meta-tolomeo for Your Machine for the coupled values.

See also