espectre::RuntimeFrontendController Class Reference

The recommended entry point for firmware embedding ESPectre. More...

#include <runtime_frontend_controller.h>

Inheritance diagram for espectre::RuntimeFrontendController:

Public Member Functions
	~RuntimeFrontendController () override
	Shut the runtime down on scope exit.
void	set_config (const RuntimeConfig &config)
	Stage the configuration used by the next setup().
RuntimeConfig &	config ()
	Mutable access to the staged configuration.
const RuntimeConfig &	config () const
	Read-only view of the staged configuration.
const RuntimeSnapshot &	snapshot () const
	Latest known snapshot, without querying the backend.
RuntimeDiagnosticsSnapshot	diagnostics () const
	Read backend counters without touching the cached sensing snapshot.
const RuntimeCapabilities &	capabilities () const
	What the active backend supports.
bool	is_setup_complete () const
	True between a successful setup() and the next shutdown().
bool	setup (IRuntimeListener *listener)
	Create the backend, apply the configuration, and start sensing.
void	loop ()
	Advance runtime work and deliver pending listener callbacks.
void	shutdown ()
	Stop sensing and release the backend.
void	set_services_armed (bool armed)
	Gate runtime-owned services without tearing the runtime down.
void	set_live_telemetry_enabled (bool enabled)
	Enable or suppress IRuntimeListener::on_live_telemetry().
bool	services_armed () const
	Current armed state, including before setup.
void	quiesce_for_ota ()
	Quiet the runtime ahead of an OTA update.
bool	set_threshold_runtime (float threshold)
	Set the motion threshold, validating it against the active detector.
bool	set_motion_hits_runtime (uint8_t motion_on_hits, uint8_t motion_off_hits)
	Set the hit filter.
bool	set_csi_traffic_mode_runtime (CsiTrafficMode mode)
	Change the live CSI traffic ownership mode.
bool	set_traffic_generator_mode_runtime (RuntimeTrafficMode mode)
	Change the live internal traffic generator packet type.
bool	set_detection_algorithm_runtime (DetectionAlgorithm algorithm)
	Switch detector while running.
bool	trigger_recalibration ()
	Restart startup calibration.
bool	is_calibrating () const
	True while the backend is calibrating.

Detailed Description

The recommended entry point for firmware embedding ESPectre.

It owns the runtime backend, picks the right one from RuntimeConfig::runtime_profile, caches the latest snapshot and the discovered capabilities, and validates control calls before they reach the backend. The shipped Native and Matter frontends are thin wrappers over it.

class ProductFrontend : public espectre::IRuntimeListener {
 public:
  bool setup() {
    espectre::RuntimeConfig config;
    config.detection_algorithm = espectre::DetectionAlgorithm::LIGHTWEIGHT;
    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) publish(snapshot.motion_state);
  }
 
 private:
  espectre::RuntimeFrontendController runtime_;
};

Lifecycle

set_config() -> setup(listener) -> loop() repeatedly -> shutdown(). The controller is reusable after shutdown(): configuration survives, and set_config() becomes effective again.

Threading

Carries no internal locking. Run setup(), loop(), and shutdown() on one task. See espectre_sdk.h for the full contract, including where listener callbacks land and how to handle controls driven from a transport callback.

Control calls before setup

The setters work before setup() and simply update the pending configuration, so a frontend can accept provisioning commands during boot without special-casing the ordering.

Definition at line 66 of file runtime_frontend_controller.h.

Constructor & Destructor Documentation

~RuntimeFrontendController()

espectre::RuntimeFrontendController::~RuntimeFrontendController ( )

override

Shut the runtime down on scope exit.

Explicit shutdown() remains recommended.

Member Function Documentation

set_config()

void espectre::RuntimeFrontendController::set_config

(

const RuntimeConfig &

config

)

Stage the configuration used by the next setup().

Ignored once setup has started, so reconfiguring a running runtime means shutdown() first, or the set_*_runtime() methods for the fields that support live changes.

config() [1/2]

RuntimeConfig & espectre::RuntimeFrontendController::config ( )

inline

Mutable access to the staged configuration.

Provided so a frontend can adjust individual fields before setup() without rebuilding the whole struct. Writing to it after setup changes only this cached copy, not the running runtime.

Definition at line 85 of file runtime_frontend_controller.h.

config() [2/2]

const RuntimeConfig & espectre::RuntimeFrontendController::config ( ) const

inline

Read-only view of the staged configuration.

Definition at line 87 of file runtime_frontend_controller.h.

snapshot()

const RuntimeSnapshot & espectre::RuntimeFrontendController::snapshot ( ) const

inline

Latest known snapshot, without querying the backend.

Refreshed automatically at setup(), by control calls, and before every listener callback is forwarded to your frontend. Use the cached snapshot for on-demand reads such as answering a status query; use the listener callbacks to react to change.

Definition at line 96 of file runtime_frontend_controller.h.

diagnostics()

RuntimeDiagnosticsSnapshot espectre::RuntimeFrontendController::diagnostics

(

)

const

Read backend counters without touching the cached sensing snapshot.

