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
- Configure Update Modes — enable OTA and USB modes
- Update Design — why the feature flags and the launchers are designed this way
- Configure the SWUpdate Service
(ToloMEO µServices) — the matching
allow_same_versionandallow_downgradekeys