Add first OTA Crate MVP

Author: fwaibel

.github/workflows/rust.yml

@@ -56,3 +56,5 @@ jobs:
           cargo test -p wifi-pure --features mock --target "${host_target}"
           cargo test -p lora-pure --features mock --target "${host_target}"
           cargo test -p espnow-pure --features mock --target "${host_target}"
+          cargo test -p ota-pure --target "${host_target}"
+          cargo test -p rustyfarian-esp-hal-ota --no-default-features --target "${host_target}"

CHANGELOG.md

@@ -14,6 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **OTA MVP** — three new crates for end-to-end firmware update on ESP32-C3 (and ESP32-C6 / ESP32 for the bare-metal stack), aligned with `docs/adr/011-ota-crate-hosting-and-transport.md` and `docs/features/ota-mvp-v1.md`. All public APIs are explicitly experimental for MVP; stabilization is owned by the future `ota-library` feature.
+  - `ota-pure` (new crate, **experimental API**) — platform-independent, `no_std`, host-tested. Surface: `Version` semver parser (`u16` components, `Display`, `Ord`), `StreamingVerifier` (chunk-fed SHA-256 over `sha2 = { default-features = false }`), `bytes_to_hex` / `hex_to_bytes` fixed-size helpers (returns `heapless::String<64>`), `ImageMetadata` sidecar parser (`.bin.sha256` + `.bin.version`), backend-neutral `OtaState` enum (`Idle → Downloading → Verifying → Writing → SwapPending → Booted`) with `next_state()`, and `OtaError` with the 8 MVP variants (`ServerUnreachable`, `DownloadFailed { status: u16 }`, `DownloadTimeout`, `ChecksumMismatch`, `VersionInvalid`, `FlashWriteFailed`, `PartitionNotFound`, `InsufficientSpace`). `DownloadFailed { status: 0 }` is reserved as a sentinel for protocol-shape rejections from the bare-metal HTTP client. 37 host unit tests.
+  - `rustyfarian-esp-idf-ota` (new crate, **experimental API**, blocking) — ESP-IDF std, lifted from `rustyfarian-beekeeper/src/ota/`. Surface: `OtaSession::new(config)`, `fetch_and_apply(url, &expected_sha256)`, `mark_valid()`, `rollback()`. Wraps `EspOta` / `EspOtaUpdate` and `EspHttpConnection`; streams download → SHA-256 verify (`StreamingVerifier`) → flash → swap in one pass without holding the full image in RAM. Strips RFC 3986 userinfo from URLs before logging (no credential leakage to `espflash monitor`). HTTPS rejected at MVP scope per ADR 011 (`ota-hardened` will revisit).
+  - `rustyfarian-esp-hal-ota` (new crate, **experimental API**, async-only) — bare-metal `no_std`, built fresh against `esp_bootloader_esp_idf::OtaUpdater` over `esp-storage` and `embassy-net::TcpSocket`. Surface: `EspHalOtaManager::new(config, FLASH<'d>)`, `async fetch_and_apply(socket, url, &expected_sha256)`, `mark_valid()`, `rollback()`. Carries an internal hand-rolled HTTP/1.1 GET parser (per ADR 011 §2): accepts only `HTTP/1.1 200 OK` with exactly one valid `Content-Length`; rejects redirects, `Transfer-Encoding: chunked`/`identity`, missing or duplicate `Content-Length`, non-`1*DIGIT` numeric values (incl. leading `+`/`-`), whitespace before colon, oversized bodies, and short reads. Chip features `esp32c3` (MVP), `esp32c6`, `esp32`; stack features `unstable`, `rt`, `embassy`. Host stub mirrors the wifi-crate pattern (typecheck-only). 29 parser unit tests.
+- Workspace: `sha2 = { version = "0.10", default-features = false }`, `esp-storage = "=0.9.0"`, `embedded-storage = "0.3"` added to `[workspace.dependencies]`; `embedded-svc = "0.29"` declared (aligning with `esp-idf-svc 0.52`).
+- Justfile: `check-ota-pure`, `test-ota`, `check-ota-idf`, `check-ota-hal`, `check-ota-hal-embassy`, `test-ota-hal` recipes; `test` aggregate extended.
+- CI (`.github/workflows/rust.yml`): host tests for `ota-pure` and `rustyfarian-esp-hal-ota --no-default-features` added to the "Test pure crates" block.
 - Build scripts: `scripts/detect-port.sh` narrows `espflash`'s auto-detect to USB serial devices (`usbmodem*`/`usbserial*` on macOS, `ttyUSB*`/`ttyACM*` on Linux) so paired Bluetooth ports stop hijacking the probe; used by `flash.sh`, `just run`, `just monitor`, and `just erase-flash`. `ESPFLASH_PORT=…` still wins when set explicitly
 - `rustyfarian-esp-hal-wifi`: `embassy` Cargo feature + `WiFiManager::init_async()` returning an `AsyncWifiHandle { controller, stack, runner }` wired into an `embassy-net` stack with automatic DHCPv4 (`AsyncWifiHandle::wait_for_ip().await` awaits the first lease). Originally landed alongside a synchronous `WiFiManager::init` path that drove `smoltcp` directly; that sync path was removed later in this same release cycle when the stack moved to `esp-radio 0.18` (see the breaking-change entry below). The `embassy` feature is now the only supported Wi-Fi path on bare-metal — see `docs/features/embassy-feature-flag-v1.md` and `docs/features/wifi-manager-async-v1.md`
 - `rustyfarian-esp-hal-wifi`: `hal_c3_connect_async` example — first async bare-metal Wi-Fi demo on ESP32-C3, uses `#[esp_rtos::main]` with two spawned tasks (`wifi_task` for association + reconnection, `net_task` for the embassy-net runner), prints the DHCP-assigned IP and idles asynchronously (see `docs/features/hal-c3-connect-async-example-v1.md`)

