C++ API reference

loading version…

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

Device protocol. The HTTP API and MQTT API document client integrations that do not embed the C++ SDK.

Overview

Full-runtime types to know

RuntimeFrontendController Owns setup, the work loop, shutdown, cached state, and validated runtime controls. RuntimeConfig Defines detector, traffic, cadence, filtering, and other startup settings. IRuntimeListener Delivers motion, threshold, status, calibration, telemetry, and fault events. RuntimeSnapshot Carries motion state, movement score, threshold, link state, and readiness.

Lifecycle at a glance

set_config()stage settings

setup(listener)start sensing

loop()deliver events

shutdown()release runtime

On ESP-IDF, build the initial configuration with make_runtime_sensing_config_from_kconfig() unless the product deliberately supplies every sensing setting itself. Call the lifecycle and control methods from one owner task.

Optional logging sink

LogSink connects shared SDK messages to a product-owned backend. Register it before runtime setup and leave it unchanged until shutdown. Without a sink, shared logging is silent and filtered message arguments are not evaluated. The sink callbacks must be thread-safe, bounded, non-blocking, and non-reentrant because runtime services can log from more than one task or capture path.

Native, Matter, and Micro-ESPectre use ESP-IDF Log v2 and pass each callback's va_list to esp_log_va. ESP-IDF adds the standard level, timestamp, tag, and line ending, so these adapters do not need their own formatting buffer. ESPHome sends messages to its own logger. Each adapter keeps its logging dependency in the frontend. Micro-ESPectre's core-only and focused traffic components can share the core-owned sink without depending on the ESP-IDF log component.

Errors and optional controls

Control methods return false when a value is outside its published range, the active backend does not advertise the capability, the backend refuses the change, or setup cannot allocate its bounded working storage. A rejected call leaves the runtime unchanged. Allocation failures are reported synchronously to the listener; runtime-owned asynchronous failures arrive through on_runtime_fault().

RuntimeCapabilities defaults every flag to false. Read capabilities() after setup and expose only the controls that the active runtime reports.

Raw CSI callbacks have a stricter threading contract. Listener events arrive from the owner task, but a callback passed to start_raw_collection() runs synchronously in Wi-Fi capture context. Keep it bounded, non-blocking, and allocation-free, and copy accepted packets into a preallocated queue for later work.

Choose the detector as a product budget

Lightweight keeps less feature state and performs less active work. High Accuracy adds feature tracking and neural inference; in the current maintained selection + holdout diagnostic, it produces higher recall and F1 and a lower false-positive rate. That evidence compares the two profiles under the same replay contract, but it is not a sealed blind generalization result. Power has not yet been measured. See the profile measurements and validation limits.

Lightweight calibrates from up to ten seconds of clean, ready slot coverage and can later lower its threshold after a quiet stretch. High Accuracy skips threshold calibration but still waits for CSI readiness and feature-window warmup.

Public SDK headers

espectre_sdk.h The recommended facade for ESP-IDF products. Runtime contracts, configuration, events, diagnostics, and boundary interfaces form the stable full-runtime API. espectre_services_sdk.h Includes the sensing facade and adds the command engine, Direct HTTP, discovery, provisioning, and bootstrap helpers. Requires ESP-IDF dependency headers. espectre_mqtt_sdk.h Provides EspIdfMqttTransport for firmware using the ESP-IDF MQTT stack. Include it separately from the services facade. espectre_core_sdk.h The advanced facade for firmware that already captures and normalizes CSI. It exposes detector classes without the ESP-IDF runtime.

Including a facade does not enable its source groups. Select the optional capability groups that your firmware uses and provide their component dependencies. Your firmware owns the service objects and their lifecycle.

The facades define separate support boundaries. Everything reachable from espectre_sdk.h belongs to the stable runtime surface. Public methods and configuration types exposed by the services and MQTT facades follow the same source-compatibility contract. The core facade covers detector classes and their documented public methods. Private members, feature trackers, generated weights, and headers included only as implementation dependencies are not independent extension points.

Compatibility

Final numeric releases follow Semantic Versioning for C++ source compatibility. Patch releases preserve documented behavior, minor releases may add compatible declarations, and breaking changes require a major release. Preview and develop bundles may change before the corresponding final release.

The SDK ships as source and does not promise a stable binary ABI. Rebuild the SDK and your integration together, and initialize public structs with their defaults before assigning named fields. The complete contract, including detector-output limits and deprecation rules, lives in the SDK guide.

Replacing the runtime

A platform port implements IEspectreRuntime. The interface covers lifecycle, state, controls, diagnostics, capabilities, and listener delivery; the existing RuntimeFrontendController remains ESP-IDF-specific and does not inject an arbitrary backend.