The sensing backend behind RuntimeFrontendController. More...

#include <runtime_interface.h>

Public Member Functions
virtual	~IEspectreRuntime ()=default
virtual bool	setup ()=0
	Bring the runtime up: radio hooks, CSI capture, detector, traffic.
virtual void	shutdown ()=0
	Stop sensing and release everything setup() acquired.
virtual void	loop ()=0
	Advance runtime work and drain deferred events.
virtual void	set_services_armed (bool armed)=0
	Gate the runtime-owned services without tearing the runtime down.
virtual void	set_live_telemetry_enabled (bool enabled)=0
	Enable or suppress the high-rate on_live_telemetry() stream.
virtual bool	set_threshold_runtime (float threshold)=0
	Retune the motion threshold while running.
virtual bool	set_motion_hits_runtime (uint8_t motion_on_hits, uint8_t motion_off_hits)=0
	Retune the hit filter while running.
virtual bool	set_csi_traffic_mode_runtime (CsiTrafficMode mode)
	Switch who owns the CSI-bearing traffic while running.
virtual bool	set_traffic_generator_mode_runtime (RuntimeTrafficMode mode)
	Change the internal traffic generator packet type while running.
virtual bool	set_detection_algorithm_runtime (DetectionAlgorithm algorithm)=0
	Switch detector while running, rebuilding detector state.
virtual bool	trigger_recalibration ()=0
	Restart startup calibration against the current ambient channel.
virtual bool	is_calibrating () const =0
	True while startup calibration is running and detection is not yet valid.
virtual RuntimeSnapshot	get_snapshot () const =0
	Current sensing state.
virtual RuntimeDiagnosticsSnapshot	get_diagnostics () const
	Capture, traffic, and link counters for diagnostic frontends.
virtual RuntimeCapabilities	get_capabilities () const =0
	What this backend actually supports.
virtual void	set_listener (IRuntimeListener *listener)=0
	Install the event sink, or nullptr to detach.

Detailed Description

The sensing backend behind RuntimeFrontendController.

Implement this only to replace the shipped ESP-IDF backend. Integrations consume it indirectly: the controller owns the instance, forwards control calls, and gates them on get_capabilities().

Threading: Implementations are not required to be thread-safe and the shipped one is not. Run setup(), loop(), and shutdown() on the task that owns the runtime, and deliver listener callbacks on the caller's task rather than from an interrupt or a driver callback. See espectre_sdk.h for the complete contract, including the control-call caveat.

Definition at line 163 of file runtime_interface.h.

Constructor & Destructor Documentation

◆ ~IEspectreRuntime()

virtual espectre::IEspectreRuntime::~IEspectreRuntime ( )

virtualdefault

Member Function Documentation

◆ setup()

virtual bool espectre::IEspectreRuntime::setup ( )

pure virtual

Bring the runtime up: radio hooks, CSI capture, detector, traffic.

Returns: false if the runtime cannot sense. The caller must not call loop() afterwards; the controller drops the instance instead.

◆ shutdown()

virtual void espectre::IEspectreRuntime::shutdown ( )

pure virtual

Stop sensing and release everything setup() acquired.

Safe to repeat.

◆ loop()

virtual void espectre::IEspectreRuntime::loop ( )

pure virtual

Advance runtime work and drain deferred events.

Call it continuously from your loop task. This is where listener callbacks are delivered, so a slow callback delays the next iteration.

◆ set_services_armed()

virtual void espectre::IEspectreRuntime::set_services_armed ( bool armed )

pure virtual

Gate the runtime-owned services without tearing the runtime down.

Disarmed, the runtime stays configured but starts no CSI capture or traffic. The current Wi-Fi association is preserved so arming again can restart capture without waiting for another IP event. Matter uses this to stay quiet until commissioning completes; Native uses it to pause sensing while a frontend intentionally suspends sensing.

◆ set_live_telemetry_enabled()

virtual void espectre::IEspectreRuntime::set_live_telemetry_enabled ( bool enabled )

pure virtual

Enable or suppress the high-rate on_live_telemetry() stream.