Cargo.toml

@@ -14,6 +14,7 @@ rustyfarian-network-pure = { path = "crates/rustyfarian-network-pure" }
 lora-pure = { path = "crates/lora-pure" }
 wifi-pure = { path = "crates/wifi-pure" }
 espnow-pure = { path = "crates/espnow-pure" }
+ota-pure = { path = "crates/ota-pure" }
 
 # External dependencies
 anyhow = "1.0"
@@ -26,9 +27,11 @@ embuild = "0.33"
 esp-idf-svc = "0.52"
 esp-idf-hal = "0.46"
 embedded-hal = "1"
+embedded-svc = "0.29"
 
 # LoRa / LoRaWAN dependencies
 heapless = "0.9"
+sha2 = { version = "0.10", default-features = false }
 lorawan-device = { version = "0.12", default-features = false, features = ["default-crypto", "region-eu868", "region-us915"] }
 lora-modulation = "0.1"
 sx126x = "0.3"
@@ -42,6 +45,8 @@ esp-radio = { version = "=0.18.0", default-features = false }
 esp-rtos = { version = "=0.3.0", default-features = false }
 esp-alloc = { version = "=0.10.0" }
 esp-bootloader-esp-idf = { version = "=0.5.0", default-features = false }
+esp-storage = { version = "=0.9.0", default-features = false }
+embedded-storage = { version = "0.3" }
 esp-println = { version = "=0.17.0", default-features = false }
 # `smoltcp` was dropped from the workspace dependency table when `esp-radio 0.18`
 # removed its `smoltcp` feature in favour of `embassy-net-driver`; no member crate

README.md

