Skip to content
Get started

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.

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.

  • id (Optional, ID): Manually specify the component ID.
  • detection_algorithm (Optional, string): lightweight or high_accuracy. Defaults to lightweight. 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, or ht_vht. Defaults to auto, which picks a profile for the chip, band, and traffic source. lltf uses the legacy long training field. ht_vht uses 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, or external. Defaults to ping. See Traffic Sources.
  • traffic_generator_target_ip (Optional, IPv4 address): Where ping, dns, and dns_tcp send 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 for dns_tcp. Cannot be used with wifi_raw or external.
  • traffic_generator_target_mac (Optional, MAC Address): Where wifi_raw sends 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 in external mode 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 whenever wifi_raw runs, also after the traffic source select switches to it. Not available on ESP32-C6 or with csi_capture_profile: ht_vht.
  • csi_traffic_multicast_group (Optional, IPv4 address): Multicast group the device joins in external mode, to receive UDP datagrams and ICMP echo requests in addition to those sent to its own address. Defaults to 239.255.0.1. An empty string joins no group. Requires traffic_generator_mode: external.
  • csi_sample_spacing (Optional, string): half_slot or distinct. Defaults to half_slot. Sets how close together two CSI packets can arrive and both reach the detector. half_slot needs at least half a time slot between them. distinct only needs different timestamps. Applies to every traffic source. See Reading the Diagnostics for when to use distinct.
  • 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 default evaluation_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.

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.

ModeTraffic
pingThe device sends ICMP echo requests.
dnsThe device sends DNS queries over UDP.
dns_tcpThe device sends DNS queries over TCP.
wifi_rawThe device sends Wi-Fi Null Data frames to the access point, or to traffic_generator_target_mac.
externalThe 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 BB as 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.

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 1000ms to 2000ms. Defaults to 1000ms. 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_pps seconds. With external traffic, send at this rate.
  • evaluation_interval (Optional, Time): Time between two detector evaluations. Range 10ms to 10s. Defaults to 250ms. Motion hits count evaluations, so this also changes how long motion_on_hits and motion_off_hits take.
  • 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.
  • 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 true when the block is present.
    • cutoff (Optional, frequency): Cutoff frequency. Range 5Hz to 20Hz. Defaults to 11Hz. The filter assumes 100 samples per second. With a different csi_target_pps, or with many missing slots, the real cutoff is different.

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 B

Device 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 same bssid on both, so they do not roam to different channels.
  • Device A needs the auto or lltf capture profile. Device B needs auto or ht_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.

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.

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_mode other than none is 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.

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.

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.

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.

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.

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_raw frames included. 0 in external mode. Unit pps, 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). Unit pps, 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.

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_rate is much higher than csi_accepted_rate, check the traffic source and the capture profile.
  • If csi_excess_rate stays close to csi_missing_slot_rate, packets are arriving in back-to-back pairs, which happens on a busy channel. Set csi_sample_spacing to distinct, so the earlier packet of each pair can fill the empty slot. If csi_occupancy does not rise within a minute, go back to half_slot.

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.

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, and external. See Traffic Sources. wifi_raw is not offered on ESP32-C6 or with csi_capture_profile: ht_vht. traffic_generator_target_ip applies only to ping, dns, and dns_tcp. Changing the mode restarts Lightweight calibration. High Accuracy keeps its threshold.
  • detection_algorithm (Optional): Options lightweight and high_accuracy. The threshold changes to the default of the new algorithm. Switching to lightweight starts a calibration, so keep the room still until it finishes.
  • csi_sample_spacing (Optional): Options half_slot and distinct. See csi_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.

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_mode defaults to RESTORE_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.

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.