Update Mechanism Reference¶

Complete technical reference for the meta-tolomeo update mechanism: DISTRO_FEATURES flags, recipe variables, conf.d files, and runtime variables.

DISTRO_FEATURES¶

Feature	Meaning	Requires
`update-ota`	Enables OTA agent-placed file updates. Installs `swupdate@.service`, the base EnvironmentFile, and `00-source.conf` with `SWUPDATE_SOURCE=file`.	—
`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`.	`update-ota`
`update-local`	Enables local USB-based updates. Installs `swupdate-usb@.service` and `swupdate-usb.sh`.	—
`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. Any combination is valid. update-ota and update-local are orthogonal.

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

Variable	Default	Set in	Description
`SWUPDATE_UPDATE_FILE`	`/data/tolomeo/ota.pkg`	machine conf / bbappend	Path where the management agent drops the `.swu` file. Applies only when `update-ota` is active without `update-ota-streaming`.
`SWUPDATE_SOURCE`	derived	read-only	`file` when `update-ota-streaming` is absent; `download` when present. Derived from `DISTRO_FEATURES` — cannot be set directly.
`SWUPDATE_PUBLIC_KEY`	—	kas / machine conf	Absolute path to the RSA public key used by swupdate for package signature verification. Required when `update-ota` or `update-local` is active.
`SWUPDATE_KEYDIR`	`${BSPDIR}/keys`	kas / local.conf	Unified directory for all key material (signing and encryption).
`SWUPDATE_ENC_KEYNAME`	`swupdate-enc`	kas / local.conf	Base name of the AES key file used for artifact encryption, without extension.
`SWUPDATE_AES_FILE`	derived	read-only	Full path to the AES key file: `${SWUPDATE_KEYDIR}/${SWUPDATE_ENC_KEYNAME}`. Cannot be set directly.

Files in /etc/swupdate/conf.d/ are shell-sourced at runtime by swupdate.sh in sorted filename order.

Filename	Installed when	Token replaced at build	Installed path
`00-source.conf`	`update-ota` is active	`@SWUPDATE_SOURCE@` → `file` or `download`	`/etc/swupdate/conf.d/00-source.conf`
`10-ota-file.conf`	`update-ota` active AND `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 management agent)

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

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.

Read by hwrevision-setup.sh via /etc/default/hwrevision. Defaults apply when not set. BSP layers override this file to adapt to their hardware.

Variable	Default (distro layer)	Default (QEMU layer)	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 used on QEMU (replaces DT-derived IDs)

Path	Installed when	Description
`/etc/default/swupdate`	`update-ota` or `update-local`	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.
`/lib/systemd/system/swupdate@.service`	`update-ota`	Templated OTA update service
`/lib/systemd/system/swupdate-usb@.service`	`update-local`	Templated USB update service
`<libdir>/swupdate/swupdate.sh`	always	Update orchestration script
`<libdir>/swupdate/swupdate-usb.sh`	`update-local`	USB device scan and handoff script