espectre_sdk.h File Reference

The public ESPectre integration surface, in one include. More...

#include "runtime/espectre_sdk_version.h"
#include "runtime/firmware_version.h"
#include "runtime/runtime_capabilities.h"
#include "runtime/runtime_config_utils.h"
#include "runtime/runtime_diagnostics.h"
#include "runtime/runtime_events.h"
#include "runtime/runtime_interface.h"
#include "runtime/runtime_sensing_schema.h"
#include "runtime/runtime_snapshot.h"
#include "runtime/espectre_protocol.h"
#include "runtime/direct_websocket_service.h"
#include "runtime/mqtt_transport.h"
#include "runtime/ota_service.h"
#include "runtime/esp_idf/runtime_frontend_controller.h"
#include "runtime/esp_idf/runtime_sensing_kconfig.h"

Go to the source code of this file.

Detailed Description

The public ESPectre integration surface, in one include.

ESPectre turns ordinary Wi-Fi traffic into a motion signal: it captures Channel State Information from the radio, extracts features, and reports a debounced motion state. This header is the supported entry point for firmware that embeds that engine instead of flashing one of the published frontends.

#include "espectre_sdk.h"
 
class ProductFrontend : public espectre::IRuntimeListener {
 public:
  bool setup() {
    espectre::RuntimeConfig config;  // documented defaults, ready to use
    runtime_.set_config(config);
    return runtime_.setup(this);
  }
 
  void loop() { runtime_.loop(); }
 
  void on_motion_state_changed(const espectre::RuntimeSnapshot &snapshot) override {
    if (!snapshot.ready_to_publish) return;
    publish(snapshot.motion_state == espectre::MotionState::MOTION);
  }
 
 private:
  espectre::RuntimeFrontendController runtime_;
};

Two integration paths

• Full runtime (recommended). Your firmware owns boot, provisioning, networking, OTA, and the product surface. ESPectre owns Wi-Fi CSI capture, calibration, detection, and eventing behind espectre::RuntimeFrontendController and espectre::IRuntimeListener. Requires ESP-IDF >= 5.5.
• Core-only. Your firmware already captures CSI. Include espectre_core_sdk.h and drive espectre::LightweightDetector or espectre::HighAccuracyDetector directly. runtime/esp_idf/csi_pipeline.cpp is the reference for normalization, evaluation cadence, and hit filtering.

Threading contract

The control surface is single-owner. Internal bounded mailboxes protect callback-to-loop handoff, but they do not make control calls thread-safe.

• Run setup(), loop(), and shutdown() on one task. These are the calls that build and tear down runtime state, and they are not safe to race.
• Every IRuntimeListener callback is delivered on the caller's task: from loop() for sensing events, or inline on the task that invoked a control method. Work raised in the Wi-Fi CSI callback is deferred through an internal mailbox first, so no listener callback runs in interrupt or Wi-Fi driver context.
• Keep callbacks bounded and non-blocking. Slow work delays loop() and can fill the bounded CSI mailbox, dropping incoming frames. Queue network I/O, NVS writes, and other blocking work for another task.
• Call set_*_runtime() only from the owner task. The shipped MQTT, Direct WebSocket, and OTA adapters queue stack events and deliver their application callbacks from the frontend loop, so Native follows this rule without external locks.
• Do not drive the controller from inside on_runtime_fault() beyond shutdown().

Versioning

ESPECTRE_SDK_VERSION_STRING and ESPECTRE_SDK_VERSION_AT_LEAST() identify the SDK sources you compiled against. See runtime/espectre_sdk_version.h for how that differs from your firmware version.

Stability tiers

Everything reachable from this header is the stable runtime surface and follows the SDK version contract. The opt-in espectre_core_sdk.h facade is the lower-level detector extension. Other headers are internal and can change in any release. docs/EMBEDDING.md defines the exact guarantees.

Licensing

ESPectre is dual-licensed: GPLv3, or a separately offered commercial license for proprietary firmware. See LICENSING.md.

Definition in file espectre_sdk.h.