Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions DEVICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,18 @@ when `CONFIG_TEDGE=y`; `apps/tedge-agent` is the client with no protocol.
Whether a given *board* can is a separate question, answered below.

**What is released** for each board is [`release/devices.yml`](release/devices.yml);
every `tedge-*` build listed there points at the entry below that records
its run on the board.
every `full` and `ota` build listed there points at the entry below that
records its run on the board.

> **Image names before 0.17.0.** The entries below keep the names images had
> when they were measured: `<app>-<variant>-<device>`, with the variants
> `standalone`, `tedge-full`, `tedge-ota`, `tedge-onboard` (ESP-IDF) and
> `nuttx`. From 0.17.0 every image is named `<app>-<os>-<set>-<device>`:
> `standalone`, `tedge-full` and `tedge-ota` are now `zephyr-standalone`,
> `zephyr-full` and `zephyr-ota`, `tedge-agent-idf-tedge-onboard-…` is
> `tedge-agent-idf-full-…`, and `tedge-agent-nuttx-…` is
> `tedge-agent-nuttx-full-…`. The README's "Moving a device to the new
> names" has the full table.

## Where they are

Expand Down
264 changes: 143 additions & 121 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion SCOPE.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ single-purpose devices (OPC-UA today; SNMP/Modbus/CAN as later Phase-2 apps):
tiny-edge's FreeRTOS port: no protocol server, set up over USB with
`tedge-onboard`. An ESP-IDF project (`idf.py build`), built by the `esp-idf`
workflow for the ESP32-C6 and ESP32-S3; the releases carry the ESP32-C6
image (`tedge-onboard` variant in `release/devices.yml`).
image (`idf-full` variant in `release/devices.yml`).
- The thin-edge.io device-management client is not in this repository. It
is [tiny-edge](https://github.com/thin-edge/tiny-edge), a Zephyr module
(`tedge`) that `west.yml` pins to a release. Apps here opt in with
Expand Down
11 changes: 7 additions & 4 deletions apps/tedge-agent-idf/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,14 @@ Cumulocity and reports its own vitals.
| Device type | `thin-edge.io-esp-idf-agent` |
| Version | `VERSION`, the same file and format as the Zephyr applications, so a release bumps it with them |

Built and run on the ESP32-C6, and released for it as the `tedge-onboard`
variant: `tedge-agent-idf-tedge-onboard-esp32c6-devkitc-<version>` with
Built and run on the ESP32-C6, and released for it as the `idf-full`
variant: `tedge-agent-idf-full-esp32c6-devkitc-<version>` with
`.factory.bin`, `.app.bin`, and `.zip`, like the Zephyr images. The release
build (`scripts/release/build.sh`) names the firmware after the variant and
the board instead of the chip. CI also builds it for the ESP32-S3 (workflow
names it `tedge-agent` (the `apps` section of `release/devices.yml`), so its
images sit beside the Zephyr and NuttX agents'
(`tedge-agent-<os>-<set>-<device>`). The release build
(`scripts/release/build.sh`) names the firmware after the board, not the
chip. CI also builds it for the ESP32-S3 (workflow
`esp-idf`); the S3 image joins the releases once it has run on that board.

## Build
Expand Down
4 changes: 2 additions & 2 deletions cumulocity/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ reason, and nothing is applied.

## Shell diagnostics

The `tedge-full` Modbus and agent images of the ESP32-S3-DevKitC and the QT Py
The `zephyr-full` Modbus and agent images of the ESP32-S3-DevKitC and the QT Py
ESP32-S3 carry the shell command (`tiny-edge/ports/zephyr/profiles/extras/shell-diagnostics.conf`)
for general checks from the device's **Shell** tab. Send `help` to see what
the device runs:
Expand All @@ -124,7 +124,7 @@ the device runs:
`net ping` is not offered: Zephyr prints the replies after the command
returns, so the cloud would only ever see the `PING <host>` line.

The ESP32-C6 Modbus `tedge-full` image carries a leaner set
The ESP32-C6 Modbus `zephyr-full` image carries a leaner set
(`release/extras/shell-lean.conf`), because the full one costs too much RAM
and flash there (DEVICES.md, "Lean cloud shell on the ESP32-C6"). In place
of `net iface`, `net conn` and `wifi status` it has:
Expand Down
2 changes: 2 additions & 0 deletions openspec/changes/consistent-image-names/.openspec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-19
83 changes: 83 additions & 0 deletions openspec/changes/consistent-image-names/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
## Context

`release/devices.yml` lists each device's builds as (app, variant). The
firmware name is `<app>-<variant>-<device>`, and it is everything a person
sees: the release files' stem, the firmware name a device reports, and its
firmware entry in Cumulocity. The operating system only shows where an app
directory (`tedge-agent-idf`) or a variant (`nuttx`) happens to name it.

The firmware name is at most 47 characters: tiny-edge keeps it in a 48-byte
buffer.

## Goals / Non-Goals

**Goals:**

- Every name says its app, operating system, feature set and board, in that
order, so the same app's images on each operating system sort together.
- The manifest enforces the scheme, so a new build cannot break it.

**Non-goals:**

- Renaming app directories, device ids or device types.

## Decisions

### 1. `<app>-<os>-<set>-<board>`

The app comes first, so `tedge-agent-zephyr-full-…`, `tedge-agent-idf-full-…`
and `tedge-agent-nuttx-full-…` sit side by side. The set drops today's
`tedge-` prefix: `full` and `ota` only exist with thin-edge.io, and
`standalone` says it has none. With the prefix, the longest name would also
be at the 47-character limit, and so would the next.

Rejected: the operating system first (groups by operating system, but splits
one app's images apart, which is what a comparison needs side by side).

### 2. `idf` for ESP-IDF

ESP-IDF includes FreeRTOS. `idf` is short, and is what someone rebuilding
the image uses (`idf.py`). `freertos` would not say that the image is built
with ESP-IDF, and `esp-idf` would add a hyphen to a name that is split on
hyphens.

### 3. Variants are named `<os>-<set>`

The manifest's variants become `zephyr-standalone`, `zephyr-full`,
`zephyr-ota`, `idf-full` and `nuttx-full`, and the firmware name keeps its
formula, `<app name>-<variant>-<device>`. The operating system comes from
the variant's `framework` (`zephyr` → `zephyr`, `esp-idf` → `idf`, `nuttx`
→ `nuttx`), and the set from its new `set` field. `matrix.py` checks that
the variant's name is `<os>-<set>`, so the name cannot drift from how the
variant is built.

### 4. The app name can differ from the app directory

The ESP-IDF agent's project is `apps/tedge-agent-idf/`, beside the Zephyr
`apps/tedge-agent/`. A top-level `apps:` section in the manifest gives it
the name `tedge-agent`; an app without an entry is named after its
directory. `matrix.py` rejects two builds with the same firmware name.

### 5. One update moves a device to its new name

A device installs whatever firmware it is sent. It only compares names to
skip reinstalling the exact name and version it already runs. So a device
on `modbus-server-tedge-ota-esp32c6-devkitc 0.16.0` installs
`modbus-server-zephyr-ota-esp32c6-devkitc 0.17.0` from the new entry, and
from then on it reports the new name. The old entries in Cumulocity stay
until someone deletes them.

## Risks / Trade-offs

- A device left on an old name finds no newer version in its old entry.
→ The release notes say once that the names changed, and how to move.
- Links to old release files keep working, but the names differ from later
releases. → DEVICES.md records each measurement under the name it had
then, with a note at its top that maps old names to new ones.

## Migration Plan

1. Merge; the next release (0.17.0) has the new names.
2. Upload the release with `scripts/release/c8y-upload.sh`, which creates the
new firmware entries.
3. Update each device once from its new entry.
65 changes: 65 additions & 0 deletions openspec/changes/consistent-image-names/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
## Why

The release images showcase one device agent on three operating systems, but
their names only sometimes say which one:

- Zephyr: never (`modbus-server-tedge-full-esp32c6-devkitc`).
- ESP-IDF: only in the app's name (`tedge-agent-idf-tedge-onboard-esp32c6-devkitc`).
- NuttX: only in the variant (`tedge-agent-nuttx-esp32c6-devkitc`).

Someone comparing operating systems cannot tell from a release file, a
firmware entry in Cumulocity or the firmware name a device reports which
operating system an image runs, nor which images are the same app.

## What Changes

- **BREAKING** Every image is named `<app>-<os>-<set>-<board>`:
- `<app>`: `modbus-server`, `opcua-server`, `snmp-agent` or `tedge-agent`.
The ESP-IDF agent is `tedge-agent` too; its project stays in
`apps/tedge-agent-idf/`.
- `<os>`: `zephyr`, `idf` (ESP-IDF, which includes FreeRTOS) or `nuttx`.
- `<set>`: `standalone` (the protocol server alone), `full` (every
thin-edge.io feature) or `ota` (connection, telemetry, restart and
firmware update, plus what else fits).
- `<board>`: the device id, as before.

For example `tedge-agent-zephyr-full-esp32c6-devkitc`,
`tedge-agent-idf-full-esp32c6-devkitc` and
`tedge-agent-nuttx-full-esp32c6-devkitc`. The name is the release files'
stem, the firmware name the image reports, and its firmware entry in
Cumulocity. The longest is 47 characters, the most a device stores.
- The manifest's variants are renamed `<os>-<set>`: `zephyr-standalone`,
`zephyr-full`, `zephyr-ota`, `idf-full` and `nuttx-full`. The manifest
rejects a variant whose name does not match its framework and set, and
two builds with the same firmware name.
- The README's supported-devices table and the release notes show the
variants by operating system.
- A device running an image with an old name moves to the new one with a
single update from the new firmware entry. The device does not compare
firmware names when it installs, so nothing on the device changes.

## Capabilities

### New Capabilities

None.

### Modified Capabilities

- `firmware-release`: the variants, the asset stem and the firmware name.

## Impact

- `release/devices.yml`, `scripts/release/` (matrix, packaging, notes,
tests), `release/size-baseline.json` (keyed by firmware name), the
README, DEVICES.md (a note on the old names), and the release workflow's
job names.
- Cumulocity: a release uploads under new firmware entries. The old entries
stay; each device needs one update from its new entry.
- No firmware code changes. Local builds, outside the release, keep their own
names (`zephyr-<app>`, and `tedge-agent-idf-<chip>` on ESP-IDF).

## Non-goals

- Renaming `apps/tedge-agent-idf/` or the Zephyr apps' directories.
- Changing device types, the version scheme or the board ids.
162 changes: 162 additions & 0 deletions openspec/changes/consistent-image-names/specs/firmware-release/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
## RENAMED Requirements

- FROM: `### Requirement: Three variants per build`
- TO: `### Requirement: Variants name the operating system and the feature set`

## MODIFIED Requirements

### Requirement: Variants name the operating system and the feature set

Each build SHALL be one of these variants, named `<os>-<set>`:

| Variant | Operating system | Contents | Set-up |
|---|---|---|---|
| `zephyr-standalone` | Zephyr | a protocol app, no `tiny-edge` code | Improv Wi-Fi over BLE |
| `zephyr-full` | Zephyr | every `tiny-edge` feature (`profiles/full.conf`) | lab-ztp-provisioner |
| `zephyr-ota` | Zephyr | at least connection, inventory, health, telemetry, restart and firmware update (`profiles/ota.conf`), plus the extra features its manifest entry lists | lab-ztp-provisioner |
| `idf-full` | ESP-IDF (FreeRTOS) | the device agent with every `tiny-edge` feature | `tedge-onboard` over USB |
| `nuttx-full` | NuttX | tiny-edge's NuttX agent with every feature | `tedge-onboard` over USB |

`<os>` SHALL follow from the variant's framework (`zephyr`, `idf` for
ESP-IDF, `nuttx`) and `<set>` SHALL be `standalone`, `full` or `ota`; the
manifest SHALL be rejected when a variant's name does not. The Zephyr
`full` and `ota` variants SHALL use the device's shared board-level `tedge`
settings. Every build SHALL be named `<app>-<variant>-<device>`, where
`<app>` is the app's name in the manifest (the ESP-IDF agent in
`apps/tedge-agent-idf/` is `tedge-agent`), and no two builds SHALL share a
name. The release notes SHALL list each `tedge` image's features as read
from its build configuration. No release image SHALL contain Wi-Fi
credentials, a Cumulocity tenant, or any other site-specific setting.

