C++ API reference

loading version…

Search for a C++ type, method, or header. A full-runtime integration needs four types: controller, config, listener, and snapshot.

Device protocol. The HTTP API and MQTT API cover clients that talk to a device without embedding the C++ SDK.

Overview

Full-runtime types to know

RuntimeFrontendController Setup, the work loop, shutdown, current state, and runtime controls. RuntimeConfig Detector, traffic, timing, filtering, and other startup settings. IRuntimeListener Motion, threshold, status, calibration, telemetry, and error events. RuntimeSnapshot Motion state, movement score, threshold, connection state, and readiness.

Lifecycle at a glance

set_config()set settings

setup(listener)start sensing

loop()deliver events

shutdown()release runtime

On ESP-IDF, start from make_runtime_sensing_config_from_kconfig() unless you set every sensing option yourself. Call the lifecycle and control methods from one task.

Optional logging sink

LogSink sends SDK messages to your own logger. Register it before setup and keep it until shutdown. Without a sink, the SDK logs nothing and skips building the messages. The sink can be called from more than one task, so its callbacks must be thread-safe, quick, non-blocking, and must not log back into the SDK. On ESP-IDF, the simplest sink passes each message to esp_log_va, as the SDK example and the Native and Matter firmware do.

Errors and optional controls

Control methods return false when a value is out of range, the feature is not available, the change is refused, or setup cannot allocate its memory. A rejected call changes nothing. Allocation failures are reported to the listener right away; errors that happen later arrive through on_runtime_fault().

Every RuntimeCapabilities flag starts as false. Read capabilities() after setup, and offer only the controls it reports.

Raw CSI callbacks have stricter rules. Listener events arrive on your task, but the callback passed to start_raw_collection() runs inside the Wi-Fi driver. Keep it quick, non-blocking, and free of allocations: copy packets into a queue you allocated in advance, and process them later.

Choosing the detector

Lightweight uses less CPU and memory. High Accuracy adds more features and a small neural network, and detects better in our tests. Lightweight calibrates at startup on about 10 seconds of clean data, or up to about 30 seconds when that window holds a burst, and can lower its threshold later, after a quiet stretch; High Accuracy needs no calibration but waits for enough CSI. See the detector profiles for measurements and limits.

Public SDK headers

espectre_sdk.h The main header for ESP-IDF products: runtime, configuration, events, and diagnostics. This is the stable full-runtime API. espectre_protocol_sdk.h Everything in espectre_sdk.h, plus the ESPectre Protocol: messages, JSON, diagnostic fields, and the transport interfaces you implement. espectre_services_sdk.h Everything in espectre_protocol_sdk.h, plus commands, Direct HTTP, discovery, provisioning, and startup helpers. Needs the ESP-IDF headers they depend on. espectre_mqtt_sdk.h EspIdfMqttTransport, for firmware that uses the ESP-IDF MQTT client. Include it separately. espectre_core_sdk.h For firmware that already captures and prepares CSI: the detectors, without the ESP-IDF runtime.

Including a header does not compile its code. Enable the optional capability groups you use and add their dependencies. Your firmware creates the service objects and manages their lifecycle.

What is stable. Everything reachable from espectre_sdk.h, the protocol header, and the public methods and configuration types of the services and MQTT headers follow the compatibility rules below. The separate core-only detector interface in espectre_core_sdk.h may change in a minor release until the stationary presence detector ships; such changes include migration notes in the changelog. Private members, feature trackers, generated weights, and headers included only internally are not part of the API.

Compatibility

Final releases follow Semantic Versioning for the stable C++ source API. Patch releases keep documented behavior, minor releases may add compatible APIs, and breaking changes need a major release, subject to the core-only exception above. Prereleases and rolling Preview and Develop bundles can change before the final release.

The SDK ships as source, with no stable binary interface (ABI): always rebuild it together with your code. Start public structs from their defaults and then set the fields you need. CsiCaptureProfile and CsiCapturePolicy can gain values, so handle values you do not know. The full rules are in the SDK versioning contract.

Other platforms

The runtime behind RuntimeFrontendController is internal and works only with ESP-IDF. A platform port builds its own runtime on espectre_core_sdk.h and can reuse the IRuntimeListener events.