Configure Update Modes¶
This guide covers enabling the OTA file, OTA streaming and USB update modes.
Prerequisites¶
- The SWUpdate signing key pair in
keys/; see Generate a Signed Update Package - An integration project with its own distribution; see Build Your Own BSP Layer
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:
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:
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:
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:
Combine Modes¶
Features are additive. To support both OTA file mode and USB on the same device:
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:
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
- Update Mechanism —
DISTRO_FEATURESflags and update variables - Update Design — why the flags name capabilities, not tools
- Generate a Signed Update Package — build a package for these modes
- Test Updates in QEMU — trigger OTA and USB updates against a QEMU instance