#### Scenario: Protocol apps on the C6 and S3 boards

- **WHEN** a release is built
- **THEN** for each of the ESP32-C6, ESP32-S3-DevKitC and QT Py ESP32-S3,
and each of `modbus-server`, `opcua-server` and `snmp-agent`, there is a
`zephyr-standalone` and a `zephyr-ota` image, and a `zephyr-full` image
wherever its capacity measurement passed

#### Scenario: One app on several operating systems

- **WHEN** a release has the device agent for the ESP32-C6 on Zephyr,
ESP-IDF and NuttX
- **THEN** its images are `tedge-agent-zephyr-full-esp32c6-devkitc`,
`tedge-agent-idf-full-esp32c6-devkitc` and
`tedge-agent-nuttx-full-esp32c6-devkitc`, and so are the firmware names
the devices report

#### Scenario: A variant name that does not match its build

- **WHEN** the manifest names a NuttX variant `zephyr-full`, or gives two
builds the same firmware name
- **THEN** the matrix job fails with a message naming the variant or the
builds, and no build runs

#### Scenario: Most capable image on a constrained board

- **WHEN** `zephyr-full` does not fit or run on a board
- **THEN** that board's `zephyr-ota` image for the app carries every further
feature that passed measurement there, and the notes list them

#### Scenario: Standalone image

