qtalker---/firmware/esp32p4-sensor-node/README.md

# Quantumancy ESP32-P4 Sensor Node

Firmware for the paired hardware sensor node described in
[`docs/superpowers/specs/2026-07-23-esp32-sensor-node-design.md`](../../docs/superpowers/specs/2026-07-23-esp32-sensor-node-design.md)
("Workstream I — firmware, ESP-IDF C — core sensor node"). Real ESP-IDF C
(FreeRTOS-based), not Arduino, not pseudocode. Connects to the seeker's home
Wi-Fi, samples a small set of sensors, and POSTs readings to the Quantumancy
backend's `POST /api/device/telemetry` endpoint, which feeds them into the
séance's live anomaly-detection pipeline as a sixth signal source alongside
`wire`/`evp`/`radio`/`emf`.

## Honesty policy — READ THIS FIRST

> This app's whole ethos is "real signal processing on real data, and it
> says so when something is unverified."

**Nobody working on this had physical ESP32-P4 hardware, a BME280, or an
LD2410 module to flash and test against.** Everything in this directory is
real, structurally-correct ESP-IDF C, written against ESP-IDF's documented
APIs and each sensor's public datasheet/protocol documentation, and reasoned
about carefully — but it has **never been compiled with a real ESP-IDF
toolchain, never been flashed, and never talked to real hardware.** Treat
every claim below as "should work, per the docs" rather than "confirmed
working." See [What's verified vs. not](#whats-verified-vs-not) for the
specific, itemized breakdown — this mirrors the same convention
`frontend/src/lib/sdr.ts`'s `HARDWARE PASS REQUIRED` header comment uses
elsewhere in this repo.

## Directory layout

```
firmware/esp32p4-sensor-node/
├── CMakeLists.txt              top-level ESP-IDF project file
├── sdkconfig.defaults          seed config (idf.py generates the real sdkconfig)
├── README.md                   this file
├── components/                 reserved for Workstream J (RTL-SDR), empty here
└── main/
    ├── CMakeLists.txt          component registration
    ├── app_main.c              entry point / boot sequence
    ├── device_config.h.example template you copy to device_config.h
    ├── wifi_manager.{h,c}      Wi-Fi station mode connect/reconnect
    ├── telemetry_client.{h,c}  HTTP POST task -> /api/device/telemetry
    ├── sensor_driver.h         the sensor_driver_t registry interface
    ├── sensor_registry.{h,c}   the concrete list of compiled-in drivers
    ├── bme280.{h,c}            temperature/humidity/pressure over I2C
    └── ld2410.{h,c}            presence/distance over UART
```

## Build instructions

