API orientation

Most full-runtime integrations need four public types. Use this page to choose the right facade, then use the generated Doxygen reference for signatures, defaults, ranges, and member-level documentation.

Open the generated API reference Built from the current public headers on every deploy.

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, periodic status, calibration, telemetry, and fault events. RuntimeSnapshot Carries motion state, movement score, threshold, link state, and readiness.

Treat the detection profile as a product-budget choice. Lightweight uses less active CPU and working memory; High Accuracy improves accuracy and generalization with additional feature state and inference work. Lightweight calibrates for up to about 10 seconds at startup and can still lower its threshold after a later quiet stretch; override on_threshold_changed() if you publish that control. High Accuracy skips threshold calibration but still waits for CSI readiness and feature-window warmup. See the detector architecture.

Lifecycle at a glance

set_config()stage settings

setup(listener)start sensing

loop()deliver events

shutdown()release runtime

Two public facades

espectre_sdk.h The recommended facade for ESP-IDF products. Its runtime contracts, controller, configuration, events, diagnostics, and boundary interfaces form the stable full-runtime API. espectre_core_sdk.h The core-only facade for firmware that already captures and normalizes CSI. It exposes the detector classes and their documented public methods without the ESP-IDF runtime.

The two facades have explicit support boundaries. Everything reachable from espectre_sdk.h belongs to the stable runtime surface. The detector classes and documented public methods exposed by espectre_core_sdk.h follow the source-compatibility contract; feature trackers, generated weights, and other 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 embedding 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.