◆ set_threshold_runtime()

virtual bool espectre::IEspectreRuntime::set_threshold_runtime ( float threshold )

pure virtual

Retune the motion threshold while running.

Returns: false when the value is out of range for the active detector, or when the runtime cannot apply it.

◆ set_motion_hits_runtime()

virtual bool espectre::IEspectreRuntime::set_motion_hits_runtime	(	uint8_t	motion_on_hits,
		uint8_t	motion_off_hits )

pure virtual

Retune the hit filter while running.

Returns: false when either count is outside 1..20, or when the runtime cannot apply the change.

◆ set_csi_traffic_mode_runtime()

virtual bool espectre::IEspectreRuntime::set_csi_traffic_mode_runtime ( CsiTrafficMode mode )

inlinevirtual

Switch who owns the CSI-bearing traffic while running.

Defaulted rather than pure so existing out-of-tree backends keep compiling. A backend that does not implement live traffic retuning should return false and let the frontend reject the command.

Definition at line 217 of file runtime_interface.h.

◆ set_traffic_generator_mode_runtime()

virtual bool espectre::IEspectreRuntime::set_traffic_generator_mode_runtime ( RuntimeTrafficMode mode )

inlinevirtual

Change the internal traffic generator packet type while running.

Backends that do not own traffic retuning keep the default false.

Definition at line 223 of file runtime_interface.h.

◆ set_detection_algorithm_runtime()

virtual bool espectre::IEspectreRuntime::set_detection_algorithm_runtime ( DetectionAlgorithm algorithm )

pure virtual

Switch detector while running, rebuilding detector state.

Returns: false when the algorithm is unknown or the switch fails.

◆ trigger_recalibration()

virtual bool espectre::IEspectreRuntime::trigger_recalibration ( )

pure virtual

Restart startup calibration against the current ambient channel.

Returns: false when calibration cannot start, for example with no Wi-Fi link yet. Progress arrives through the calibration callbacks.

◆ is_calibrating()

virtual bool espectre::IEspectreRuntime::is_calibrating ( ) const

pure virtual

True while startup calibration is running and detection is not yet valid.

◆ get_snapshot()

virtual RuntimeSnapshot espectre::IEspectreRuntime::get_snapshot ( ) const

pure virtual

Current sensing state.

Cheap enough to poll from your loop.

◆ get_diagnostics()

virtual RuntimeDiagnosticsSnapshot espectre::IEspectreRuntime::get_diagnostics ( ) const

inlinevirtual

Capture, traffic, and link counters for diagnostic frontends.

The counters are cumulative and monotonic within a session. Feed them to RuntimeDiagnosticsSampler from an existing periodic sensing callback to get rates without adding a diagnostic timer.

Defaulted rather than pure so that adding it does not break out-of-tree backends. A runtime that collects nothing keeps the zeroed snapshot, which is what a frontend reads as "no counters from this backend".

Definition at line 253 of file runtime_interface.h.

◆ get_capabilities()

virtual RuntimeCapabilities espectre::IEspectreRuntime::get_capabilities ( ) const

pure virtual

What this backend actually supports.

Stable after setup().

◆ set_listener()

virtual void espectre::IEspectreRuntime::set_listener ( IRuntimeListener * listener )

pure virtual

Install the event sink, or nullptr to detach.

Set it before setup() so calibration events are not missed. The runtime does not take ownership; the listener must outlive the runtime.

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

src/cpp/runtime/runtime_interface.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IEspectreRuntime()

Member Function Documentation

◆ setup()

◆ shutdown()

◆ loop()

◆ set_services_armed()

◆ set_live_telemetry_enabled()

◆ set_threshold_runtime()

◆ set_motion_hits_runtime()

◆ set_csi_traffic_mode_runtime()

◆ set_traffic_generator_mode_runtime()

◆ set_detection_algorithm_runtime()

◆ trigger_recalibration()

◆ is_calibrating()

◆ get_snapshot()

◆ get_diagnostics()

◆ get_capabilities()

◆ set_listener()