Requires an ESP-IDF install (v5.3 or newer — ESP32-P4 target support landed
around v5.2/5.3; this was written without a toolchain available to pin an
exact tested version, see honesty section). With `idf.py` on your `PATH`
(e.g. after sourcing ESP-IDF's `export.sh`):

```sh
cd firmware/esp32p4-sensor-node

# 1. Fill in your Wi-Fi + pairing details (see next section) — the build
#    will fail on a missing #include until you do this.
cp main/device_config.h.example main/device_config.h
$EDITOR main/device_config.h

# 2. Target and build.
idf.py set-target esp32p4
idf.py build

# 3. Flash + monitor (adjust the port for your machine).
idf.py -p /dev/ttyUSB0 flash monitor
```

## Manual configuration (no provisioning UI — by design)

A full BLE/Wi-Fi-AP provisioning flow is explicitly out of scope for this
spec (see the spec's "Explicitly out of scope" section). Instead, you
hand-edit one header before building:

1. In the Quantumancy web app, sign in and create a device from your
   account (name + optional sensor-type hint). The backend shows you a
   **raw pairing token exactly once** — copy it immediately, it cannot be
   retrieved again (same one-time-secret convention as the site's session
   tokens).
2. `cp main/device_config.h.example main/device_config.h`
3. Edit `main/device_config.h` and fill in:
   - `DEVICE_WIFI_SSID` / `DEVICE_WIFI_PASSWORD` — your home Wi-Fi.
   - `DEVICE_BACKEND_BASE_URL` — the backend's base URL, no trailing slash.
   - `DEVICE_PAIRING_TOKEN` — the raw token from step 1.
   - `DEVICE_REPORT_INTERVAL_SEC` — optional, defaults to 15s.
4. `main/device_config.h` is listed in `.gitignore` — it will never be
   committed. Never put real credentials in `device_config.h.example`
   itself; that file is the template everyone else copies.

There is deliberately no other config path (no NVS-based captive portal, no
BLE provisioning) in this build — see the spec's scope boundary.

## What's verified vs. not

**Structurally verified** (reasoned through carefully against ESP-IDF's
documented API surface and each sensor's public protocol docs; internally
consistent; no known syntax errors or obviously-wrong API usage):

- Project skeleton (`CMakeLists.txt` × 2, `sdkconfig.defaults`,
  `idf_component_register` call) follows ESP-IDF's standard project layout.
- Wi-Fi station-mode connect/reconnect (`wifi_manager.c`) follows ESP-IDF's
  documented event-driven pattern (`WIFI_EVENT`/`IP_EVENT` handlers +
  `EventGroupHandle_t`), extended with an exponential-backoff reconnect
  timer instead of giving up after N tries.
- HTTP client (`telemetry_client.c`) builds the exact JSON shape the spec's
  contract defines and POSTs it via `esp_http_client` with
  `Authorization: Bearer <token>` and `Content-Type: application/json`.
- BME280 driver (`bme280.c`): register map and the double-precision
  compensation formulas are transcribed from Bosch's public BME280
  datasheet (rev 1.23, §4.2.2–4.2.3) — this is well-trodden, publicly
  documented territory, and the formulas are checkable line-by-line against
  the datasheet. Uses ESP-IDF's newer `driver/i2c_master.h` API (the
  current idiomatic choice; the older `driver/i2c.h` is being phased out).
- LD2410 driver (`ld2410.c`): UART frame envelope (header/footer magic
  bytes, length-prefixed payload) follows the shape consistently reported
  across public LD2410 protocol write-ups. **The exact payload byte offsets
  for target state / distances / energies are the single least-certain
  piece of code in this entire firmware** — see the detailed note in
  `ld2410_parse_payload()`. The driver defends itself with a head/tail
  marker sanity check (`0xAA`/`0x55`) and silently skips anything that
  doesn't match rather than reporting garbage, but that check catches
  gross corruption, not subtle off-by-one offset errors.
- Sensor driver registry (`sensor_driver.h`, `sensor_registry.c`): a
  `sensor_driver_t { name, init, read }` struct, a compile-time array of
  them, and generic init/collect functions that `app_main.c` and
  `telemetry_client.c` call without knowing which concrete sensors exist.

**NOT verified — requires real hardware bring-up:**

- `idf.py build` has never actually been run in this environment (no
  ESP-IDF toolchain installed here) — there could be a typo, a missing
  include, or an API signature mismatch against whatever exact ESP-IDF
  version you build with that only a real compile will surface.
- I2C timing/electricals: pull-up resistor values, bus speed headroom,
  cable length — none of this has been bench-tested.
- BME280 compensation formula correctness in practice: the math is
  transcribed carefully, but "matches the datasheet" and "produces a
  plausible number when this exact C runs on this exact silicon" are
  different claims until someone compares a real reading to a reference
  thermometer/barometer.
- LD2410 frame parsing, as above — verify against a logic analyzer capture
  or a known-good reference implementation (e.g. the `ncmreynolds/ld2410`
  or `iavorvel/MyLD2410` Arduino libraries, cross-checked) before trusting
  field values.
- Wi-Fi reconnect behavior under real-world conditions (router reboot,
  weak signal, captive portals) — the backoff logic is reasoned about, not
  soak-tested.
- HTTP client behavior against the real backend: TLS handshake against
  its actual certificate, real latency, real error responses. The
  `sdkconfig.defaults` enables mbedTLS's full certificate bundle for this,
  but that's untested against the live deploy.
- Timing/power: task stack sizes (`telemetry_task`'s 8192 words, etc.) are
  reasonable guesses, not measured high-water-marks from a real run.
- **The ESP32-P4-has-no-integrated-Wi-Fi caveat below** — this is a real
  hardware architecture question, not just an untested detail.

## Important hardware caveat: ESP32-P4 has no integrated Wi-Fi radio

The ESP32-P4 SoC (per Espressif's own published specs) has **no built-in
2.4GHz radio**. A real deployment needs one of:

- **A companion Wi-Fi chip** (e.g. ESP32-C6) wired to the P4 via SDIO or
  SPI, running Espressif's "esp-hosted" firmware/driver stack. Critically,
  esp-hosted presents the *same* `esp_wifi`/`esp_netif` API this firmware
  already uses — so `wifi_manager.c` should not need to change, only board
  wiring and `sdkconfig` (host-side esp-hosted config) would.
- **Building this same code against a Wi-Fi-native target instead**, e.g.
  `idf.py set-target esp32s3` or `esp32c6`. The application code
  (`wifi_manager.c`, `telemetry_client.c`, the sensor drivers) is written
  against the standard API surface and doesn't reference P4-specific
  peripherals for anything except I2C/UART GPIO numbers, so it should be
  largely target-portable.

This wasn't in the original spec's framing but matters enough for a real
build that it's called out here explicitly, in the honesty-policy spirit —
better to flag a real hardware-architecture gap than let someone discover
it after ordering a bare P4 dev board expecting it to just join Wi-Fi.

## Wiring / pinout

### BME280 (I2C) — temperature, humidity, pressure

Chosen as the concrete default sensor per the spec ("a common,
well-documented sensor... pick this as the concrete default since no
specific part number was given").

| BME280 pin | Connects to                          |
|------------|---------------------------------------|
| VCC        | 3V3                                    |
| GND        | GND                                    |
| SDA        | GPIO8 (`BME280_I2C_SDA_GPIO`)          |
| SCL        | GPIO9 (`BME280_I2C_SCL_GPIO`)          |
| CSB        | VCC (selects I2C mode, not SPI)        |
| SDO        | GND → I2C address `0x76` (default assumed; tie to VCC + change `BME280_I2C_ADDR` for `0x77`) |

GPIO numbers are `#define`s at the top of `bme280.h` — override them there
(or via a future `idf.py menuconfig` entry) to match your actual wiring.
100kHz I2C clock by default (`BME280_I2C_CLK_HZ`); the part supports faster
modes if your wiring/pull-ups support it.

### LD2410 (UART) — presence, distance, motion

**Chosen over a plain PIR** — see the rationale in `ld2410.h`'s header
comment: the LD2410 reports moving-target and stationary-target distance
and energy separately, not just a boolean, which is richer signal for the
anomaly pipeline and better matches this app's "believable" ethos (it can
distinguish "someone crossed the room" from "the sitter shifted in their
chair" in a way a boolean PIR cannot). The tradeoff is a materially more
complex protocol than a PIR's single GPIO pin — see the honesty note in
[What's verified vs. not](#whats-verified-vs-not) about the LD2410 frame
parser being the least-certain code in this firmware. If you'd rather start
with a boolean PIR for a faster, more certain first bring-up, it fits the
same `sensor_driver_t` interface — see
[Adding a new sensor](#adding-a-new-sensor) below.

| LD2410 pin | Connects to                          |
|------------|----------------------------------------|
| VCC        | 5V (sensor front-end runs at 5V; confirm your board revision's UART logic level before wiring directly to a 3.3V-only UART pin) |
| GND        | GND                                     |
| TX         | GPIO17 (`LD2410_UART_RX_GPIO`, ESP32 RX) |
| RX         | GPIO18 (`LD2410_UART_TX_GPIO`, ESP32 TX) |

Default UART settings: 256000 baud, 8N1 (module factory default), reporting
in "basic" (non-engineering) mode. GPIO numbers and baud rate are
`#define`s at the top of `ld2410.h`.

## Sensor driver registry — the extensibility pattern

`sensor_driver.h` defines:

```c
typedef struct {
    char sensor_type[SENSOR_READING_TYPE_MAXLEN];
    double value;
    char unit[SENSOR_READING_UNIT_MAXLEN];
    cJSON *metadata; // nullable; NULL serializes as {}
} sensor_reading_t;

typedef struct sensor_driver {
    const char *name;
    esp_err_t (*init)(void);
    esp_err_t (*read)(sensor_reading_t *out, size_t max_out, size_t *out_count);
} sensor_driver_t;
```

`sensor_registry.c` holds a compile-time array of these (currently BME280
and LD2410) and two generic functions, `sensor_registry_init_all()` and
`sensor_registry_collect()`, that `app_main.c` and `telemetry_client.c`
call without ever referencing `bme280.c`/`ld2410.c` directly. One driver
failing `init()` or `read()` is logged and skipped — it doesn't take the
whole node offline.

### Adding a new sensor

1. Write `main/my_sensor.h` / `main/my_sensor.c` implementing `init()` and
   `read()` matching `sensor_driver_t`'s function pointer signatures.
2. Add `"my_sensor.c"` to the `SRCS` list in `main/CMakeLists.txt`.
3. `#include "my_sensor.h"` in `sensor_registry.c` and add one line to the
   `s_drivers[]` array:
   ```c
   { .name = "my_sensor", .init = my_sensor_init, .read = my_sensor_read },
   ```

Nothing in `app_main.c`, `telemetry_client.c`, or the main reporting loop's
control flow needs to change — that's the whole point of this structure per
the spec.

## Backend contract this firmware targets

From the spec (binding, see the spec file for the authoritative version):

```json
POST /api/device/telemetry
Authorization: Bearer <raw pairing token>
Content-Type: application/json

{
  "readings": [
    {"sensor_type": "presence", "value": 1, "unit": "bool", "metadata": {}},
    {"sensor_type": "temperature", "value": 21.4, "unit": "c", "metadata": {}},
    {"sensor_type": "humidity", "value": 47.2, "unit": "pct", "metadata": {}},
    {"sensor_type": "pressure", "value": 1013.2, "unit": "hpa", "metadata": {}}
  ]
}
```

This firmware's BME280 driver emits `temperature`/`humidity`/`pressure`
exactly as shown; its LD2410 driver emits `presence` as a `0`/`1` boolean
in `value` with the richer distance/energy data folded into `metadata`
(`moving_distance_cm`, `moving_energy`, `stationary_distance_cm`,
`stationary_energy`, `detection_distance_cm`, `target_state`).

## Out of scope here

Per the spec: thermal camera support, a full BLE/Wi-Fi-AP provisioning UX,
on-device spectrum analysis/FFT, the RTL-SDR module (Workstream J — see
`components/README.md`), and anything on the backend/frontend side
(Workstreams G, H, K).