@@ -7,7 +7,7 @@
 [![cargo clippy](https://github.com/datenkollektiv/rustyfarian-network/actions/workflows/clippy.yml/badge.svg)](https://github.com/datenkollektiv/rustyfarian-network/actions/workflows/clippy.yml)
 [![cargo audit](https://github.com/datenkollektiv/rustyfarian-network/actions/workflows/audit.yml/badge.svg)](https://github.com/datenkollektiv/rustyfarian-network/actions/workflows/audit.yml)
 
-Wi-Fi, MQTT, LoRa, and ESP-NOW networking libraries for ESP32 projects.
+Wi-Fi, MQTT, LoRa, ESP-NOW, and OTA support libraries for ESP32 projects.
 
 > Note: Large parts of this library (and documentation) were developed with the assistance of AI tools.
 > All generated code has been reviewed and curated by the maintainer.
@@ -23,7 +23,8 @@ Wi-Fi, MQTT, LoRa, and ESP-NOW networking libraries for ESP32 projects.
 - A growing platform-independent layer (`rustyfarian-network-pure`) that can be unit-tested on the host
 - Minimal friction: a few lines of `Cargo.toml` and no surprises
 
-**Out of scope:** Application-layer protocols (HTTP, CoAP, WebSocket) and provisioning/SoftAP flows.
+**Out of scope:** General-purpose application-layer clients (HTTP, CoAP, WebSocket) and provisioning/SoftAP flows.
+The OTA crates (`rustyfarian-esp-idf-ota`, `rustyfarian-esp-hal-ota`) carry their own internal HTTP/1.1 GET clients for firmware download, but these are implementation details and not published as reusable workspace HTTP APIs.
 
 *Full vision, success signals, and open questions: [VISION.md](./VISION.md)*
 
@@ -41,18 +42,21 @@ a pattern common in application development but rare in embedded Rust.
 
 ## Crates
 
-| Crate                                                         | Description                                                                               |
-|:--------------------------------------------------------------|:------------------------------------------------------------------------------------------|
-| [`rustyfarian-network-pure`](crates/rustyfarian-network-pure) | Platform-independent primitives — validation, timing math; unit-testable on the host      |
-| [`wifi-pure`](crates/wifi-pure)                               | Platform-independent Wi-Fi types, traits, and validation; `no_std`; unit-testable on host |
-| [`rustyfarian-esp-idf-wifi`](crates/rustyfarian-esp-idf-wifi) | Wi-Fi connection manager with LED status feedback                                         |
-| [`rustyfarian-esp-hal-wifi`](crates/rustyfarian-esp-hal-wifi) | Wi-Fi driver stub for bare-metal `esp-hal` targets; full implementation in progress       |
-| [`rustyfarian-esp-idf-mqtt`](crates/rustyfarian-esp-idf-mqtt) | MQTT client with automatic reconnection and graceful shutdown                             |
-| [`lora-pure`](crates/lora-pure)                               | Platform-independent LoRa/LoRaWAN types and traits; `no_std`; unit-testable on host       |
-| [`rustyfarian-esp-idf-lora`](crates/rustyfarian-esp-idf-lora) | LoRa radio driver (SX1262) and LoRaWAN adapter for ESP-IDF targets                        |
-| [`rustyfarian-esp-hal-lora`](crates/rustyfarian-esp-hal-lora) | LoRa radio stub for bare-metal `esp-hal` targets; hardware driver in progress             |
+| Crate                                                             | Description                                                                                 |
+|:------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|
+| [`rustyfarian-network-pure`](crates/rustyfarian-network-pure)     | Platform-independent primitives — validation, timing math; unit-testable on the host        |
+| [`wifi-pure`](crates/wifi-pure)                                   | Platform-independent Wi-Fi types, traits, and validation; `no_std`; unit-testable on host   |
+| [`rustyfarian-esp-idf-wifi`](crates/rustyfarian-esp-idf-wifi)     | Wi-Fi connection manager with LED status feedback                                           |
+| [`rustyfarian-esp-hal-wifi`](crates/rustyfarian-esp-hal-wifi)     | Wi-Fi driver stub for bare-metal `esp-hal` targets; full implementation in progress         |
+| [`rustyfarian-esp-idf-mqtt`](crates/rustyfarian-esp-idf-mqtt)     | MQTT client with automatic reconnection and graceful shutdown                               |
+| [`lora-pure`](crates/lora-pure)                                   | Platform-independent LoRa/LoRaWAN types and traits; `no_std`; unit-testable on host         |
+| [`rustyfarian-esp-idf-lora`](crates/rustyfarian-esp-idf-lora)     | LoRa radio driver (SX1262) and LoRaWAN adapter for ESP-IDF targets                          |
+| [`rustyfarian-esp-hal-lora`](crates/rustyfarian-esp-hal-lora)     | LoRa radio stub for bare-metal `esp-hal` targets; hardware driver in progress               |
 | [`espnow-pure`](crates/espnow-pure)                               | Platform-independent ESP-NOW types, traits, and validation; `no_std`; unit-testable on host |
 | [`rustyfarian-esp-idf-espnow`](crates/rustyfarian-esp-idf-espnow) | ESP-NOW driver for ESP-IDF projects, implementing the `EspNowDriver` trait                  |
+| [`ota-pure`](crates/ota-pure)                                     | Platform-independent OTA primitives — `Version`, streaming SHA-256, sidecar metadata        |
+| [`rustyfarian-esp-idf-ota`](crates/rustyfarian-esp-idf-ota)       | ESP-IDF OTA driver — **blocking**; streaming download, SHA-256 verify, partition swap, rollback |
+| [`rustyfarian-esp-hal-ota`](crates/rustyfarian-esp-hal-ota)       | Bare-metal OTA driver — **async-only**; strict HTTP/1.1 over `embassy-net` + `OtaUpdater` (MVP) |
 
 ## Usage
 

VISION.md

@@ -20,6 +20,7 @@ Any ESP32-IDF project can add Wi-Fi and MQTT in minutes, with confidence.
 - **An `esp-hal` bare-metal tier** — dedicated `rustyfarian-esp-hal-*` crates provide bare-metal alternatives alongside the existing ESP-IDF path.
   This generalises the earlier LoRa-only `esp-hal` goal into a workspace-wide pattern: separate crates per HAL tier with shared `*-pure` crates for platform-independent types and traits (see [ADR 005](docs/adr/005-crate-naming-for-dual-hal-drivers.md)).
   Active: `rustyfarian-esp-hal-lora` (LoRa radio driver) and `rustyfarian-esp-hal-wifi` (Wi-Fi via `esp-wifi 0.14.0`, in progress).
+- **OTA as firmware-update plumbing** — OTA support may live in this workspace when it reuses the same Wi-Fi, bootloader, partition-table, and dual-HAL foundations as the networking crates.
 
 ## Target Beneficiaries
 
@@ -28,8 +29,8 @@ but with an API clean enough that any ESP32-IDF project can adopt it with confid
 
 ## Non-Goals
 
-- **Application-layer protocols** — HTTP, CoAP, WebSocket, and similar are out of scope;
-  this library stops at Wi-Fi association and MQTT pub/sub.
+- **General-purpose application-layer clients** — HTTP, CoAP, WebSocket, and similar reusable clients are out of scope.
+  Feature-specific private transports may exist behind crate APIs, such as OTA fetching, but are not exported as protocol libraries.
 - **Provisioning / SoftAP mode** — no captive portal, BLE provisioning, or Wi-Fi setup flows.
 - **Full `no_std` / `esp-hal` MQTT** — MQTT over bare-metal Wi-Fi (`rustyfarian-esp-hal-mqtt`) is a long-term goal but not an active workstream; Wi-Fi association is the current `esp-hal` frontier.
 
@@ -54,3 +55,5 @@ _(none at this time)_
 - 2026-03-12 — `esp-hal` Wi-Fi promoted from non-goal to active goal; LoRa path blocked on hardware.
   `rustyfarian-esp-hal-wifi` added to long-term goals; non-goal narrowed to `esp-hal` MQTT only.
   The `esp-hal` goal was generalised from LoRa-only to a workspace-wide dual-HAL pattern (ADR 005).
+- 2026-04-29 — OTA accepted as firmware-update plumbing in this workspace, with private transports only.
+  General-purpose HTTP clients remain a non-goal (ADR 011).

crates/ota-pure/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "ota-pure"
+version = "0.1.0"
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Platform-independent OTA primitives — version parsing, streaming SHA-256, metadata"
+keywords = ["ota", "embedded", "no-std"]
+categories = ["embedded", "no-std"]
+
+[dependencies]
+sha2 = { workspace = true, default-features = false }
+heapless = { workspace = true }

crates/ota-pure/src/error.rs

@@ -0,0 +1,54 @@
+//! OTA error types.
+
+use core::fmt;
+
+/// Experimental: API may change before 1.0.
+///
+/// Errors that can occur during OTA updates.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum OtaError {
+    /// The update server could not be reached.
+    ServerUnreachable,
+    /// The download request returned a non-200 HTTP status, or the server
+    /// response failed a strict-protocol check.
+    ///
+    /// `status == 0` is a sentinel for "protocol-shape rejection" — used by
+    /// the bare-metal HTTP client when a response is syntactically rejected
+    /// before a status code is meaningful (e.g. `Transfer-Encoding: chunked`
+    /// or another unsupported response shape). Any non-zero value is the
+    /// HTTP status code returned by the server.
+    DownloadFailed {
+        /// HTTP status code returned by the server, or `0` for a
+        /// protocol-shape rejection (see variant docs).
+        status: u16,
+    },
+    /// The download did not complete within the allowed time.
+    DownloadTimeout,
+    /// The computed SHA-256 digest does not match the expected value.
+    ChecksumMismatch,
+    /// The version string could not be parsed.
+    VersionInvalid,
+    /// Writing to flash failed.
+    FlashWriteFailed,
+    /// The OTA partition could not be located.
+    PartitionNotFound,
+    /// There is not enough flash space for the new image.
+    InsufficientSpace,
+}
+
+impl fmt::Display for OtaError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            OtaError::ServerUnreachable => write!(f, "Update server unreachable"),
+            OtaError::DownloadFailed { status } => {
+                write!(f, "Download failed with status {status}")
+            }
+            OtaError::DownloadTimeout => write!(f, "Download timeout"),
+            OtaError::ChecksumMismatch => write!(f, "Firmware checksum mismatch"),
+            OtaError::VersionInvalid => write!(f, "Firmware version invalid"),
+            OtaError::FlashWriteFailed => write!(f, "Flash write failed"),
+            OtaError::PartitionNotFound => write!(f, "OTA partition not found"),
+            OtaError::InsufficientSpace => write!(f, "Insufficient flash space"),
+        }
+    }
+}

