Update Design¶
meta-tolomeo names update capabilities with tool-agnostic feature flags and leaves every runtime decision to launchers that parse, never execute, their configuration.
Feature Flags Name Capabilities, Not Tools¶
The three update-mode flags — tlm-update-ota, tlm-update-ota-streaming, and tlm-update-offline — do not mention
swupdate. This is intentional.
These flags describe a device's update capability at the platform level, not the tool that implements it. A BSP layer
can read these flags and wire them to whichever update tool it uses. If meta-tolomeo-distro is replaced by a layer
using a different update mechanism, the same flags remain valid in distro configurations — the platform's
intent is preserved without leaking implementation details into the hardware description. The tlm- prefix keeps them
apart from upstream features such as pam or ptest.
Streaming Extends OTA, USB Stands Alone¶
Two features are independent; streaming depends on OTA:
tlm-update-otaandtlm-update-offlineare orthogonal — one covers remote updates, the other covers local updates from removable media. Neither implies the other. Both can be active on the same device simultaneously, sharing the EnvironmentFile and public key without conflict.tlm-update-ota-streamingis a modifier on top oftlm-update-ota, not a separate mode. It changes what swupdate installs from: swupdate fetches theURLindescriptor.envitself instead of reading the packagetlm-swupdatedownloaded. It operates within the same OTA service infrastructure.
The tlm-update-ota-streaming requires tlm-update-ota constraint is enforced at parse time with a bbfatal. This
prevents a configuration where the binary has curl compiled in but the base OTA infrastructure (service, conf.d
directory, key) is missing.
Topology in the EnvironmentFile, Behavior in conf.d¶
Runtime configuration is split across two locations with distinct purposes.
/etc/default/swupdate is loaded by systemd as an EnvironmentFile before the service starts. It contains only path
topology: where the swupdate binary is, where the public key is, and where the conf.d directories are. This
information must be available before any script runs, which is why it lives in a systemd-managed file rather than a
conf.d fragment. Its content never varies by update mode — it is the same regardless of whether the device uses file
mode, streaming mode, or USB.
/etc/swupdate/conf.d/ contains KEY=VALUE fragments parsed at runtime by swupdate.sh. These fragments set
behavioral variables: which source mode to use, what file path to check, what URL to fetch. Only allowlisted keys are
applied and nothing is executed, so a fragment cannot alter the anti-rollback policy. Because they are loaded in sorted
filename order, fragments with higher names can override earlier ones. This is where the ToloMEO Edge agent writes
descriptor.env at update time — it never modifies service unit files or the EnvironmentFile.
The split keeps the systemd pre-start environment simple and stable, while allowing the behavioral configuration to be composed and overridden at runtime.
Every Update Checks the Hardware Revision¶
Both update services run hwrevision-setup.sh as ExecStartPre before the update script (swupdate.sh for OTA,
swupdate-usb.sh for USB). This script writes the device's hardware revision to /etc/hwrevision, which swupdate reads
to verify that the update package is compatible with the target hardware before installing.
The variables used by the script are configured per BSP layer via /etc/default/hwrevision. For the full variable
list, see hwrevision-setup.sh Variables.
SWUPDATE_SOURCE Follows the Feature Flags¶
SWUPDATE_SOURCE is derived from DISTRO_FEATURES, so it cannot disagree with the swupdate build. A free variable set
in local.conf or a bbappend would allow a mismatch: SWUPDATE_SOURCE=download would not compile curl support into the
swupdate binary, and the mismatch would surface only at runtime, when swupdate attempted a download with no curl
support available.
SWUPDATE_SOURCE = "${@bb.utils.contains('DISTRO_FEATURES', 'tlm-update-ota-streaming', 'download', 'file', d)}"
When tlm-update-ota-streaming is present, the same feature flag that sets SWUPDATE_SOURCE=download also pulls in
swupdate-download.cfg, which enables curl support in the swupdate build configuration. The runtime mode and the binary
capabilities are always in sync — correct by construction rather than by convention.
swupdate.sh Builds the Command as an Array¶
swupdate.sh assembles the swupdate command in three stages:
Stage 1 — load_config_files() parses all files in $SWUPDATE_CONF_DIR_LIB and $SWUPDATE_CONF_DIR_ETC in sorted
order and applies the allowlisted KEY=VALUE lines. Files in the etc directory take precedence over the lib directory
when both contain a file with the same name. After this stage, SWUPDATE_SOURCE, UPDATE_FILE, and URL (when
present) are available as shell variables.
Stage 2 — build_arguments() reads the variables from stage 1 and builds the swupdate command as a Bash array. An
array is used instead of string concatenation and eval to ensure that argument values containing spaces or special
characters are passed verbatim to the process without shell re-parsing.
Stage 3 — run_swupdate() execs the assembled command. exec replaces the shell process with swupdate, so swupdate
inherits the same PID and systemd service tracking works correctly.
The handoff point of the ToloMEO Edge agent is descriptor.env: it writes the URL to that file. The OTA monitor
notifies tlm-swupdate, which downloads the package and starts a transient swupdate@<timestamp>.service.
Stage 1 picks descriptor.env up and makes URL available to stage 2. Neither the agent nor the OTA monitor invokes
swupdate directly.
Anti-Rollback Checks Twice and Trusts the Signed Version¶
Two layers compare an update against the running BUILD_VERSION, and they trust different things.
tlm-swupdate checks the fw_version declared in the NotifyOTAUpdate notification. That version is unsigned, so the
check is an early filter: an outdated update is never downloaded. The launchers swupdate.sh and swupdate-usb.sh pass
--no-downgrading and --no-reinstalling to swupdate, which compares against software.version in the signed
sw-description. That check is the authoritative control, because the signature covers the version it reads.
The OTA monitor forwards URL, FIRMWARE_NAME and FIRMWARE_VERSION from descriptor.env to tlm-swupdate
unchanged; it parses the file and never executes it.
The launchers read the running BUILD_VERSION from /usr/lib/os-release on the read-only rootfs, not from
/etc/os-release: /etc is an overlay that could shadow the file. The policy is baked in at build time, so the
environment, /etc/default/swupdate, conf.d fragments and descriptor.env cannot relax it.
TLM_OTA_ALLOW_SAME_VERSION and TLM_OTA_ALLOW_DOWNGRADE relax the two checks together in tlm-swupdate and the
launchers. With both set to 1, anti-rollback is off. A distro that declares the tlm-production feature gets a build
warning when TLM_OTA_ALLOW_DOWNGRADE is 1, so the loosened control is visible in the build log.
See also
- Configure Update Modes — step-by-step configuration
- Update Mechanism — complete variable and file reference