spaxel/docs/notes/firmware-host-test-approach.md

# Firmware Host-Based Test Approach — Decision Record

**Bead:** bf-21t (decision spike; parent harness bead: bf-4ne)
**Date:** 2026-07-03
**Decision:** **gcc host harness** (plain gcc-compiled test runner under `firmware/test/`,
*not* the ESP-IDF `--target linux` / Unity-host path).

This is a decision spike only. It records *why* the ESP-IDF linux target was rejected
so that the harness build-out (bf-4ne) does not have to re-derive it. The chosen
approach and the reason below **must be carried into bf-4ne's test-runner header
comment**.

---

## TL;DR

`firmware/main/*.c` cannot be compiled for the ESP-IDF `linux` target because the
core files pull in **hardware-radio / peripheral drivers that have no host build**:

- `csi.c` → `esp_wifi.h` (CSI callback + promiscuous-mode API) — no host build.
- `provision.c` → `driver/uart.h` (UART provisioning window) — no host build.

The firmware is built as a single `main` component, so the whole component must
link for any one file to be host-tested via `idf.py --target linux`. It doesn't, so
the linux target is impractical. Fall back to a gcc harness that **does not link
`firmware/main/*.c` directly** — it tests pure-logic extractions and binary-format
contracts instead.

---

## Investigation

ESP-IDF was not installed on the investigation host (`IDF_PATH` unset, no `idf.py`),
so this is reasoned from the source plus the documented ESP-IDF `linux`-target
component matrix (IDF 5.2.x, the version pinned for this project). gcc 14.2 is
available, which the fallback path requires.

### What the ESP-IDF `linux` target provides

Host builds exist for the "hostable" components:
`nvs_flash`/`nvs` (file-backed host emulation — the canonical IDF host-test
example), `esp_log`, `esp_timer`, `esp_event`, `freertos` (POSIX/SMP-on-host
port — so `freertos/task.h`, `queue.h`, `event_groups.h`, `semphr.h` resolve),
`cJSON` (pure C), and partial `esp_netif`/`mbedtls`.

What it does **not** provide (hardware/peripheral-only, target-arch):
`esp_wifi` (depends on the radio MAC/baseband binary blob), the entire
`driver/*` namespace (`uart`, `gpio`, `temperature_sensor`, …), `esp_bt`/BLE,
`esp_http_server`/`esp_http_client`/`esp_websocket_client`, `esp_ota_ops`,
`mdns`, `lwip` (as these files use it).

### Per-file verdict for the three target files

| File | Non-hostable include | Specific symbols used | linux target |
|------|----------------------|-----------------------|--------------|
| `nvs_migration.c` | — (only `nvs`, `esp_log`, `spaxel.h`) | `nvs_open/get_str/set_str/commit/erase_key`, `nvs_handle_t` | ✅ feasible *in isolation* |
| `csi.c` | `esp_wifi.h` | `wifi_csi_info_t`, `wifi_csi_config_t`, `esp_wifi_set_csi_config`, `esp_wifi_set_csi_rx_cb`, `esp_wifi_set_csi`, `esp_wifi_set_promiscuous` | ❌ **blocked** |
| `provision.c` | `driver/uart.h` | `uart_param_config`, `uart_driver_install`, `uart_write_bytes`, `uart_read_bytes`, `uart_driver_delete`, `UART_NUM_0`, `uart_config_t`, `UART_DATA_8_BITS` | ❌ **blocked** |

### Why the lone feasible file doesn't rescue the approach

`nvs_migration.c` is the one file whose dependency set (`nvs` + `esp_log` +
`freertos`, transitively via `spaxel.h`) is entirely hostable — NVS has a real
file-backed host build. So *in isolation* it could be run through the IDF linux
target. But:

1. The firmware compiles `main` as **one component** —
   `firmware/main/CMakeLists.txt`'s `idf_component_register(...)` lists every
   `*.c` as SRCS and declares
   `REQUIRES esp_wifi esp_netif nvs_flash esp_http_client esp_timer bt driver log esp_http_server mbedtls app_update json freertos`
   (verified verbatim in the tree). That `REQUIRES` line itself names `esp_wifi`,
   `bt`, and `driver` — three components with **no `linux` build** — so the `main`
   component cannot even be configured for the host target, regardless of which
   translation unit you care about. The IDF host-test model builds whole
   components, not cherry-picked TUs; `csi.c`, `wifi.c`, `websocket.c`, `ble.c`,
   `provision.c`, `led.c`, `ntp.c` all drag in unhostable drivers.
2. Making `main` linkable for the host would mean wrapping every driver include
   in host/target `#ifdef` guards or splitting hardware code into a separate
   component — i.e. refactoring production firmware purely to satisfy host
   tests, which risks the on-target build and defeats the purpose.
3. Even if it worked, you would then run **two different test mechanisms** (IDF
   linux for nvs, gcc for csi/prov). A single coherent harness is simpler and is
   what the parent bead (bf-4ne) asks for.

Conclusion: the ESP-IDF linux target is **rejected** as the unified harness
approach.

---

## Decision: gcc host harness under `firmware/test/`

A plain gcc-compiled test runner that:

- Does **not** `#include` or link `firmware/main/*.c` directly (they can't compile
  without the ESP-IDF target toolchain).
- Instead tests:
  - **Pure-logic extractions** — small, dependency-free pieces of behavior copied
    into separately-compilable test units (e.g. the Welford amplitude-variance in
    `csi.c`, the JSON→NVS-key mapping in `provision.c`, the migration-step logic
    in `nvs_migration.c`), *or* refactored into `*_logic.c` files with zero `esp_`
    includes that both the firmware and the harness can compile.
  - **Binary-format contracts** — the 24-byte CSI frame layout and the
    provisioning JSON schema, validated by re-implementing a reference
    encoder/decoder in the test.
- Uses assert-style macros (or Unity host) — either is fine; the key constraint is
  "compiles with plain gcc, no ESP-IDF toolchain."
- Is wired so adding new `test_*.c` files later is trivial (convention-based or a
  single `SOURCES` list), per bf-4ne.

### What this does NOT cover (accepted trade-off)

The gcc harness cannot exercise the actual `esp_wifi`/`uart`/`nvs` call sites —
those remain validated on-target (and via the Go-side `spaxel-sim` acceptance
suite, which already drives the full node→mothership contract host-free). The
firmware host tests are a *logic-and-format* safety net, not a hardware test.

---

## Carry-forward into child 2 (bf-4ne — the harness build-out)

bf-4ne must, in its test-runner header comment, state:

1. **Chosen approach:** gcc host harness.
2. **Concrete reason:** `csi.c` is blocked by `esp_wifi.h` and `provision.c` by
   `driver/uart.h`; neither has an ESP-IDF `linux`-target build, so
   `firmware/main/*.c` cannot be linked directly and the Unity/`idf.py --target
   linux` path was rejected. (Even `nvs_migration.c`, the lone hostable file,
   is blocked because `main` builds as one component.)
3. **The single documented run command** for the harness.

This doc (`docs/notes/firmware-host-test-approach.md`) is the durable reference
for that comment.