Add ESPectre to an Arduino sketch

Detect motion from Wi-Fi CSI in an Arduino-ESP32 sketch. Your sketch keeps control of Wi-Fi and of everything else it does.

The full runtime, in a library

Arduino-ESP32 is built on ESP-IDF, so the library runs the same runtime as the ESP-IDF SDK: CSI capture, calibration, detection, and the traffic that keeps CSI flowing. The ESPectre class wraps it with begin(), loop(), and callbacks that run on your sketch's task.

Requirements

Installation

From v3.2.0, install ESPectre from the Arduino Library Manager. With Arduino CLI:

arduino-cli lib install ESPectre

To try the development version, install the develop branch of espectre-arduino, which follows every development build:

arduino-cli config set library.enable_unsafe_install true
arduino-cli lib install --git-url https://github.com/francescopace/espectre-arduino.git#develop

Your first sketch

Open File > Examples > ESPectre > MotionDetection, set your network in arduino_secrets.h, and upload it. The core of the example is short:

#include <WiFi.h>
#include <ESPectre.h>

ESPectre sensor;

void setup() {
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  WiFi.begin("your-network", "your-password");
  sensor.onMotion([](bool motion) { Serial.println(motion ? "Motion" : "Idle"); });
  sensor.begin();
}

void loop() {
  sensor.loop();
  delay(10);
}

1. Start Wi-Fi, then the sensor

   Call begin() after WiFi.begin(). The connection does not have to be up yet.

2. Call loop() every time

   Callbacks run inside begin(), loop(), and end(), so keep them short.

3. Wait for calibration

   The sensor calibrates after each connection, while the room is quiet. Until then, ready() is false and no motion is reported.

Two more examples show the result on a board with a display: FeatherReverseTFT for the Adafruit Feather ESP32-S3 Reverse TFT, and WaveshareTouchLCD147 for the Waveshare ESP32-S3-Touch-LCD-1.47. See the display demos.

Wi-Fi

• ESPectre turns Wi-Fi power save off at every connection. Do not call WiFi.setSleep(true) while sensing.
• On a mesh network, pass the BSSID and channel of the nearest access point to WiFi.begin(). A board joined to a distant node gets weak CSI.
• Arduino-ESP32 does not reconnect after some failures, such as a refused authentication. Reconnect from your sketch when WiFi.status() stays disconnected.

Current limits

• The library covers sensing only. MQTT, Direct HTTP, and provisioning are not included, so the browser tools cannot reach the board.
• On ESP32, the fixed transmit rate does not apply, because Arduino builds ESP-IDF with A-MPDU enabled.
• The example uses most of the default 1.2 MB app partition. Choose a larger partition scheme when your sketch adds other libraries.

For the full API, configuration, logging, and board notes, see the Arduino library reference.