- **WHEN** a `zephyr-standalone` image is flashed and provisioned over Improv
- **THEN** the device serves its protocol on the provisioned network and makes
no connection to Cumulocity

#### Scenario: tedge image gets its tenant from provisioning

- **WHEN** a `zephyr-full` or `zephyr-ota` image is flashed and provisioned
by lab-ztp-provisioner
- **THEN** the device joins the network and enrols with the tenant delivered
in the ZTP bundle, without any tenant having been compiled in

#### Scenario: No secrets in the build

- **WHEN** a release build runs
- **THEN** it passes no Wi-Fi, tenant or `*.local.conf` overlay, and the
resulting `.config` has empty `CONFIG_APP_WIFI_SSID` and `CONFIG_TEDGE_C8Y_URL`

### Requirement: Release assets are complete and named consistently

For every build, the release SHALL attach, named with the stem
`<app>-<os>-<set>-<device>-<version>` (the firmware name, then the
version):

- `<stem>.factory.bin` — bootloader, application and provisioner merged into
one image to be written at `0x0`;
- `<stem>.app.bin` — the signed application image alone;
- `<stem>.zip` — the bootloader, the signed application, the signed
provisioner, a `flash.json` giving the chip, flash mode, frequency and size,
each image's offset and partition, the signing key statement, and a
`README.txt` with the flash commands.

