francescopace/espectre 3.2.0

v3.2.0 - Arduino library and Direct API for the ESPHome built-in component

on GitHub

ESPectre 3.2 adds an Arduino library, and brings the website tools and the CLI to the espectre component built into ESPHome. Code written for 3.1 builds without changes.

Highlights

• A new Arduino library adds motion sensing to Arduino-ESP32 sketches. See the Arduino guide.
• The espectre_direct add-on brings the website tools and the CLI to the espectre component built into ESPHome. See the component built into ESPHome.
• The ESPHome external component is deprecated and will be removed in 3.3.

Arduino

• The ESPectre class has begin(), loop(), ready(), motion(), and the onMotion(), onReady(), and onFault() callbacks, which run on the sketch's task. runtime() returns the full SDK controller.
• The sketch keeps control of Wi-Fi. The library does sensing only, without MQTT, Direct HTTP, or provisioning.
• It works on ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, and ESP32-C6, at about 100 CSI packets per second.
• On ESP32 the fixed transmit rate does not apply, because Arduino builds ESP-IDF with A-MPDU enabled. ESP32 still reaches about 87% temporal occupancy next to the access point.
• Settings changed at runtime are not saved unless persist_runtime_overrides is set.
• The FeatherReverseTFT and WaveshareTouchLCD147 examples show the connection, calibration progress, motion state, movement score, and threshold on the Adafruit Feather ESP32-S3 Reverse TFT and the Waveshare ESP32-S3-Touch-LCD-1.47. The first was inspired by John Edgar Park's demo. See the display demos.
• Releases publish the library to espectre-arduino.

ESPHome

• espectre_direct serves the Direct API next to the built-in espectre component: device and sensing resources, live events, CSI collection, and discovery. The built-in component applies and saves every sensing change.
• With ESPHome 2026.10 it can recalibrate and set the traffic mode. Threshold, motion hits, detector, sample spacing, and the sensing switch need ESPHome 2026.11.
• The external component is deprecated and prints a build warning. Official images keep it until 3.3. See moving to the built-in component.
• The ESPHome guide and a new website guide cover the built-in component.
• Official firmware builds use ESPHome 2026.10.2.

Tools and integrations

• Monitor shows only the sensing controls that the device accepts.
• The Home Assistant traffic generator add-on (0.4.1) recognizes the occupancy sensor of the built-in ESPHome component when it is named after its csi_occupancy key. See the add-on guide.
• The website adds an Arduino guide, and the Guides page lists every guide.
• Matter firmware builds use esp-matter 1.6.1.
• CI runs the released ESPHome and Native images for ESP32-C3, ESP32-C5, ESP32-C6, and ESP32-S3 in esp-emu with recorded CSI, and checks them against the Python detector. See emulator CSI replay.

Fixes

• CSI collection no longer stops when one TCP segment is lost on a busy channel (#203).
• A product that starts Wi-Fi before the SDK, as an Arduino sketch does, no longer stays offline after the SDK applies its radio settings. The SDK rejoins the station and retries until it is back online.

SDK

The additions are source-compatible:

• espectre::ESPectre is the Arduino-style sensor for ESP-IDF projects that use Arduino as a component. See Arduino-style sensor.
• RuntimeGuestAccess and RuntimeDirectHttpBridge::setup_guest() let a second component serve Direct HTTP on a runtime it does not own. Sensing changes go to the owner through a RuntimeControlSink. See the API reference.
• RuntimeFrontendController::set_observer() adds a second event listener.
• log_sink_registered() reports whether a log sink is registered.
• In capabilities, the update_sensing operation lists the sensing fields the device accepts. Firmware before 3.2.0 does not list them.

Upgrading from 3.1.0

• No code changes are needed.
• ESPHome configurations with the external component keep working, with a deprecation warning.
• A client that rejects unknown fields must accept fields in capabilities.
• When a product starts Wi-Fi before the SDK, the SDK may now call esp_wifi_connect() itself until the station is back online.