Skip to content

Update Mechanism

The update mechanism is the set of DISTRO_FEATURES, recipe variables, conf.d files and runtime variables that configure SWUpdate on a ToloMEO device.

DISTRO_FEATURES

Feature Meaning Requires
tlm-update-ota Enables OTA updates through tlm-swupdate. Installs swupdate@.service, the base EnvironmentFile, and 00-source.conf with SWUPDATE_SOURCE=file. —
tlm-update-ota-streaming Enables the update tool to fetch the artifact directly from a URL. Compiles curl support into the swupdate binary. Sets SWUPDATE_SOURCE=download. tlm-update-ota
tlm-update-offline Enables local USB-based updates. Installs swupdate-usb@.service and swupdate-usb.sh. —
tlm-update-encrypted Compiles AES image and manifest decryption support into the swupdate binary. Does not provision the on-device decryption key — that is a BSP-layer responsibility. —

Features are additive. tlm-update-ota-streaming requires tlm-update-ota; the build stops at parse time otherwise. The other features combine freely.

Rootfs State Per Scenario

Active features /etc/default/swupdate conf.d at build time conf.d at runtime
tlm-update-ota ✓ 00-source.conf + 10-ota-file.conf —
tlm-update-ota + tlm-update-ota-streaming ✓ 00-source.conf descriptor.env
tlm-update-offline ✓ — —
tlm-update-ota + tlm-update-offline ✓ 00-source.conf + 10-ota-file.conf —
tlm-update-ota + tlm-update-ota-streaming + tlm-update-offline ✓ 00-source.conf descriptor.env

Recipe Variables

Variable Default Set in Description
SWUPDATE_UPDATE_FILE derived machine conf / bbappend Path tlm-swupdate downloads the .swu file to; defaults to TLM_OTA_FILE (/data/tolomeo/ota.pkg). Applies only when tlm-update-ota is active without tlm-update-ota-streaming. Set TLM_OTA_DIR and TLM_OTA_FILENAME instead.
SWUPDATE_SOURCE derived read-only file when tlm-update-ota-streaming is absent; download when present. Derived from DISTRO_FEATURES.
SWUPDATE_PUBLIC_KEY ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME}.pub kas / local.conf RSA public key swupdate uses for package signature verification. Required for every tolomeo build; the build stops if the file is missing.
SWUPDATE_KEYDIR keys† kas / local.conf Directory for all key material (signing and encryption).
SWUPDATE_SIGN_KEYNAME dev-sign† kas / local.conf Base name of the signing key files, without extension.
SWUPDATE_ENC_KEYNAME dev-aes† kas / local.conf Base name of the AES key file used for artifact encryption, without extension.
SWUPDATE_AES_FILE derived — Full path to the AES key file, ${SWUPDATE_KEYDIR}/${SWUPDATE_ENC_KEYNAME} when tlm-update-encrypted is active and empty otherwise.
TLM_OTA_ALLOW_SAME_VERSION 0 distro conf / local.conf Defined by tolomeo_ota and baked in at build time. 0 rejects an update with the running version in every anti-rollback layer; 1 accepts it.
TLM_OTA_ALLOW_DOWNGRADE 0 distro conf / local.conf Defined by tolomeo_ota and baked in at build time. 0 rejects an update older than the running version in every anti-rollback layer; 1 accepts it.
BUILD_VERSION — kas Firmware version published in /usr/lib/os-release (linked from /etc/os-release) and in sw-description. Must be semver (e.g. 1.2.0+26.03); the build fails at parse time otherwise.

† The meta-tolomeo-distro kas fragment sets SWUPDATE_KEYDIR to ${BSPDIR}/keys, SWUPDATE_SIGN_KEYNAME to swupdate-sign and SWUPDATE_ENC_KEYNAME to swupdate-enc.

conf.d Files

swupdate.sh parses the files in <libdir>/swupdate/conf.d/ and /etc/swupdate/conf.d/ at runtime, in sorted filename order; on the same filename the /etc file wins. Only KEY=VALUE lines are applied, and only for the keys listed under Runtime Variables plus SWUPDATE_SOURCE, UPDATE_FILE, SWUPDATE_SW, SWUPDATE_MODE, DEBUG, SWUPDATE_WEBSERVER_ARGS and SWUPDATE_SURICATTA_ARGS; descriptor.env, written by the ToloMEO Edge agent, may set URL only. One pair of surrounding quotes is stripped. Any other line is ignored and never executed.

Filename Installed when Token replaced at build Installed path
00-source.conf tlm-update-ota is active @SWUPDATE_SOURCE@ → file or download /etc/swupdate/conf.d/00-source.conf
10-ota-file.conf tlm-update-ota active AND tlm-update-ota-streaming absent @SWUPDATE_UPDATE_FILE@ → configured path /etc/swupdate/conf.d/10-ota-file.conf
descriptor.env Not installed at build time — /etc/swupdate/conf.d/descriptor.env (written at runtime by the ToloMEO Edge agent)

Runtime Variables