crates/ota-pure/src/lib.rs

@@ -0,0 +1,17 @@
+#![no_std]
+//! Platform-independent OTA primitives — Version parsing, streaming SHA-256,
+//! sidecar metadata, backend-neutral state machine.
+//!
+//! All public APIs are experimental.
+
+pub mod error;
+pub mod metadata;
+pub mod state;
+pub mod verifier;
+pub mod version;
+
+pub use error::OtaError;
+pub use metadata::ImageMetadata;
+pub use state::OtaState;
+pub use verifier::{bytes_to_hex, hex_to_bytes, StreamingVerifier};
+pub use version::Version;

crates/ota-pure/src/metadata.rs

@@ -0,0 +1,73 @@
+//! Firmware image sidecar metadata parser.
+
+use crate::error::OtaError;
+use crate::verifier::hex_to_bytes;
+use crate::version::Version;
+
+/// Experimental: API may change before 1.0.
+///
+/// Sidecar metadata for a firmware image.
+///
+/// Parsed from the `.bin.sha256` (64-char hex digest) and `.bin.version`
+/// (semver string) sidecar files that accompany each firmware image.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageMetadata {
+    /// Expected SHA-256 digest of the firmware image.
+    pub sha256: [u8; 32],
+    /// Declared firmware version.
+    pub version: Version,
+}
+
+impl ImageMetadata {
+    /// Experimental: API may change before 1.0.
+    ///
+    /// Parse metadata from raw sidecar strings.
+    ///
+    /// `sha256_hex` must be a 64-character lowercase (or uppercase) hex string.
+    /// `version_str` must be a `"MAJOR.MINOR.PATCH"` semver string.
+    /// Both inputs are trimmed of leading/trailing whitespace before parsing.
+    ///
+    /// Returns `Err(OtaError::ChecksumMismatch)` for a malformed digest, or
+    /// `Err(OtaError::VersionInvalid)` for a malformed version string.
+    pub fn parse(sha256_hex: &str, version_str: &str) -> Result<Self, OtaError> {
+        let sha256 = hex_to_bytes(sha256_hex.trim())?;
+        let version = Version::parse(version_str.trim())?;
+        Ok(Self { sha256, version })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const HELLO_HASH: &str = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
+
+    #[test]
+    fn parse_valid_metadata() {
+        let m = ImageMetadata::parse(HELLO_HASH, "1.2.3").unwrap();
+        assert_eq!(m.version, Version::new(1, 2, 3));
+        assert_eq!(m.sha256[0], 0x2c);
+    }
+
+    #[test]
+    fn parse_trims_whitespace() {
+        // Build padded hex without heap allocation.
+        use core::fmt::Write as _;
+        let mut padded = heapless::String::<68>::new();
+        write!(padded, "  {HELLO_HASH}  ").unwrap();
+        let m = ImageMetadata::parse(padded.as_str(), "  0.1.8\n").unwrap();
+        assert_eq!(m.version, Version::new(0, 1, 8));
+    }
+
+    #[test]
+    fn parse_invalid_hash_returns_checksum_error() {
+        let result = ImageMetadata::parse("not-a-hash", "1.0.0");
+        assert_eq!(result, Err(OtaError::ChecksumMismatch));
+    }
+
+    #[test]
+    fn parse_invalid_version_returns_version_error() {
+        let result = ImageMetadata::parse(HELLO_HASH, "bad-version");
+        assert_eq!(result, Err(OtaError::VersionInvalid));
+    }
+}