Use the ESPectre component built into ESPHome

ESPectre is part of ESPHome. Add motion sensing to any ESPHome YAML, with no external component.

Built-in or external component

The built-in component and the external component, the one in the ESPectre repository, run the same SDK. They differ in what comes around it. This guide covers ESPHome 2026.11.

Start with the built-in component when you already maintain an ESPHome configuration and want motion as one more entity. Use the external component or an official image for the browser tools.

The external component is deprecated and will be removed in ESPectre 3.3, when official images move to the built-in one. The ESPHome guide shows how to move a configuration and how to add the browser tools with espectre_direct.

Your first configuration

Add the hub and a motion sensor to a configuration that already sets up Wi-Fi:

espectre:

binary_sensor:
  - platform: espectre
    motion:
      name: Motion

The sensor calibrates after each connection, while the room is quiet. Keep the room still for the first half minute after the device joins Wi-Fi.

Options

All options go under espectre: and are optional. The defaults suit most rooms.

Entities

The component creates only the entities you list. This configuration adds the ones most people want:

binary_sensor:
  - platform: espectre
    motion:
      name: Motion
    calibrating:
      name: Calibrating

sensor:
  - platform: espectre
    movement:
      name: Movement
    diagnostics:
      update_interval: 10s
      csi_accepted_rate:
        name: CSI Accepted Rate
      csi_occupancy:
        name: CSI Temporal Occupancy

number:
  - platform: espectre
    threshold:
      name: Threshold

select:
  - platform: espectre
    detection_algorithm:
      name: Detection Algorithm
    traffic_generator_mode:
      name: Traffic Mode

switch:
  - platform: espectre
    sensing:
      name: Sensing

button:
  - platform: espectre
    name: Recalibrate

• Controls apply at runtime, without a new build. Numbers also cover motion_on_hits and motion_off_hits, and the selects also cover csi_sample_spacing. The Sensing switch pauses sensing and is restored after a reboot.
• Diagnostics also include generator_rate, traffic_tx_rate, traffic_rx_rate, csi_callback_rate, csi_missing_slot_rate, and csi_excess_rate. They publish nothing until you set update_interval or call component.update on them.
• The traffic generator app fills its panel from these entities when they use the names it expects. See the Home Assistant guide.

What the component changes in ESPHome

CSI needs a steady stream of received packets, so the component adjusts the radio:

• Wi-Fi power save is always off, also while the device is disconnected.
• ESPHome's periodic roaming scans stop, because each one interrupts sensing. Losing the access point still triggers a normal reconnect.
• Wi-Fi aggregation is off in both directions, because CSI needs one report per frame. This can lower Wi-Fi throughput for the whole firmware.
• It needs ESP-IDF 5.5.3 or later, or Arduino 3.3.7 or later, on ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, or ESP32-C6.

Current limits

• The built-in component has no Direct API of its own. Add the espectre_direct add-on for Monitor, Find devices, CSI collection, and the ./espectre device commands; the ESPHome guide shows how.
• With ESPHome 2026.10, the add-on changes only the traffic source and starts a recalibration. Threshold, motion hits, detection profile, packet spacing, and the sensing switch need ESPHome 2026.11. The device name, the access point pin, the Wi-Fi settings, and MQTT stay in your YAML.

For every option and platform, see the ESPHome documentation.