ESPectre C++ SDK

1. Add the SDK

Activate ESP-IDF, open your project folder, and add the latest stable release:

idf.py add-dependency "francescopace/espectre"

For a prerelease or a specific version, replace VERSION_FROM_REGISTRY with a version from the registry. For a branch snapshot, use its version and the staging URL https://components-staging.espressif.com:

idf.py add-dependency --registry-url "https://components.espressif.com" "francescopace/espectre=VERSION_FROM_REGISTRY"

The dependency is saved in main/idf_component.yml, and the exact version in dependencies.lock. Snapshot versions end in .main or .develop; copy them from the registry, not from the website's download labels.

Set CONFIG_ESP_WIFI_CSI_ENABLED=y in your project configuration. Sensing is always included; turn on optional services in menuconfig. See the recommended project configuration for the other options and the public headers for your integration.

2. Drive the runtime

Call setup() after creating the Wi-Fi station and the default event loop, ideally before connecting to Wi-Fi; an existing connection is also picked up. Then call loop() continuously, and queue the events your product needs:

#include "espectre_sdk.h"

class ProductFrontend : public espectre::IRuntimeListener {
 public:
  bool setup() {
    runtime_.set_config(
        espectre::make_runtime_sensing_config_from_kconfig());
    return runtime_.setup(this);
  }

  void loop() { runtime_.loop(); }

  void on_motion_state_changed(
      const espectre::RuntimeSnapshot& snapshot) override {
    if (!snapshot.ready_to_publish) return;
    enqueue_motion(snapshot.motion_state == espectre::MotionState::MOTION);
  }

 private:
  void enqueue_motion(bool motion);
  espectre::RuntimeFrontendController runtime_;
};

Logging is optional. To see SDK messages, register an espectre::LogSink before runtime_.setup(); otherwise the SDK logs nothing.

3. Follow the runtime rules

• Publish only when snapshot.ready_to_publish is true.
• Run setup(), loop(), and shutdown() on one task.
• Keep listener callbacks short and non-blocking; do network and storage work elsewhere.
• Check capabilities() before offering optional controls.