# ADR-083: Per-Cluster Pi Compute Hop

| Field          | Value                                                                                |
|----------------|--------------------------------------------------------------------------------------|
| **Status**     | Proposed — pending field evidence on three-tier proposal scope                       |
| **Date**       | 2026-04-26                                                                           |
| **Authors**    | ruv                                                                                  |
| **Supersedes** | —                                                                                    |
| **Refines**    | ADR-028 (capability audit), ADR-081 (5-layer kernel), ADR-066 (swarm bridge)         |
| **Companion**  | `docs/research/architecture/three-tier-rust-node.md`, `docs/research/architecture/decision-tree.md`, `docs/research/sota/2026-Q2-rf-sensing-and-edge-rust.md` |

## Context

ADR-028 established the per-node BOM at ~$9 (ESP32-S3 8MB) — ~$15 with a
mmWave sensor — and ADR-081 framed the firmware as a 5-layer adaptive
kernel running entirely on a single ESP32-S3 die. Both decisions are
correct for the **per-node** dimension; deployments that fit the
"sensor talks UDP to a server somewhere" shape work fine on this stack.

The three-tier-node research exploration
(`docs/research/architecture/three-tier-rust-node.md`) raised a separate
question: **what changes when a deployment scales past one or two rooms,
and where should the heavy compute live?** The exploration's answer
("dual ESP32-S3 + Pi Zero 2W per node") is one shape, but the
companion decision-tree (`decision-tree.md` §1, §3 L3, §5) identifies a
materially cheaper path: keep today's single-S3 sensor node unchanged
and add **one Pi per cluster of 3–6 sensor nodes**. The 2026-Q2 SOTA
survey (`sota/2026-Q2-rf-sensing-and-edge-rust.md`) confirms that the
load this path needs to carry — model inference, QUIC backhaul, and a
real secure-boot story — fits comfortably on a Pi-class SoC, while the
load it doesn't need to carry — CSI capture, ISR-precise wake control —
is exactly what the ESP32-S3 already does well.

The three things this ADR is about, all of which the current single-S3
deployment shape pushes onto the cloud or onto every individual node:

1. **Per-deployment ML inference.** WiFlow / DT-Pose / GraphPose-Fi
   class models (4–10M params, 0.5–1.5 GFLOPs) want a Cortex-A53-class
   target. The ESP32-S3 cannot host these; the cloud can but only at
   the cost of round-trip latency. A per-cluster Pi inference hop is
   the natural home.
2. **QUIC backhaul.** `quinn` + `rustls` is mature on Linux but does
   not run on ESP32-class hardware in any production-grade form
   (SOTA §5). A Pi terminating QUIC for a cluster gives every sensor
   node QUIC's loss/handoff/multiplex properties without porting QUIC
   to the MCU.
3. **Secure-boot anchor for OTA.** ESP-IDF Secure Boot V2 covers each
   sensor node, but cluster-wide policy (which model is current, which
   sensor MCU image is canary, what is the rollout ring) needs a
   higher-trust local store. A Pi running buildroot + dm-verity +
   signed FIT is a defensible anchor without the BOM hit of CM4 / Pi 5
   (the latter is its own decision; see ADR-085 sketch below and
   decision-tree.md L6).

The cluster-Pi shape does **not** require any change to ADR-028 or
ADR-081. The sensor node continues to be a single-MCU ESP32-S3 running
the 5-layer kernel. Everything new lives at the cluster boundary.

## Decision

Adopt **a per-cluster Pi hop** as the canonical RuView mid-scale
deployment shape. A "cluster" is **3–6 ESP32-S3 sensor nodes within
WiFi mesh range of one Pi**.

Specifically:

1. **Sensor nodes are unchanged.** They continue to run the ADR-081
   5-layer kernel on a single ESP32-S3, emit `rv_feature_state_t`
   packets (60 byte, ~5 Hz, ~300 B/s) over UDP, and connect via
   ESP-WIFI-MESH or direct WiFi to the cluster Pi.
2. **Each cluster has exactly one Pi** acting as:
   - **Sensor aggregator**: ingests UDP from all cluster sensor
     nodes, runs feature-level fusion (multistatic + viewpoint
     attention from the existing `wifi-densepose-ruvector` crate).
   - **ML inference target**: hosts the WiFi-pose model and runs
     inference at the cluster boundary, not on each sensor MCU.
   - **QUIC client to the cloud / gateway**: terminates QUIC mTLS,
     batches cluster-level events.
   - **OTA + secure-boot anchor for its sensor nodes**: holds signed
     manifests, stages canary rollouts, owns provisioning state.