Required in Streaming Mode

Variable Source Description
URL descriptor.env Full URL of the .swu artifact to fetch. Required when SWUPDATE_SOURCE=download.

Optional Download Tuning

All variables below are unset by default. When not set, swupdate built-in defaults apply.

Variable swupdate flag Description
SWUPDATE_DOWNLOAD_RETRIES -r Number of retry attempts on download failure
SWUPDATE_DOWNLOAD_TIMEOUT -t Per-attempt timeout in seconds
SWUPDATE_DOWNLOAD_MAX_SPEED -n Maximum download speed in bytes per second
SWUPDATE_DOWNLOAD_NO_CHECK_CERT --no-check-certificate Disable TLS certificate verification (set to any non-empty value to enable)
SWUPDATE_DOWNLOAD_SSL_KEY --ssl-key Path to client TLS private key
SWUPDATE_DOWNLOAD_SSL_CERT --ssl-cert Path to client TLS certificate
SWUPDATE_DOWNLOAD_CA_PATH --ca-path Path to CA certificate bundle

Optional variables can be set in a conf.d fragment or passed via a systemd service drop-in.

Anti-Rollback

Two layers compare an update against the running BUILD_VERSION. An older version is rejected unless TLM_OTA_ALLOW_DOWNGRADE is 1; the same version is rejected unless TLM_OTA_ALLOW_SAME_VERSION is 1. With both set to 1, anti-rollback is off. A distro that declares the tlm-production distro feature gets a build warning whenever TLM_OTA_ALLOW_DOWNGRADE is 1, whatever TLM_OTA_ALLOW_SAME_VERSION is; see Build-Kind Distro Features. These layers apply whatever triggers the update: the ToloMEO Edge agent, a hand-written descriptor.env, commands sent straight to tlm-swupdate, or a USB stick.

Layer Component Compares On rejection
1 tlm-swupdate fw_version from NotifyOTAUpdate Ignores the notification; drops a checkpointed update on start
2 swupdate.sh, swupdate-usb.sh software.version in the signed sw-description swupdate refuses the package

The OTA monitor forwards URL, FIRMWARE_NAME and FIRMWARE_VERSION from descriptor.env to tlm-swupdate unchanged. The launchers read the running BUILD_VERSION from /usr/lib/os-release at runtime. The policy and the os-release path are baked in at build time: the environment, /etc/default/swupdate, conf.d fragments and descriptor.env cannot change them. The launchers always pass --key; swupdate refuses to run without it. See Update Design for the reasons.

swupdate flag Passed when Rejects
--no-downgrading <BUILD_VERSION> TLM_OTA_ALLOW_DOWNGRADE = 0 (default) Packages older than the running version
--no-reinstalling <BUILD_VERSION> TLM_OTA_ALLOW_SAME_VERSION = 0 (default) Packages with the same version as the running one

When either flag is passed and os-release is missing, has no BUILD_VERSION or it is not semver, the launchers exit without invoking swupdate. With anti-rollback off they do not read os-release.

hwrevision-setup.sh Variables

hwrevision-setup.sh reads these variables from /etc/default/hwrevision; the defaults apply when a variable is not set. meta-tolomeo-nxp overrides the file for its device-tree-based boards, and a BSP layer overrides it for its own hardware.

Variable Default (meta-tolomeo-distro) Default (meta-tolomeo-nxp) Description
HW_REVISION_FILE /etc/hwrevision /etc/hwrevision Path where the hardware revision string is written
DT_SOM_CONFIG — /proc/device-tree/som/configid Device-tree node path for the SOM config ID
DT_CB_CONFIG — /proc/device-tree/cb/configid Device-tree node path for the carrier board config ID
BOARD_NAME @MACHINE@ (substituted at build time) @MACHINE@ (substituted at build time) Board name written to /etc/hwrevision
REVISION_NUM 1.0 — Static revision string (replaces the device-tree-derived IDs)

Installed Paths Summary

Path Installed when Description
/etc/default/swupdate tlm-update-ota or tlm-update-offline systemd EnvironmentFile: sets SWUPDATE_BIN, SWUPDATE_PUBLIC_KEY, SWUPDATE_CONF_DIR_ETC, SWUPDATE_CONF_DIR_LIB
/etc/default/hwrevision always systemd EnvironmentFile for hwrevision-setup.sh; contents vary by BSP layer.
<libdir>/swupdate/hwrevision-setup.sh always Writes the device's hardware revision to /etc/hwrevision as ExecStartPre before each update service invocation.
/etc/swupdate/certs/public.pem always RSA public key for update package verification. Installed unconditionally — signature verification is required before any update channel is enabled.
/usr/lib/systemd/system/swupdate@.service tlm-update-ota Templated OTA update service
/usr/lib/systemd/system/swupdate-usb@.service tlm-update-offline Templated USB update service
<libdir>/swupdate/swupdate.sh always Update orchestration script
<libdir>/swupdate/swupdate-usb.sh tlm-update-offline USB device scan and handoff script

See also