RF Object Detection (WiFi CSI) on the Cardputer ADV — Volume 1: Overview, Provenance, and Hardware Constraints

1.1 About this sub-project

This is a research and firmware deep dive, not a reference deep dive. The Cardputer ADV reference (12 volumes) covers what the stock device is — the ESP32-S3 hardware, the EXT bus, the Cap LoRa-1262, the firmware ecosystem, flashing and recovery. This sub-project covers one specific sensing application: using the Cardputer ADV’s ESP32-S3 Wi-Fi radio to capture Channel State Information (CSI) — the fine-grained radio channel measurements that encode how objects in the room are perturbing the signal — and turning that into a real-time RF object detection / motion sensing instrument.

This work started as part of a broader sensing research project (separate, private) and is published here as the generic WiFi-CSI-on-Cardputer-ADV hacking work — everything in these volumes is grounded in publicly available firmware and well-documented CSI sensing technique.

1.2 What RF object detection via WiFi CSI on the Cardputer is

The Cardputer ADV’s ESP32-S3FN8 supports a rarely-used Wi-Fi radio feature: Channel State Information reporting, where the radio exposes the per-subcarrier amplitude and phase measurements it collects during packet reception. When a person or object moves through the room, those measurements change — reflections, scattering, and shadowing all leave a signature in the CSI stream. A single Cardputer ADV, joined to a Wi-Fi AP in Station mode with CSI and promiscuous capture enabled, can compute a running motion scalar from those measurements and render it live on the external 2.8″ ILI9341 display. No camera, no radar, no cloud — just the ESP32-S3 radio and a few kilobytes of circular buffers.

1.3 Provenance — credit where it’s due

This sub-project builds directly on two upstreams:

• The upstream firmware is Cardputer-CSI-Human-Detector by skizzophrenic (Talking Sasquach) — a single-device CSI motion detector purpose-built for the Cardputer ADV + external 2.8″ ILI9341 screen. It is MIT-licensed. A read-only snapshot is cached in this sub-project at code/firmware/upstream/ (commit 28c9502, fetched 2026-06-24; .git stripped — tracked as source). The upstream repository lives at https://github.com/skizzophrenic/Cardputer-CSI-Human-Detector.

• The sensing concept builds on the ruvnet/RuView WiFi-sensing project, which popularised ESP32 CSI sensing for presence and motion on commodity hardware.

This sub-project is an engineering reference and development workspace around those upstreams, documenting what the firmware does, where it can go, and the constraints that shape every design decision on this specific platform.

1.4 How the single-device CSI heuristic works

The upstream csiCallback() function (lines 67–133 of upstream/src/main.cpp) is the heart of the motion detector. Here is how it works:

1. Join one AP as STA. The firmware joins a single access point (credentials stored in NVS via Preferences) and locks to that AP’s channel. Promiscuous mode + CSI reporting are enabled simultaneously: every CSI-bearing frame the radio receives — from any MAC address on that channel — triggers the callback.

2. Extract amplitude and phase per frame. The callback receives an wifi_csi_info_t struct from the ESP-IDF. It reads the raw CSI data buffer, computes a mean subcarrier amplitude and a mean sin(phase) value for that frame, and pushes both into a 50-sample circular ring buffer.

3. Compute variance over the window. Once the window fills, the callback computes the variance of the amplitude buffer and the variance of the sin(phase) buffer — variance is the motion signal; a static room means stable CSI, a moving object introduces spread.

4. Adaptive normalization. An EMA (exponential moving average) floor and a running maximum are used to normalize both variance signals to the [0, 1] range. This adaptive normalization lets the detector self-calibrate to the room’s baseline without a manual calibration step.

5. Blend into a motion scalar. The two normalized variances are blended 60% amplitude / 40% phase into a single 0..1 motion scalar — the output that drives the display and the presence/motion decision.

Key architectural fact: the callback does not filter by source MAC address. Every CSI-bearing frame on the joined channel — from the connected AP, neighboring APs beaconing on the same channel, or other STAs — folds into the same ring buffers. This all-sources-blended behavior is the motivation for per-MAC CSI separation as the next development step (see Volume 2).

1.5 The three hardware constraints

Before building on this platform, settle these. Each can make a CSI build fail or quietly interfere with something else.

1.5.1 Constraint 1 — 512 KB SRAM, no PSRAM: RAM is the ceiling

The ESP32-S3FN8 on the Cardputer ADV has 512 KB SRAM and no PSRAM — approximately 360–400 KB of usable heap after the Wi-Fi stack, bootloader overhead, and task stacks. A full 320×240 16-bit framebuffer for the external 2.8″ ILI9341 display is ~154 KB by itself. A full framebuffer is therefore not available alongside CSI ring buffers and the Wi-Fi stack simultaneously. The upstream firmware’s answer — and the standing discipline for any firmware on this platform — is to render the external screen with two sprites and pushRotateZoom: small canvases drawn locally and pushed scaled to the panel, never a full back-buffer. The upstream firmware dropped an earlier 32 KB composite buffer to relieve heap pressure. Exceeding the heap ceiling crashes the device; the firmware degrades gracefully to a centered 1:1 clone rather than crashing.

1.5.2 Constraint 2 — Shared SPI bus: displays and SD contend

The Cardputer ADV’s internal SPI bus carries three devices: the built-in 1.14″ ST7789V2 display, the microSD card (CS = GPIO12), and the external ILI9341 panel on the EXT header (CS = GPIO5). All three share the same MOSI/SCK/MISO lines. SD card writes stall display refresh; long display operations delay SD logging. The bus is managed by distinct chip-select lines and bus_shared = true at a 27 MHz write clock. The design rule for any CSI firmware on this platform: keep the radar or any additional sensor off SPI — route it to the EXT UART or the Grove I²C port — and batch SD logging (accumulate in a RAM buffer, flush periodically) rather than writing per-frame.

1.5.3 Constraint 3 — Single Wi-Fi/BLE radio: coexistence

The ESP32-S3’s Wi-Fi 4 radio and BLE 5.0 share the same 2.4 GHz front-end. CSI capture requires the radio in Station mode on one channel; BLE scanning on the same radio competes directly. The consequence: concurrent Wi-Fi CSI + active BLE halves the effective CSI frame rate and introduces noise bursts. For CSI sensing work, Wi-Fi is primary — if BLE is needed for another function, time-slice (sense window → pause CSI → BLE scan → resume) rather than running both concurrently.

1.6 What’s coming in this sub-project (forward map)

This overview is Volume 1. The rest of the sub-project covers the upstream firmware in depth and the development path forward:

• Vol 2 — Upstream firmware review, per-MAC CSI separation, and multi-AP/multi-channel feasibility. What the upstream Cardputer-CSI-Human-Detector is and isn’t, the code-review verdicts (what to keep/change/fix), per-MAC CSI separation as the immediate next step (pure software, no new hardware), and the multi-AP/multi-channel radio tomography direction with its constraints and iteration ladder.
• Vol 3 — Cardputer ADV hardware, EXT-bus display wiring, and IDF firmware architecture. The hardware subsystems that matter for CSI builds, the ILI9341 EXT-bus wiring reference, the PlatformIO build and flash workflow, and the IDF CSI callback + sprite-draw firmware architecture in detail.

1.7 Resources

• Cached upstream firmware: code/firmware/upstream/ (MIT, commit 28c9502) — see its README.md.
• Upstream: https://github.com/skizzophrenic/Cardputer-CSI-Human-Detector
• WiFi CSI sensing concept: https://github.com/ruvnet/RuView
• Cardputer ADV reference deep dive: overview + decision tree, pinout + EXT bus, flashing + recovery.