3. **Cluster Pi SoC choice is deferred** to a future ADR (sketched
   below as ADR-085). The acceptable candidates are Pi Zero 2W, Pi 4,
   Pi 5, and CM4. The decision tree's L6 distinguishes these by
   secure-boot threat model; this ADR does not pre-commit.
4. **The single-node deployment shape is not deprecated.** A
   home-lab / single-room / development deployment can still run a
   single ESP32-S3 talking UDP directly to the existing
   `wifi-densepose-sensing-server`, no Pi required. The cluster Pi
   becomes the recommended shape for fleets ≥ 3 sensor nodes.

### Boundary contract

The cluster Pi exposes two interfaces:

| Interface              | Direction         | Schema                                                                |
|------------------------|-------------------|-----------------------------------------------------------------------|
| **UDP `rv_feature_state_t` ingest** | sensor → Pi | Existing 60-byte packed struct from ADR-081 (magic `0xC5110006`)     |
| **QUIC mTLS uplink**   | Pi → gateway/cloud | New: cluster-level event envelope (CBOR), batched, ~10 KB/min upper bound |

Sensor → Pi is **the same wire as today's sensor → server**. Cluster Pi
uplink is **new** and is what the existing `wifi-densepose-sensing-server`
becomes — relocated from the user's laptop / container to the cluster
node. Concretely: the sensing server already exists in
`crates/wifi-densepose-sensing-server`; it cross-compiles to ARMv7 /
AArch64 today via `cargo build --target aarch64-unknown-linux-gnu`. The
relocation is a deployment change, not a re-implementation.

### Three-tier vs cluster hop

This ADR's cluster-Pi shape is the L3-hybrid path in
`decision-tree.md` §2 — **not** the full three-tier (dual-MCU + per-node
Pi) shape. It captures most of the value (ML, QUIC, secure-boot anchor)
at minimal BOM impact. The full three-tier shape remains the long-term
exploration target, blocked behind L4 (no_std CSI maturity) and L2
(per-node ISR-jitter evidence).

## Consequences

### Positive

- **Pose-grade ML on edge becomes deployable**, not just possible. A
  Pi (any of the eligible SoCs) hosts WiFlow-class models with
  ≤ 100 ms latency per cluster, vs ≥ 1 s round-trip if pose runs in the
  cloud (SOTA §1, §3).
- **QUIC arrives without an MCU port.** `quinn` + `rustls` runs on the
  Pi as it does on a server (SOTA §5). The sensor MCU keeps UDP — the
  cheapest, highest-tested wire it already speaks.
- **Cluster-level secure boot becomes coherent.** Per-sensor Secure
  Boot V2 + flash encryption (ADR-028 baseline) is unchanged. The Pi
  buildroot + dm-verity image is the cluster trust anchor and signs
  the OTA manifests for its sensors. The cluster-level threat model is
  expressible without per-sensor BOM regression.
- **No PCB respin.** Sensor nodes are bit-for-bit identical to today's
  ADR-028 baseline. The cluster Pi is a separate device on the cluster
  WiFi (and / or Ethernet, if available).
- **Deployment cost scales sub-linearly with sensor count.** One
  $25–$60 Pi per 3–6 sensor nodes adds ~$5–$20 per sensor amortized,
  vs ~$25–$50 per sensor for the per-node-Pi shape.

### Negative

- **The cluster Pi is a new piece of infrastructure to provision,
  monitor, and update.** It is the right place for cluster-level
  responsibilities, but it is not free; it adds a Linux box to every
  multi-room deployment. Mitigated by buildroot images and the
  existing OTA tooling story (see Implementation §4).
- **Cluster Pi failure takes the cluster offline** (sensor nodes
  cannot uplink without a working aggregator on the WiFi LAN). For
  high-availability deployments, this ADR is the floor; an HA-pair
  cluster Pi would be a follow-up.
- **One more network hop on the sensing path.** Sensor → Pi → cloud
  adds ~5–20 ms over Sensor → cloud (depending on link quality).
  Pose latency budgets are 100s of ms, so this is well inside spec.

### Neutral

- ADR-028 (capability audit), ADR-081 (5-layer kernel), and ADR-066
  (swarm bridge) are unchanged. This ADR adds a new device class above
  the sensor; it does not modify the sensor itself.
- The home-lab single-node shape continues to work; this ADR adds a
  recommended path for fleets, it does not deprecate the existing one.

## Implementation

The implementation is intentionally light because most of the pieces
already exist; the ADR is largely about formalizing where they live.

