francescopace/espectre 3.0.0-rc3

v3.0.0-rc3 - SDK on the ESP Component Registry and ESP-IDF 6 support

on GitHub

Highlights

• Published the SDK as the francescopace/espectre component on the ESP Component Registry.
• Added ESP-IDF 6.x support to the SDK, alongside 5.5.3 and later.
• Added the Home Assistant Traffic Generator add-on (#168).
• Improved device discovery and sensing recovery after Wi-Fi roaming.

Added

• ESP-IDF 6.x support in the SDK. Official firmware stays on 5.5.5; see SDK.md.
• Registry packages with a Wi-Fi sensing example, validated by consumer builds before and after publication.
• The SDK API reference on the website, covering every public type.
• The Traffic Generator add-on for 64-bit Home Assistant OS, with an Ingress panel for traffic control and live diagnostics, including ESPHome devices (#168).
• Generator Rate and Traffic RX Rate sensors in Home Assistant (#182).
• Warnings when a runtime loop iteration or a traffic generator send stalls for 100 ms or more, naming the slow steps.
• An NM-CYD-C5 ESPHome example with a touch display, contributed by @RockBase-iot (#166).
• BaseDetector calibration hooks on_startup_calibration_abandoned(), startup_calibration_conclusive(), and calibration_motion_ceiling(). Defaults keep the previous behavior.
• RuntimeConfig::persist_runtime_overrides: set it to false when your firmware owns configuration, so live control changes are neither restored nor saved.

Changed

• Breaking: Official ESPHome images use MAC-suffixed hostnames such as espectre-a1b2c3.local. After the first update, use the new hostname for OTA and update dashboard entity IDs (#179).
• Breaking: The SDK exports only its root include directory; use layer-prefixed includes such as #include "runtime/runtime_config.h".
• Breaking: IEspectreRuntime is internal. RuntimeConfig and WifiBandPolicy moved to runtime/runtime_config.h, which replaces runtime/runtime_interface.h.
• Breaking: espectre_sdk.h no longer includes the ESPectre Protocol; include espectre_protocol_sdk.h. Diagnostic JSON helpers moved to runtime/runtime_diagnostics_protocol.h, and diagnostic profiles have named constants.
• Breaking: RuntimeDiagnosticsSnapshot groups its fields as link, traffic, csi, platform, and performance, for example csi.accepted_total. Wire names are unchanged.
• Breaking: Renamed SDK symbols so each name says what it controls, such as TrafficGeneratorMode, RuntimeConfig::threshold, and set_threshold(). Wire names, ESPHome YAML keys, and saved settings are unchanged.
• Breaking: traffic_generator_mode: external replaces csi_traffic_mode in the protocol, ESPHome YAML, Kconfig, and the SDK. The Home Assistant "CSI Traffic Ownership" select is gone; "CSI Traffic Source" gains external. Saved settings migrate; update clients and firmware together.
• Breaking: kNativeLoopPriority left the SDK; the Native frontend defines its own.
• Breaking: Removed unused SDK API, including parse_json_array_objects(), two RawCsiStopReason values, and RawCsiPacketView::wifi_rx_start_ts_ns. publish_frontend_mqtt_message() drops its config argument.
• Breaking: wifi_band_policy defaults to AUTO on every target. A hand-built RuntimeConfig{} on ESP32-C5 now selects the band automatically.
• Traffic diagnostics report internal generation (generator_pps) and station traffic (traffic_tx_pps, traffic_rx_pps) separately, so the generator rate reads zero when no generator runs (#182).
• The SDK requires MQTT and mDNS only when enabled, and no longer requires the HTTP server.
• ESPHome devices no longer run periodic roaming scans, which took the radio off-channel for up to 12 seconds every 5 minutes.
• update_sensing returns unsupported for a threshold the device cannot change.
• CLI discovery waits six seconds by default and asks devices to reply directly.
• One cd.yml workflow publishes releases to the production registry and main and develop snapshots to the staging registry (#178).

Fixed

• Fixed runtime loop stalls from taking the lwIP core lock and from stopping the traffic generator. Firmware that drives TrafficGeneratorManager or CsiTrafficService directly must keep calling loop() after stop().
• Fixed sensing not resuming after roaming with a retained IPv4 address, and startup waiting on a Wi-Fi scan.
• Fixed CSI staying silent on S3 and C5 after switching from wifi_raw to another traffic source.
• Fixed Lightweight calibration: movement no longer pushes the threshold close to 1.0, and quiet rooms no longer drive it to about 0.01. It now stays between 0.095 and 0.987.
• Fixed MOTION and availability flickering during brief CSI coverage dips.
• Fixed update_sensing applying some fields before rejecting another. Custom frontends should pass the new optional validator to FrontendCommandEngine::execute().
• Fixed a failed startup calibration dropping the active detector, an unchanged detector losing its threshold, and shutdown() leaving availability ready.
• Fixed espectre collect ignoring its own startup calibration.
• Fixed mDNS replies to common query types and browser discovery running out of HTTP connections. See DISCOVERY.md.
• Fixed Native rebooting while checking for OTA updates.
• Fixed matter qr and monitor --reset leaving the device in the firmware loader, and Matter reporting its version as unknown.
• Fixed standalone Wi-Fi leaking resources, truncating full-length credentials, and giving up on reconnection.
• Fixed source-list builds of the Direct sources missing the mDNS link wrapper; use ESPECTRE_RUNTIME_ESP_IDF_DIRECT_LINK_OPTIONS.
• Fixed the WiFi Channel sensor showing decimals (#181).

Removed

• Breaking: Removed the traffic_packets_total diagnostic; use get_generator_packets_total() or get_packets_received() (#182).
• Breaking: Removed initialize_primary_console(); integrations set up their own console.
• Breaking: Removed wifi_tx_rate.h from the services facade; call apply_station_tx_rate() from network_traffic.h.
• Breaking: Removed ESPECTRE_CORE_INCLUDE_DIRS and ESPECTRE_RUNTIME_INCLUDE_DIRS.
• Breaking: Removed CSI V7 binary record support. Existing NPZ datasets still load.
• Breaking: Removed RuntimeProfile and its helpers; set traffic_generator_mode instead.
• Breaking: Removed RuntimeSubcarrierSource and the subcarrier snapshot fields; read RuntimeFrontendController::subcarriers().
• Breaking: Removed csi_traffic_mode helpers, make_runtime_sensing_config(), and visit_runtime_diagnostics(). The validate_runtime_*() helpers are now internal.
• Breaking: Removed the unused raw stream command path, including the last FrontendCommandEngine::execute() argument. Raw CSI collection opens with GET /csi.
• Breaking: Removed handle_device_config_command() and its types; use parse_espectre_config_command() and parse_espectre_mqtt_config_command().
• Breaking: Removed ESPECTRE_DIRECT_MAX_REQUEST_ID_SIZE and ESPECTRE_DIRECT_MAX_METHOD_SIZE; use ESPECTRE_COMMAND_ID_MAX_LENGTH.
• Breaking: Removed BaseDetector::packet_index_; read total_packets_.

SDK source migration

Updating C++ code from rc2 is a compile-and-replace pass. Behavior changes only where noted. The external traffic setting also changes on the wire, in Kconfig, and in ESPHome YAML; saved settings migrate on their own.

Two behavior changes need a decision:

• A hand-built RuntimeConfig{} on ESP32-C5 now uses AUTO band selection. Set wifi_band_policy = WifiBandPolicy::BAND_2G to keep 2.4 GHz.
• If your firmware owns configuration, set persist_runtime_overrides = false so saved controls no longer override it.