Unlike snapshot(), this queries the backend on every call. Invoke it from an existing periodic sensing callback, not from the hot loop. Returns a zeroed snapshot before setup().

capabilities()

const RuntimeCapabilities & espectre::RuntimeFrontendController::capabilities ( ) const

inline

What the active backend supports.

Meaningful only after setup().

Gate your product surface on it rather than hardcoding: the controller already refuses capability-gated calls, and this is how you avoid exposing a control the runtime will reject.

Definition at line 112 of file runtime_frontend_controller.h.

is_setup_complete()

bool espectre::RuntimeFrontendController::is_setup_complete ( ) const

inline

True between a successful setup() and the next shutdown().

Definition at line 114 of file runtime_frontend_controller.h.

setup()

bool espectre::RuntimeFrontendController::setup

(

IRuntimeListener *

listener

)

Create the backend, apply the configuration, and start sensing.

Calling it twice is a no-op that returns true.

Parameters

listener

Event sink, or nullptr for none. Not owned; it must outlive the controller.

Returns

false when the backend cannot start, for example a RuntimeProfile::STREAM config in a build without the stream runtime. On failure the backend is dropped and the controller stays un-setup, so it is safe to fix the config and retry.

loop()

void espectre::RuntimeFrontendController::loop

(

)

Advance runtime work and deliver pending listener callbacks.

Call it continuously from your loop task. Safe, and a no-op, before setup.

shutdown()

void espectre::RuntimeFrontendController::shutdown

(

)

Stop sensing and release the backend.

Safe before setup and to repeat.

set_services_armed()

void espectre::RuntimeFrontendController::set_services_armed

(

bool

armed

)

Gate runtime-owned services without tearing the runtime down.

Sticky: the value is remembered and reapplied to the backend created by a later setup(). Matter uses it to stay silent until commissioning. Frontends use it to pause CSI without dropping Wi-Fi.

set_live_telemetry_enabled()

void espectre::RuntimeFrontendController::set_live_telemetry_enabled

(

bool

enabled

)

Enable or suppress IRuntimeListener::on_live_telemetry().

Also sticky.

services_armed()

bool espectre::RuntimeFrontendController::services_armed ( ) const

inline

Current armed state, including before setup.

Definition at line 149 of file runtime_frontend_controller.h.

quiesce_for_ota()

void espectre::RuntimeFrontendController::quiesce_for_ota

(

)

Quiet the runtime ahead of an OTA update.

Drops live telemetry and disarms services so the download is not competing with CSI capture and traffic generation. Reverse it with set_services_armed(true) if the update is abandoned.

set_threshold_runtime()

bool espectre::RuntimeFrontendController::set_threshold_runtime

(

float

threshold

)

Set the motion threshold, validating it against the active detector.

Parameters

threshold

Value on the 0..1 metric scale.

Returns

false when out of range, or when the backend refuses it. Before setup the value is staged and returns true.

set_motion_hits_runtime()

bool espectre::RuntimeFrontendController::set_motion_hits_runtime	(	uint8_t	motion_on_hits,
		uint8_t	motion_off_hits )

Set the hit filter.

Parameters

motion_on_hits	Consecutive above-threshold evaluations to report motion (1..20). Higher trades latency for fewer false positives.
motion_off_hits	Consecutive below-threshold evaluations to clear it (1..20).

Returns

false when either value is out of range, or when the runtime is up and does not advertise RuntimeCapabilities::supports_runtime_motion_hits_updates.

set_csi_traffic_mode_runtime()

bool espectre::RuntimeFrontendController::set_csi_traffic_mode_runtime

(

CsiTrafficMode

mode

)

Change the live CSI traffic ownership mode.

Returns

false when the mode is invalid, or when the runtime is up and does not advertise RuntimeCapabilities::supports_traffic_control.

set_traffic_generator_mode_runtime()

bool espectre::RuntimeFrontendController::set_traffic_generator_mode_runtime

(

RuntimeTrafficMode

mode

)

Change the live internal traffic generator packet type.

Returns

false when the mode is invalid, or when the runtime is up and does not advertise RuntimeCapabilities::supports_traffic_control.

set_detection_algorithm_runtime()

bool espectre::RuntimeFrontendController::set_detection_algorithm_runtime

(

DetectionAlgorithm

algorithm

)

Switch detector while running.

The threshold follows the detector: the controller adopts the new detector's threshold rather than carrying the old value across scales.

Returns

false for an unknown algorithm, or when the runtime is up and does not advertise RuntimeCapabilities::supports_runtime_detector_selection.

trigger_recalibration()

bool espectre::RuntimeFrontendController::trigger_recalibration

(

)

Restart startup calibration.

Returns

false before setup, or when the backend does not advertise RuntimeCapabilities::supports_manual_recalibration. Success only means calibration started; the outcome arrives through IRuntimeListener::on_calibration_finished().

is_calibrating()

bool espectre::RuntimeFrontendController::is_calibrating

(

)

const

True while the backend is calibrating.

False before setup.

---

The documentation for this class was generated from the following file:

• src/cpp/runtime/esp_idf/runtime_frontend_controller.h