1. **Cluster-Pi cross-compile target.** Add to
   `rust-port/wifi-densepose-rs/.cargo/config.toml` (or the equivalent
   per-crate target spec) an `aarch64-unknown-linux-gnu` target so
   `wifi-densepose-sensing-server` builds for Pi 4 / 5 / CM4 by
   default. Also retain `armv7-unknown-linux-gnueabihf` for Pi Zero 2W
   compatibility while the Pi-SoC decision (ADR-085 sketch) is open.
2. **Cluster-Pi service unit.** Add a systemd unit file under
   `firmware/cluster-pi/` (new directory) that runs
   `wifi-densepose-sensing-server` with the cluster's UDP/QUIC ports
   and drops privileges. Buildroot integration is a separate ADR if
   the SoC choice goes to Pi Zero 2W (where there's no RPi-OS path).
3. **QUIC uplink module.** Add `wifi-densepose-sensing-server` a
   feature-gated `quic-uplink` module using `quinn` + `rustls`. The
   feature is **off by default** in the home-lab shape and on for the
   cluster Pi.
4. **OTA + signed-manifest flow.** Out of scope for this ADR; tracked
   as I4 in `decision-tree.md` §4. The cluster Pi's role is to *hold*
   the manifest store, not to define the manifest format. Use the
   existing ADR-066 swarm bridge channel for OTA staging.
5. **Documentation update.** README's hardware-table gains a
   "Cluster compute" row. CLAUDE.md gets a one-paragraph cluster-Pi
   section under Architecture. User-guide gets a cluster-deployment
   section.
6. **Validation.** A 3-sensor cluster + 1 Pi fixture in the lab.
   Pass criteria: end-to-end CSI → cluster fusion → cloud ingest;
   measured latency under 100 ms per cluster; cluster Pi reboot
   without sensor data loss > 5 s; OTA staging round-trip across all
   sensors in the cluster.

## Validation

This ADR is **proposed**, not accepted. Acceptance requires:

1. The cluster-Pi `wifi-densepose-sensing-server` cross-compiles
   cleanly on `aarch64-unknown-linux-gnu` and `armv7-unknown-linux-gnueabihf`
   targets with the existing workspace tests passing.
2. A 3-sensor + 1-Pi field test demonstrates ≥ 4 hours stable
   end-to-end CSI → fusion → cloud round-trip with latency
   ≤ 100 ms per cluster and zero phantom-skeleton regressions
   (ADR-082 holds across the new uplink).
3. The cluster-Pi ↔ sensor secure-boot story is approved alongside
   ADR-085's SoC choice.

When the above pass, this ADR moves from **Proposed** → **Accepted**
and the README + CLAUDE.md are updated to reflect cluster-Pi as the
recommended fleet-shape.

## Related ADRs (current and proposed)

- **ADR-028** (Accepted) — ESP32 capability audit. Single-node BOM
  baseline. Unchanged by this ADR.
- **ADR-029** (Proposed) — RuvSense multistatic sensing mode. Pairs
  naturally with cluster-Pi: cluster Pi is the natural home for
  multi-sensor fusion.
- **ADR-066** — Swarm bridge to coordinator. The cluster-Pi is the
  per-cluster swarm coordinator endpoint.
- **ADR-081** (Accepted) — 5-layer adaptive CSI mesh firmware kernel.
  Unchanged by this ADR.
- **ADR-082** (Accepted) — Pose tracker confirmed-track output filter.
  Holds across UDP and QUIC uplinks identically.
- **Future ADR (sketched in `decision-tree.md` L4)** — `no_std` CSI
  capture maturity benchmark. Gates the dual-MCU shape; not required
  for the cluster-Pi shape proposed here.
- **Future ADR (sketched in `decision-tree.md` L6)** — Cluster-Pi SoC
  choice (Pi Zero 2W vs CM4 vs Pi 5). Pure secure-boot decision.

## Open questions

- **Cluster size sweet spot.** "3–6 nodes" is a planning estimate. The
  3-sensor lab fixture in §Implementation will inform whether the
  upper bound is closer to 4, 6, or 8 in practice.
- **Cluster-Pi failure semantics.** Default behavior: sensor MCUs hold
  the last 60 s of feature packets in RAM and replay on reconnect.
  HA-pair cluster Pi is a separate ADR if needed.
- **Mesh control-plane interaction.** If the deployment moves to
  Thread (decision-tree.md L5), the cluster Pi may need a Thread
  Border Router role. This ADR doesn't pre-commit; it's compatible
  with both ESP-WIFI-MESH and Thread futures.