The release SHALL attach `SHA256SUMS` covering every asset.

#### Scenario: Offsets match the build

- **WHEN** a bundle is produced for the ESP32-WROOM-32
- **THEN** `flash.json` places the bootloader at `0x1000` and the application
and provisioner at the `slot0_partition` and `prov_partition` offsets of
that build's devicetree

#### Scenario: Checksums

- **WHEN** a user runs `sha256sum -c SHA256SUMS` over the downloaded assets
- **THEN** every asset verifies

### Requirement: tedge images can be installed over the air from Cumulocity

Every `tedge` build SHALL report the firmware name
`<app>-<os>-<set>-<device>` (at most 47 characters), unique per build. Every release SHALL attach `c8y-firmware.json` listing, per `tedge`
build, the firmware name, the version exactly as the image reports it
(`X.Y.Z` or `X.Y.Z-<pre>`), the device type, the `.app.bin` asset name and
its SHA-256. The project SHALL provide a user-run script that uploads a
release's `tedge` application images, pre-releases included, into a
Cumulocity tenant's firmware repository under those names and versions,
idempotently. The workflow itself SHALL hold no Cumulocity credentials.

#### Scenario: Upload and install

- **WHEN** a user runs the upload script for `v0.4.0` against their tenant
and then installs `modbus-server-zephyr-ota-esp32c6-devkitc` `0.4.0` on a C6
running an earlier `tedge` image signed with the same key
- **THEN** the device downloads the image from the tenant, reboots into it,
confirms it, reports `modbus-server-zephyr-ota-esp32c6-devkitc 0.4.0`, and the
operation succeeds

#### Scenario: Only matching images are offered

- **WHEN** an operator opens the firmware repository entry named after a
device's reported firmware name
- **THEN** every version in it was built for that device, app and operating
system

#### Scenario: Running the upload twice

- **WHEN** the upload script is run again for a release already uploaded
- **THEN** it creates nothing new and reports the existing versions

#### Scenario: Pre-release over the air

- **WHEN** `v0.4.0-rc1` is uploaded and installed on a device running
`0.3.x` or `0.4.0-rc0`
- **THEN** the operation succeeds and the device reports `0.4.0-rc1`

#### Scenario: From a pre-release to the final release

- **WHEN** `0.4.0` is installed on a device running `0.4.0-rc1`
- **THEN** the install is accepted, succeeds, and the device reports `0.4.0`

#### Scenario: Checksum mismatch

- **WHEN** a downloaded `.app.bin` does not match `SHA256SUMS`
- **THEN** the script uploads nothing and names the file

#### Scenario: Moving a device to the new names

- **WHEN** a device running `modbus-server-tedge-ota-esp32c6-devkitc` (a name
from before 0.17.0) is sent `modbus-server-zephyr-ota-esp32c6-devkitc`
`0.17.0`
- **THEN** it installs it, confirms it, and reports
`modbus-server-zephyr-ota-esp32c6-devkitc 0.17.0`
Loading
Loading