ESPectre
SDK / Architecture

Architecture in three layers

Dependencies point in one direction: frontend → runtime → core. Put product integration at the top and sensing algorithms at the bottom.

Frontend src/cpp/frontend/
Owns boot, networking policy, UI, protocols, and ecosystem mapping. ESPHome, Native, Matter, and Streamer are maintained references; your product can replace this layer.
Runtime src/cpp/runtime/
Owns capture lifecycle, calibration, snapshots, events, and control contracts. ESP-IDF implementations live under runtime/esp_idf/.
Core src/cpp/core/
Owns CSI format, conditioning, features, and the Lightweight and High Accuracy detectors. It is portable C++17 and requires no ESP-IDF runtime.

Runtime data flow

Wi-Fi trafficproduct
CSI captureruntime/esp_idf
Featurescore
Detectioncore
Product eventfrontend

Where should new code go?

If the code…Put it in…
Changes CSI processing or detector behaviorcore/, with matching Python behavior
Defines a reusable lifecycle, event, snapshot, or transport contractruntime/
Calls ESP-IDF, FreeRTOS, Wi-Fi, NVS, or lwIPruntime/esp_idf/
Maps sensing into Direct WebSocket, MQTT, Matter, ESPHome, or your product UIfrontend/

Building a runtime for another platform

Keep the shared contracts and replace the platform backend. A new runtime should:

  1. Implement IEspectreRuntime

    Own capture setup, the work loop, shutdown, controls, snapshots, diagnostics, and capability reporting.

  2. Feed the shared detector core

    Convert platform CSI into ESPectre's normalized format, reuse the core features and detectors, and preserve parity with the runtime's evaluation, readiness, and hit-filter behavior.

  3. Deliver the shared events

    Defer driver callbacks, and notify IRuntimeListener from the runtime's owning task.

  4. Add platform wiring

    Place the implementation under a platform directory such as runtime/arduino/ or runtime/linux/, and provide its own controller or factory. The shipped RuntimeFrontendController currently constructs ESP-IDF backends directly.

Arduino on ESP32Feasible as a new adapter over Arduino-ESP32 and its underlying ESP-IDF CSI facilities, provided the build offers C++17. No Arduino runtime is shipped today.
Raspberry Pi / LinuxRequires a Wi-Fi chipset, firmware, and driver that expose usable CSI. Standard Linux Wi-Fi connectivity alone is not enough, so this is hardware-dependent rather than a generic Raspberry Pi port.
The complete ownership rules and design rationale live in ARCHITECTURE.md. Durable decisions are recorded in docs/adr/.
Next: API orientation →
Find the public SDK types and generated reference.