v3.0.0 - Wi-Fi sensing SDK, standalone firmware, and browser tools

[github-actions[bot]]

ESPectre 3.0 splits the sensing engine, runtime, and frontend so Wi-Fi motion detection can run inside other firmware. It turns the three release candidates into one stable release.

Coming from 2.x? Read up to "Upgrading from 2.x". Tested a release candidate? Jump to "For release candidate testers".

Highlights

• C++ source SDK on the ESP Component Registry as francescopace/espectre, for C++17 or later and ESP-IDF 5.5.3 or later. ESP-IDF 6.x is build-validated only. See the SDK guide.
• Standalone Native firmware with Direct HTTP, MQTT, Home Assistant discovery, and HTTPS OTA.
• Matter occupancy-sensor frontend that reports motion. Images are uncertified development builds without Matter OTA. See the Matter guide.
• Browser tools for installation, provisioning, configuration, and tuning, plus one ./espectre CLI.
• Two detectors on a 0.0–1.0 probability scale: Lightweight, the default, calibrates at startup; High Accuracy is a neural model that needs no calibration.

Sensing and CSI

• Timestamp-based temporal sampling replaces packet-count windows. Missing slots stay explicit.
• Both detectors use gain-invariant features, so AGC stays on. See the algorithm reference.
• traffic_generator_mode selects ping (default), dns, dns_tcp, wifi_raw (experimental), or external.
• Build-time capture policies auto, lltf, and ht-vht. ESP32-C5 adds 2.4/5 GHz selection; 5 GHz detection is uncharacterized. See CSI acquisition.
• Retransmitted frames and stray ACKs no longer add CSI samples.
• Sensing resumes after roaming, and ESPHome skips periodic roaming scans.
• Raw CSI collection streams V8 records over HTTP, and collect validates every capture.

SDK, integrations, and tools

• Modular SDK: use the full runtime or only the detectors through espectre_core_sdk.h. MQTT, Direct, and provisioning are optional.
• Dual license: GPLv3 or commercial. The ESPHome frontend stays GPLv3-only. See licensing.
• Separate SDK, application, and protocol versions with a documented compatibility contract. See SDK versioning.
• Direct HTTP and MQTT share one JSON contract. Direct uses /espectre/v1 on port 62587, and discovery uses _espectre._tcp. See the API reference and discovery reference.
• Official images accept only signed OTA updates. See official images and personal builds.
• Home Assistant Traffic Generator add-on ([FEATURE] Traffic Generator / ESPectre App for Home Assistant  #168), with generator and station traffic reported separately ([BUG] TX rate reported when no internal traffic generator #182).
• Micro-ESPectre runs native Lightweight detection with HTTP delivery. High Accuracy stays host-side.
• Browser troubleshooting guide and an NM-CYD-C5 touch-display example by @RockBase-iot (feat: support nm-cyd-c5 device with ST7789 #166).
• Dataset validation pairs recordings up to three hours apart with matching role and RSSI class.

Upgrading from 2.x

• Detectors: mvs → lightweight, ml → high_accuracy, MVSDetector → LightweightDetector, MLDetector → HighAccuracyDetector. Scores and thresholds use 0.0–1.0.
• ESPHome YAML: segmentation_window_size → segmentation_window_size_ms, evaluation_interval → evaluation_interval_ms, traffic_generator_rate → csi_target_pps. Remove segmentation_threshold, gain_lock, selected_subcarriers, publish-interval overrides, and ble_*. Provision over Improv Serial. See the ESPHome guide.
• Hostnames and entity IDs gain a MAC suffix, such as espectre-a1b2c3.local ([FEATURE] Enable unique MAC-suffixed hostnames in the official Web Serial firmware #179). Update OTA addresses and dashboards, and reapply any BSSID pin. Example YAML lives in src/cpp/frontend/esphome/examples/.
• CLI: use ./espectre, with MicroPython commands under ./espectre micro. Browser tools, mqtt, and collect replace the old me workflows. See the CLI guide.
• Micro-ESPectre: reflash and redeploy. Device-side High Accuracy, MQTT, and UDP streaming are gone. See the Micro-ESPectre guide.
• Requirements: Python 3.14, ESPHome 2026.7.0 or later, and ESP-IDF 5.5.3 or later. PlatformIO and the old components/espectre/ layout are gone.
• Leaving unsigned personal builds needs one USB flash of signed official firmware. Migrate dataset metadata to format 1.2.

For release candidate testers

Changed since 3.0.0-rc3

• Temporal admission fills free neighbouring slots: median occupancy 92.3% → 93.9%.
• High Accuracy retrained with log1p inputs: worst paired recall 97.1% → 98.3% at the same 0.14% peak false-positive rate.
• New wifi_scan_allowed() for firmware that runs its own Wi-Fi scans.
• CsiCaptureProfile and CsiCapturePolicy are open enums, and the core-only detector interface sits outside the compatibility promise.
• Dataset pairs can span three hours instead of 30 minutes.
• New browser troubleshooting guide.

Fixed since 3.0.0-rc3

• High Accuracy starting with the Lightweight threshold instead of 0.5 ([BUG] Threshold reverts during reflash/reboot, requires re-calibrate to reset #186).
• Lightweight calibration ignoring a traffic-source change, such as ping → dns.
• ESP32-S3 staying in calibration after a Wi-Fi reconnect.
• CSI runaway on weak links: retransmissions and ACKs pushed a 100 pps source to 217 records/s.
• collect skipping its quality checks since rc1 and passing captures with long gaps.
• collect hanging on Ctrl+C, and failed sends leaving the CSI stream open.
• Arduino source builds failing to link.
• Web flasher corrupting commands after a metadata read; it now uses esptool-js 0.7.0.

Upgrading from 3.0.0 release candidates

• ESPHome: csi_traffic_mode → traffic_generator_mode, also for _select. Saved rc1/rc2 csi_traffic settings no longer migrate. Delete retired Native Home Assistant entities manually, and update firmware before using the add-on.
• C++: apply the rc3 SDK migration table, then TrafficGeneratorMode::EXTERNAL → EXTERNAL_HOST.
• ESPECTRE_SDK_VERSION_NUMBER → ESPECTRE_SDK_VERSION_AT_LEAST(). espectre_device_id_from_mac() is gone.
• API clients: resource methods replace POST /request, motion replaces telemetry, and GET /csi replaces raw-session commands. Diagnostics need explicit fields, and V7 records are gone. See the API reference.
• Re-export custom High Accuracy weights; inference requires ML_FEATURE_LOG_SCALE.
• TrafficGeneratorManager → TrafficGeneratorService in traffic_generator_service.h. Keep calling loop() on it and on CsiTrafficService after stop().
• on_live_telemetry() takes a RuntimeSnapshot, and set_config() returns false after setup.
• persist_runtime_overrides defaults to false; first-party firmware enables it. clear_persisted_overrides() erases saved controls.
• RuntimeConfig::threshold defaults to the selected detector's value. Setup faults without CONFIG_ESP_WIFI_CSI_ENABLED.

---

---

This discussion was created from the release v3.0.0 - Wi-Fi sensing SDK, standalone firmware, and browser tools.