ESPectre Wi-Fi Motion Detection
The espectre component detects motion from Wi-Fi channel state information (CSI), using the
ESPectre SDK. The ESP32 does all the processing, so no other motion sensor is needed.
The component needs WiFi connected to an access point. It runs on ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, and ESP32-C6, with the ESP-IDF framework 5.5.3 or newer or the Arduino framework 3.3.7 or newer. ESP32-C5 and ESP32-C6 need ESP-IDF, because ESPHome does not support Arduino on these chips.
Configuration
Section titled “Configuration”espectre:
binary_sensor: - platform: espectre motion: name: "Motion"By default the device sends traffic to the Wi-Fi gateway and measures the CSI it gets back. Only one espectre
component can use the radio.
Lightweight detection calibrates its threshold at startup. Keep the device in place and the room still until calibration finishes. High Accuracy detection does not need a quiet room, but it still waits for usable CSI and for the detector to warm up.
Results depend on where the device is, on the access point, and on the radio environment. The component detects movement. It cannot tell whether a person who stays still is in the room.
Configuration Variables
Section titled “Configuration Variables”- id (Optional, ID): Manually specify the component ID.
- detection_algorithm (Optional, string):
lightweightorhigh_accuracy. Defaults tolightweight. Lightweight detection calibrates its threshold to the room and uses less CPU and memory. High Accuracy detection runs an on-device neural network with trained weights. - csi_capture_profile (Optional, string):
auto,lltf, orht_vht. Defaults toauto, which picks a profile for the chip, band, and traffic source.lltfuses the legacy long training field.ht_vhtuses HT20 or VHT20, depending on the Wi-Fi connection. - traffic_generator_mode (Optional, string): The source of the traffic that carries CSI:
ping,dns,dns_tcp,wifi_raw, orexternal. Defaults toping. See Traffic Sources. - traffic_generator_target_ip (Optional, IPv4 address): Where
ping,dns, anddns_tcpsend their traffic. Defaults to the Wi-Fi gateway. Use a unicast address that answers the selected mode. DNS modes need a DNS server on port 53, with TCP support fordns_tcp. Cannot be used withwifi_raworexternal. - traffic_generator_target_mac (Optional, MAC Address): Where
wifi_rawsends its Null Data frames. Defaults to the access point the device is connected to, also after roaming. Set it to the Wi-Fi station MAC address of another ESPectre device inexternalmode to measure the link between the two devices. See Two-Device Sensing. Must be a unicast address. With the device’s own address, raw traffic does not start. The option applies wheneverwifi_rawruns, also after the traffic source select switches to it. Not available on ESP32-C6 or withcsi_capture_profile: ht_vht. - csi_traffic_multicast_group (Optional, IPv4 address): Multicast group the device joins in
externalmode, to receive UDP datagrams and ICMP echo requests in addition to those sent to its own address. Defaults to239.255.0.1. An empty string joins no group. Requirestraffic_generator_mode: external. - csi_sample_spacing (Optional, string):
half_slotordistinct. Defaults tohalf_slot. Sets how close together two CSI packets can arrive and both reach the detector.half_slotneeds at least half a time slot between them.distinctonly needs different timestamps. Applies to every traffic source. See Reading the Diagnostics for when to usedistinct. - motion_on_hits (Optional, int): How many detector evaluations in a row must be above the threshold to
report motion. Range 1 to 20. Defaults to
4, about 1 second at the defaultevaluation_interval. Raise it if short bursts trigger motion. Lower it if motion is reported too late. - motion_off_hits (Optional, int): How many detector evaluations in a row must be below the threshold to
clear motion. Range 1 to 20. Defaults to
3.
You can also change motion_on_hits and motion_off_hits at runtime with the numbers.
Traffic Sources
Section titled “Traffic Sources”The device measures CSI on the packets it receives, so it needs a steady flow of traffic. The detector expects
csi_target_pps packets per second, 100 by default.
| Mode | Traffic |
|---|---|
ping | The device sends ICMP echo requests. |
dns | The device sends DNS queries over UDP. |
dns_tcp | The device sends DNS queries over TCP. |
wifi_raw | The device sends Wi-Fi Null Data frames to the access point, or to traffic_generator_target_mac. |
external | The device sends nothing. Another host sends the traffic. |
wifi_raw is not available on ESP32-C6 and needs the auto or lltf capture profile.
In external mode, another host can send:
- ICMP echo requests to the device or to its multicast group. The device answers each request, so it keeps transmitting while it measures.
- UDP datagrams to port 5555, with the four bytes
F0 9F 91 BBas payload. - Null Data frames from another ESPectre device. See Two-Device Sensing.
Send at csi_target_pps packets per second, to the device’s address or to its multicast group. Broadcast traffic
does not give reliable CSI.
Prefer ICMP echo requests. UDP datagrams get no reply, so the device stays almost silent. After a few seconds the access point can change how it transmits to the device, and an empty room can show motion.
Advanced Configuration Variables
Section titled “Advanced Configuration Variables”These options change detector timing and signal filtering. The detectors were validated with the defaults, so tune the threshold and motion hits first. If you change any of these, test detection again.
espectre: evaluation_interval: 500ms hampel_filter: window: 9 lowpass_filter: cutoff: 8Hz- window_size (Optional, Time): Length of the detector window.
Range
1000msto2000ms. Defaults to1000ms. A longer window changes the detector features and the response time. - csi_target_pps (Optional, int): Packets per second that the detector expects and the traffic generator
sends. Range 1 to 500. Defaults to
100. The detector splits its window into time slots of 1/csi_target_ppsseconds. Withexternaltraffic, send at this rate. - evaluation_interval (Optional, Time): Time between two detector
evaluations. Range
10msto10s. Defaults to250ms. Motion hits count evaluations, so this also changes how longmotion_on_hitsandmotion_off_hitstake. - hampel_filter (Optional): Replaces outliers with the median of the filter window. Both detection
algorithms use it. Enabled by default.
- enabled (Optional, boolean): Whether the filter runs. Defaults to
true. - window (Optional, int): Window length, in samples. Range 3 to 11. Defaults to
7. - threshold (Optional, float): A sample is replaced when its distance from the median is more than this
value times 1.4826 times the median absolute deviation (MAD). Range 1.0 to 10.0. Defaults to
5.0.
- enabled (Optional, boolean): Whether the filter runs. Defaults to
- lowpass_filter (Optional): Smooths the signal before the detector evaluates it. This can reduce false
positives, but slows the response. Disabled by default.
- enabled (Optional, boolean): Whether the filter runs. Defaults to
truewhen the block is present. - cutoff (Optional, frequency): Cutoff frequency. Range
5Hzto20Hz. Defaults to11Hz. The filter assumes 100 samples per second. With a differentcsi_target_pps, or with many missing slots, the real cutoff is different.
- enabled (Optional, boolean): Whether the filter runs. Defaults to
Two-Device Sensing
Section titled “Two-Device Sensing”Two ESPectre devices can measure the link between them instead of the link to the access point. This helps when the access point is far from the area you want to monitor: place the two devices on opposite sides of the area.
Device A sends Null Data frames to device B and measures B’s acknowledgements. Device B measures A’s frames. Each device runs its own detector and reports its own motion.
Device A:
espectre: traffic_generator_mode: wifi_raw traffic_generator_target_mac: "AA:BB:CC:DD:EE:FF" # Wi-Fi station MAC address of device BDevice B:
espectre: traffic_generator_mode: external- Both devices must be on the same Wi-Fi channel and use the same
csi_target_pps. On a mesh network, set the samebssidon both, so they do not roam to different channels. - Device A needs the
autoorlltfcapture profile. Device B needsautoorht_vht. - An ESP32-C6 can only be device B. In an ESP32-C5 and ESP32-C6 pair, the ESP32-C5 is device A.
- While you test the link, stop any other external traffic sent to device B.
- Both devices need ESPHome 2026.11.0 or newer. Older versions ignore the frames.
Access Point and Band
Section titled “Access Point and Band”If you have several access points, set the bssid of the one with the strongest signal in the WiFi
networks entry. A signal between -40 and -70 dBm works well.
The device then connects only to that access point, and does not connect at all when it is unavailable.
On ESP32-C5, the SDK follows the WiFi component’s band_mode. Start with 2.4 GHz, because detection on 5 GHz has
not been characterized. The SDK uses a 20 MHz channel width.
Wi-Fi Settings
Section titled “Wi-Fi Settings”The component changes these Wi-Fi settings for the whole firmware:
- Wi-Fi power saving is off, also while the device is disconnected, so the device uses slightly more power during
reconnects. A
power_save_modeother thannoneis not applied, and the build logs a warning. - Frame aggregation (AMPDU) is off in both directions. The radio reports one CSI sample per received transmission, so without aggregation more frames carry CSI. Wi-Fi throughput can drop, so OTA updates, the web server, and audio streaming may be slower.
- On the original ESP32, the SDK fixes the transmit rate at 6.5 Mbps when the access point supports 802.11n.
- Post-connect roaming scans are paused while the component runs, because each scan takes the radio off-channel and empties the CSI window. The device still reconnects if it loses the access point.
- In every traffic mode, the device answers ICMP echo requests sent to any multicast group it has joined, including groups joined by other components such as mDNS.
Runtime Restarts
Section titled “Runtime Restarts”If the SDK runtime fails to start or stops with a fault, the component sets its error status, logs the fault, and restarts the runtime after 30 seconds. The restarted runtime keeps the values set from the numbers, selects, and switch. Lightweight detection calibrates again. High Accuracy detection keeps a threshold set from the threshold number, and otherwise starts from the model’s default threshold.
Binary Sensors
Section titled “Binary Sensors”Both keys are optional, but configure at least one per platform entry.
binary_sensor: - platform: espectre motion: name: "Motion" calibrating: name: "Calibrating"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- motion (Optional): On when the detector detects motion. Its device class is
motion. - calibrating (Optional): On while calibration runs. This is a diagnostic entity.
Both support all options from Binary Sensor.
The motion sensor is unknown while the runtime warms up or calibrates, and when it stops receiving usable CSI. Unknown does not mean that there is no motion.
Sensors
Section titled “Sensors”Both keys are optional, but configure at least one per platform entry.
sensor: - platform: espectre movement: name: "Movement Score"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- movement (Optional): The detector’s movement score. All options from Sensor. See Movement Score.
- diagnostics (Optional): Diagnostic sensors. See Diagnostic Sensors.
Movement Score
Section titled “Movement Score”The movement score goes from 0 to 1. Each algorithm has its own scale, so scores from different algorithms
cannot be compared. The score publishes after every detector evaluation, every evaluation_interval (250 ms by
default). The motion binary sensor publishes only when it changes. If you only need motion, leave the movement
score out. Otherwise, use sensor filters such as throttle or delta to
send fewer values.
The movement sensor has no update_interval, because its values come from detector evaluations. It is unknown
while sensing is unavailable.
Diagnostic Sensors
Section titled “Diagnostic Sensors”The diagnostic sensors show what the traffic source and CSI capture are doing. They are diagnostic entities, and all of them publish together from the same one-second SDK sample.
By default they publish only on request, so they stay unknown until something asks for an update. Add a button
that runs the component.update action with the id of the
diagnostics, as in the example below, or set update_interval.
sensor: - platform: espectre diagnostics: id: espectre_diagnostics generator_rate: name: "Generator Rate" traffic_tx_rate: name: "Traffic TX Rate" traffic_rx_rate: name: "Traffic RX Rate" csi_callback_rate: name: "CSI Callback Rate" csi_accepted_rate: name: "CSI Accepted Rate" csi_missing_slot_rate: name: "CSI Missing Slot Rate" csi_excess_rate: name: "CSI Excess Rate" csi_occupancy: name: "CSI Temporal Occupancy"
button: - platform: template name: "Refresh Diagnostics" entity_category: diagnostic on_press: - component.update: espectre_diagnostics- id (Optional, ID): ID of the diagnostic sensors group, used by
component.update. - update_interval (Optional, Time): How often the diagnostic sensors
publish. Defaults to
never. The SDK computes a new sample every second, so shorter intervals repeat values. - generator_rate (Optional): Packets per second sent by the internal traffic generator,
wifi_rawframes included. 0 inexternalmode. Unitpps, one decimal place. - traffic_tx_rate (Optional): Packets per second that the Wi-Fi driver accepted for transmission from the
station, including traffic not sent by the generator. Unit
pps, one decimal place. - traffic_rx_rate (Optional): Packets per second that the Wi-Fi driver delivered to the station.
Unit
pps, one decimal place. - csi_callback_rate (Optional): CSI callbacks per second from the Wi-Fi driver, before any validation.
Unit
pps, one decimal place. - csi_accepted_rate (Optional): CSI packets per second that passed capture validation.
Unit
pps, one decimal place. - csi_missing_slot_rate (Optional): Detector time slots per second that got no CSI.
Unit
slot/s, one decimal place. - csi_excess_rate (Optional): CSI packets per second dropped because their time slot already had one, or
because they arrived too close to the previous packet (see
csi_sample_spacing). Unitpps, one decimal place. - csi_occupancy (Optional): Percentage of time slots in the detector window that have CSI. Detection needs
at least 70%. Unit
%, no decimal places.
Configure at least one sensor under diagnostics. Each sensor supports all options from
Sensor. The sensors are unknown while the SDK runtime is not running.
The component does not report signal strength. For RSSI, use the WiFi Signal Sensor.
Reading the Diagnostics
Section titled “Reading the Diagnostics”Only packets that pass validation reach the detector, at most one per time slot, and only if they keep the
spacing set by csi_sample_spacing from the previous packet.
- If
csi_callback_rateis much higher thancsi_accepted_rate, check the traffic source and the capture profile. - If
csi_excess_ratestays close tocsi_missing_slot_rate, packets are arriving in back-to-back pairs, which happens on a busy channel. Setcsi_sample_spacingtodistinct, so the earlier packet of each pair can fill the empty slot. Ifcsi_occupancydoes not rise within a minute, go back tohalf_slot.
Numbers
Section titled “Numbers”The numbers change detection settings at runtime. They are configuration entities. All keys are optional, but configure at least one per platform entry.
number: - platform: espectre threshold: name: "Threshold" motion_on_hits: name: "Motion On Hits" motion_off_hits: name: "Motion Off Hits"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- threshold (Optional): The movement score above which an evaluation counts toward motion. Range 0 to 1, step 0.01. As with the movement score, each algorithm has its own scale.
- motion_on_hits (Optional): Runtime value of
motion_on_hits. Range 1 to 20. - motion_off_hits (Optional): Runtime value of
motion_off_hits. Range 1 to 20.
Each number supports all options from Number.
The threshold number shows the active threshold. It follows the changes made by Lightweight calibration, by the Recalibrate button, and by a change of detection algorithm. A threshold set from the number is not saved. After a reboot, Lightweight detection calibrates again and High Accuracy detection starts from the model’s default threshold.
The motion hits are saved and restored after a reboot. If nothing is saved, each number starts from its
configuration value. Changing motion_on_hits or motion_off_hits in the configuration discards the saved
value.
If the SDK rejects a value, the component logs a warning and the number goes back to the active value.
Selects
Section titled “Selects”The selects change the traffic source, the detection algorithm, and the CSI sample spacing at runtime. They are configuration entities. All keys are optional, but configure at least one per platform entry.
select: - platform: espectre traffic_generator_mode: name: "CSI Traffic Source" detection_algorithm: name: "Detection Profile" csi_sample_spacing: name: "CSI Packet Spacing"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- traffic_generator_mode (Optional): Options
ping,dns,dns_tcp,wifi_raw, andexternal. See Traffic Sources.wifi_rawis not offered on ESP32-C6 or withcsi_capture_profile: ht_vht.traffic_generator_target_ipapplies only toping,dns, anddns_tcp. Changing the mode restarts Lightweight calibration. High Accuracy keeps its threshold. - detection_algorithm (Optional): Options
lightweightandhigh_accuracy. The threshold changes to the default of the new algorithm. Switching tolightweightstarts a calibration, so keep the room still until it finishes. - csi_sample_spacing (Optional): Options
half_slotanddistinct. Seecsi_sample_spacing.
Each select supports all options from Select.
The selected options are saved and restored after a reboot. If nothing is saved, each select starts from its
configuration value. Changing traffic_generator_mode, detection_algorithm, or csi_sample_spacing in the
configuration discards the saved option. If the SDK rejects an option, the component logs a warning and the
select stays on the active option.
Switch
Section titled “Switch”The switch pauses and resumes sensing. Wi-Fi stays connected. It is a configuration entity.
switch: - platform: espectre sensing: name: "Sensing"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- sensing (Required): All options from Switch, except
inverted.restore_modedefaults toRESTORE_DEFAULT_ON.
Turning the switch off stops the traffic generator and CSI capture, and cancels a running calibration. The motion and movement sensors become unknown. Turning it on resumes sensing: Lightweight detection calibrates again, and High Accuracy detection keeps its threshold.
The switch state is restored before the runtime starts, so a device that boots with the switch off does not start sensing.
Button
Section titled “Button”The button starts a recalibration. It is a configuration entity.
button: - platform: espectre name: "Recalibrate"- espectre_id (Optional, ID): ID of the ESPectre component. Automatically selected when omitted.
- All options from Button.
After pressing Recalibrate, keep the room still until calibration finishes. Lightweight detection collects about 10 seconds of quiet input and computes a new threshold. Brief movement extends calibration, up to 30 seconds. High Accuracy detection does not calibrate to the room: it restores the model’s default threshold. A press while calibration is running is ignored. If calibration fails, the SDK keeps the previous threshold and logs a warning. Until the first calibration succeeds, a failure also sets the component’s warning status.
Recalibrate after you rearrange the room. If you move the device, restart it instead.