diff --git a/openspec/changes/nuttx-port/.openspec.yaml b/openspec/changes/archive/2026-11-18-nuttx-port/.openspec.yaml similarity index 100% rename from openspec/changes/nuttx-port/.openspec.yaml rename to openspec/changes/archive/2026-11-18-nuttx-port/.openspec.yaml diff --git a/openspec/changes/nuttx-port/design.md b/openspec/changes/archive/2026-11-18-nuttx-port/design.md similarity index 100% rename from openspec/changes/nuttx-port/design.md rename to openspec/changes/archive/2026-11-18-nuttx-port/design.md diff --git a/openspec/changes/nuttx-port/proposal.md b/openspec/changes/archive/2026-11-18-nuttx-port/proposal.md similarity index 100% rename from openspec/changes/nuttx-port/proposal.md rename to openspec/changes/archive/2026-11-18-nuttx-port/proposal.md diff --git a/openspec/changes/nuttx-port/specs/tedge-nuttx-port/spec.md b/openspec/changes/archive/2026-11-18-nuttx-port/specs/tedge-nuttx-port/spec.md similarity index 100% rename from openspec/changes/nuttx-port/specs/tedge-nuttx-port/spec.md rename to openspec/changes/archive/2026-11-18-nuttx-port/specs/tedge-nuttx-port/spec.md diff --git a/openspec/changes/nuttx-port/tasks.md b/openspec/changes/archive/2026-11-18-nuttx-port/tasks.md similarity index 99% rename from openspec/changes/nuttx-port/tasks.md rename to openspec/changes/archive/2026-11-18-nuttx-port/tasks.md index 6925c2e..15b5026 100644 --- a/openspec/changes/nuttx-port/tasks.md +++ b/openspec/changes/archive/2026-11-18-nuttx-port/tasks.md @@ -66,7 +66,7 @@ - [x] 9.3 Add NuttX to the top-level README's port table and port comparison - [x] 9.4 Update `REPORT.md` with the final sizes and a short summary; keep it as the record of what NuttX needed (2026-11-17: summary, status per stage, findings 24–31, sizes for the S3, C6 and C3 agents, line counts) - [x] 9.5 Fix the two format warnings in `core/src/tedge_core.c` in a separate pull request (`PRIu32`) (2026-11-17: thin-edge/tiny-edge#20; checked with `riscv-none-elf-gcc -Werror`. The download idle timeout from 5.6 went out separately too, as #21 with unit tests) -- [ ] 9.6 Offer the two USB serial driver fixes to NuttX upstream (deferred 2026-11-17 by the maintainer) +- [ ] 9.6 Offer the two USB serial driver fixes to NuttX upstream (deferred 2026-11-17 by the maintainer; tracked in thin-edge/tiny-edge#30) - [x] 9.7 Confirm that `git diff main -- core/ provisioning/ include/tedge/port/` is empty (2026-11-17: empty after rebasing on 0.6.1, which has #20 and #21) ## 10. Release (thin-edge/microcontroller-devices, separate pull request) diff --git a/openspec/specs/tedge-nuttx-port/spec.md b/openspec/specs/tedge-nuttx-port/spec.md new file mode 100644 index 0000000..1a8ac85 --- /dev/null +++ b/openspec/specs/tedge-nuttx-port/spec.md @@ -0,0 +1,185 @@ +# tedge-nuttx-port Specification + +## Purpose +How tiny-edge builds and runs as a NuttX application: the port in `ports/nuttx/`, built on the POSIX port, with MCUboot A/B firmware updates on the ESP32-C6, ESP32-C3 and ESP32-S3. +## Requirements +### Requirement: tiny-edge builds as a NuttX application + +`ports/nuttx/` SHALL build tiny-edge as an application that nuttx-apps +includes as an external directory, with NuttX's Make build and, where +NuttX offers one for the board, its CMake build. It SHALL compile the core, +the provisioning library, the POSIX port's sources, and `ports/common/` +from the repository, not copies of them. + +#### Scenario: Build for a supported board + +- **WHEN** nuttx-apps includes `ports/nuttx/` and `esp32s3-devkit` or + `esp32c6-devkitc` is configured with the port's configuration +- **THEN** NuttX builds an image with the tiny-edge app, from the same core + sources the Zephyr and FreeRTOS ports build + +#### Scenario: CI builds it + +- **WHEN** a pull request changes `core/`, `provisioning/`, `ports/posix/`, + `ports/common/`, or `ports/nuttx/` +- **THEN** CI builds the app for the ESP32-S3 and the ESP32-C6 with every + feature, and for one board with a reduced feature set, and fails the pull + request if a build fails + +#### Scenario: A changed configuration + +- **WHEN** the build script builds with a configuration that differs from + the last build's +- **THEN** it rebuilds every object, so no object built for another + configuration is linked in + +### Requirement: Features are selected with the other ports' options + +Each feature SHALL have the `CONFIG_TEDGE_*` Kconfig option of the same +name and default as on Zephyr and ESP-IDF: telemetry, health, restart, +firmware update, shell command, log upload, remote access, parameters, +certificate renewal, and set-up over USB, and the authentication and MQTT +endpoint choices. The device SHALL advertise only the operations of the +features built in. + +#### Scenario: A reduced build + +- **WHEN** the app is built with firmware update, shell command, log + upload, and remote access off +- **THEN** it builds, connects, and advertises neither firmware update, + shell command, log upload, nor remote access + +### Requirement: The core and other ports stay free of NuttX code + +The port SHALL NOT change `core/`, `provisioning/`, or the port interface. +Code specific to NuttX SHALL be only in `ports/nuttx/`. A change to +`ports/posix/` SHALL be an option that any POSIX system can use, named for +what it does, and SHALL keep today's behavior when it is not set. + +#### Scenario: A NuttX difference in the POSIX port + +- **WHEN** the POSIX port uses a call that NuttX lacks or implements + differently +- **THEN** the POSIX port gains an option for the alternative, the NuttX + port sets it, and the POSIX tests on Linux and macOS pass with it on and + off + +### Requirement: The device connects to Cumulocity and reports itself + +The device SHALL enroll with the Cumulocity CA or use bootstrap +credentials, connect over mTLS to the MQTT Service, and send the same +messages as on the other ports. `tedge_OS` SHALL report `nuttx` and its +release, and `c8y_Hardware` SHALL report the chip and the Wi-Fi MAC +address. Threads SHALL get the stack sizes the core asks for. + +#### Scenario: First connection + +- **WHEN** a set-up device starts with a network +- **THEN** it sets its clock from the network, connects to Cumulocity, its + twin shows `c8y_Agent`, `tedge_OS`, and `c8y_Hardware`, and the `device` + measurement arrives every interval + +#### Scenario: A long session + +- **WHEN** the device runs for 30 minutes with telemetry and a remote access + tunnel, with no program on the computer reading its USB port +- **THEN** no thread overflows its stack, the free heap stays steady, and + the device keeps answering operations + +### Requirement: Device management works as on the other ports + +The device SHALL restart from the cloud with a board reset, keep its +settings and key on LittleFS, apply and keep parameters, upload logs, open +remote access tunnels, renew its certificate, and report an operation +interrupted by a reset as failed after the reboot. + +#### Scenario: Restart from the cloud + +- **WHEN** Cumulocity sends a restart operation +- **THEN** the board resets, joins the network again, connects with the + stored certificate, and reports the operation as successful + +#### Scenario: Parameters persist + +- **WHEN** a parameter set changes from Cumulocity and the board restarts +- **THEN** the board reports the changed values after the restart + +### Requirement: Shell commands run NSH commands + +With `CONFIG_TEDGE_SHELL_COMMAND`, the device SHALL run a `c8y_Command` +that its allow-list permits as an NSH command, return its output up to the +configured limit, and fail the operation when the command is not allowed +or runs longer than the timeout. + +#### Scenario: An allowed command + +- **WHEN** Cumulocity sends `c8y_Command` with `free`, which the allow-list + permits +- **THEN** the operation succeeds with the command's output as its result + +#### Scenario: A command not allowed + +- **WHEN** Cumulocity sends a command the allow-list does not permit +- **THEN** the operation fails with a reason that says the command is not + allowed, and nothing runs + +### Requirement: Firmware updates go through MCUboot + +The port SHALL implement `firmware.h` on NuttX's MCUboot support: write +the new image to the secondary slot, boot it on trial, confirm it once the +core says the image has proven itself, and report the running image's +version. A reset before confirmation SHALL bring the previous image back. +The build SHALL fail when the image does not fit its slot. + +#### Scenario: A successful update + +- **WHEN** Cumulocity installs a newer signed image on the device +- **THEN** the device writes it, restarts into it, connects, confirms it, + and reports the new version and a successful operation + +#### Scenario: An image that does not confirm + +- **WHEN** the new image cannot connect within the core's confirmation time +- **THEN** the device restarts into the previous image and reports the + operation as failed + +### Requirement: tedge-onboard sets the device up over USB + +The port SHALL run Improv Serial on the board's USB serial console, apply +the Wi-Fi network it receives and store it, list the networks the device +sees when asked, and go back to the stored network when a new one cannot be +joined, so `tedge-onboard` sets up a NuttX device with no change to the +tool. Log lines on the console SHALL NOT break Improv frames, and SHALL NOT +stall the device when no program reads the port. + +#### Scenario: Set-up of a new device + +- **WHEN** a user runs `tedge-onboard` with a NuttX board on USB that has a + cleared data partition +- **THEN** the tool finds the board, lists the networks the board sees, + gives it the chosen network, the tenant, and a one-time password, and the + device connects with the device type its firmware reports + +#### Scenario: A wrong password + +- **WHEN** the tool gives the board a network it cannot join +- **THEN** the board reports that it could not join, and joins its stored + network again + +### Requirement: The port is documented and released like the others + +`ports/nuttx/README.md` SHALL describe, as the other ports' READMEs do, +how to add the port to an application, its options, how each port +interface maps to NuttX, how to set a device up, its status per board, and +what is not in the port yet. The top-level README SHALL list the port. The +sample agent SHALL be released as a device image for the ESP32-C6 from +thin-edge/microcontroller-devices, with its own device type and a firmware +entry for Cumulocity. + +#### Scenario: A user picks the NuttX image + +- **WHEN** a user downloads the NuttX agent image from a + microcontroller-devices release and flashes it +- **THEN** `tedge-onboard` sets the device up, and Cumulocity offers later + releases of the same image as firmware updates for that device type +