Abstract base class for motion detection algorithms. More...

#include <base_detector.h>

Inheritance diagram for espectre::BaseDetector:

Public Member Functions
	BaseDetector (uint16_t window_size=DETECTOR_DEFAULT_WINDOW_SIZE)
	Constructor.
virtual	~BaseDetector ()
	BaseDetector (BaseDetector &&other) noexcept
BaseDetector &	operator= (BaseDetector &&other) noexcept
	BaseDetector (const BaseDetector &)=delete
BaseDetector &	operator= (const BaseDetector &)=delete
virtual void	process_packet (const int8_t csi_data, size_t csi_len, const uint8_t selected_subcarriers=nullptr, uint8_t num_subcarriers=0, int8_t rssi_dbm=INT8_MIN)
	Process a CSI packet and update internal state.
void	set_packet_timestamp_us (uint64_t timestamp_us)
	Supply the monotonic arrival timestamp consumed by time-binned features.
virtual void	reset ()
	Reset detector state.
virtual MotionState	get_state () const
	Get current motion state.
virtual bool	is_ready () const
	Check if detector is ready (buffer filled).
virtual void	advance_missing_slots (uint32_t count)
	Advance packet-indexed feature rings for absent temporal slots.
void	set_minimum_valid_samples (uint16_t count)
	Set the valid-slot occupancy floor used by is_ready().
virtual uint32_t	get_total_packets () const
	Get total packets processed.
virtual void	update_state ()=0
	Update state machine (call at publish interval).
float	get_motion_metric () const
	Get current motion metric value.
virtual bool	set_threshold (float threshold)=0
	Set detection threshold.
virtual bool	set_adaptive_threshold (float threshold)
	Apply a detector-specific startup-calibrated threshold.
virtual float	get_threshold () const =0
	Get current threshold.
virtual const char *	get_name () const =0
	Get detector name for logging.
virtual float	get_startup_threshold_factor () const
	Get the detector-specific automatic startup multiplier.
virtual bool	startup_gate_enabled () const
	Whether startup calibration uses the consistency gate (threshold.h).
virtual void	on_startup_calibration_begin ()
	Hook called immediately before startup calibration begins.
virtual void	on_startup_calibration_complete ()
	Hook called when startup calibration completes successfully.
virtual void	configure_lowpass (bool enabled, float cutoff_hz=LOWPASS_CUTOFF_DEFAULT)
	Configure low-pass filter.
virtual void	configure_hampel (bool enabled, uint8_t window_size=HAMPEL_TURBULENCE_WINDOW_DEFAULT, float threshold=HAMPEL_TURBULENCE_THRESHOLD_DEFAULT)
	Configure Hampel filter.
virtual void	clear_buffer ()
	Clear turbulence buffer (cold restart).
const float *	get_turbulence_buffer () const
	Get turbulence buffer pointer.
uint16_t	get_buffer_count () const
	Get number of valid samples in buffer.
uint16_t	get_valid_buffer_count () const
uint16_t	get_window_size () const
	Get configured window size.
float	get_last_turbulence () const
	Get last turbulence value.
bool	is_lowpass_enabled () const
	Check if low-pass filter is enabled.
bool	is_hampel_enabled () const
	Check if Hampel filter is enabled.

Protected Member Functions
void	clear_evaluation_state_ ()
	Drop the last evaluation result.
void	process_amplitudes (const float *amplitudes, uint8_t count)
uint64_t	packet_timestamp_us_or (uint64_t fallback) const
void	add_turbulence_to_buffer (float turbulence)
	Add turbulence value to buffer (with filtering).
const float *	ordered_turbulence (uint16_t &count) const
	View the turbulence ring in chronological order.

Static Protected Member Functions
static float *	alloc_zeroed_floats (uint16_t count)
	Allocate a zeroed float buffer on the heap.

Protected Attributes
float *	turbulence_buffer_
float *	ordered_turbulence_
uint16_t	buffer_index_
uint16_t	buffer_count_
uint16_t	valid_buffer_count_
uint16_t	minimum_valid_samples_
uint16_t	window_size_
MotionState	state_
float	current_metric_
uint32_t	total_packets_
uint32_t	packet_index_
uint64_t	packet_timestamp_us_
bool	has_packet_timestamp_
hampel_filter_state_t	hampel_state_
lowpass_filter_state_t	lowpass_state_

Detailed Description

Abstract base class for motion detection algorithms.

Provides shared functionality:

Turbulence buffer management (circular buffer)
Hampel and low-pass filtering
CSI processing and spatial turbulence calculation

Subclasses must implement:

update_state(): detection algorithm logic
get_motion_metric(): primary detection metric
get_threshold() / set_threshold(): threshold management
get_name(): detector name for logging

Definition at line 41 of file base_detector.h.

Constructor & Destructor Documentation

◆ BaseDetector() [1/3]

espectre::BaseDetector::BaseDetector ( uint16_t window_size = DETECTOR_DEFAULT_WINDOW_SIZE )

explicit

Constructor.

Parameters

window_size Buffer window size (10-200 packets)

◆ ~BaseDetector()

virtual espectre::BaseDetector::~BaseDetector ( )

virtual

◆ BaseDetector() [2/3]

espectre::BaseDetector::BaseDetector ( BaseDetector && other )

noexcept

◆ BaseDetector() [3/3]

espectre::BaseDetector::BaseDetector ( const BaseDetector & )

delete

Member Function Documentation

◆ operator=() [1/2]

BaseDetector & espectre::BaseDetector::operator= ( BaseDetector && other )

noexcept

◆ operator=() [2/2]

BaseDetector & espectre::BaseDetector::operator= ( const BaseDetector & )

delete

◆ process_packet()

virtual void espectre::BaseDetector::process_packet	(	const int8_t *	csi_data,
		size_t	csi_len,
		const uint8_t *	selected_subcarriers = nullptr,
		uint8_t	num_subcarriers = 0,
		int8_t	rssi_dbm = INT8_MIN )

virtual

Process a CSI packet and update internal state.

Calculates spatial turbulence from CSI data, applies filtering, and stores in circular buffer.

Parameters

csi_data	Raw CSI data (I/Q interleaved)
csi_len	Length of CSI data
selected_subcarriers	Array of subcarrier indices
num_subcarriers	Number of selected subcarriers
rssi_dbm	Link RSSI for this packet, or INT8_MIN when unknown

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ set_packet_timestamp_us()

void espectre::BaseDetector::set_packet_timestamp_us ( uint64_t timestamp_us )

inline

Supply the monotonic arrival timestamp consumed by time-binned features.

Definition at line 82 of file base_detector.h.

◆ reset()

virtual void espectre::BaseDetector::reset ( )

virtual

Reset detector state.

Resets state machine but preserves buffer ("warm" restart).

Reimplemented in espectre::LightweightDetector.

◆ get_state()

virtual MotionState espectre::BaseDetector::get_state ( ) const

inlinevirtual

Get current motion state.

Definition at line 97 of file base_detector.h.

◆ is_ready()

virtual bool espectre::BaseDetector::is_ready ( ) const

inlinevirtual

Check if detector is ready (buffer filled).

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

Definition at line 102 of file base_detector.h.

◆ advance_missing_slots()

virtual void espectre::BaseDetector::advance_missing_slots ( uint32_t count )

virtual

Advance packet-indexed feature rings for absent temporal slots.

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ set_minimum_valid_samples()

void espectre::BaseDetector::set_minimum_valid_samples ( uint16_t count )

inline

Set the valid-slot occupancy floor used by is_ready().

Definition at line 111 of file base_detector.h.

◆ get_total_packets()

virtual uint32_t espectre::BaseDetector::get_total_packets ( ) const

inlinevirtual

Get total packets processed.

Definition at line 119 of file base_detector.h.

◆ update_state()

virtual void espectre::BaseDetector::update_state ( )

pure virtual

Update state machine (call at publish interval).

Subclasses implement their detection algorithm here.

Implemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ get_motion_metric()

float espectre::BaseDetector::get_motion_metric ( ) const

inline

Get current motion metric value.

Not virtual: every detector reported the same member through an identical accessor, and the two copies drifted on when they cleared it. Subclasses assign current_metric_ at the end of their update_state() instead.

Returns: Primary metric (classic motion metric, ML probability, etc.)

Definition at line 141 of file base_detector.h.

◆ set_threshold()

virtual bool espectre::BaseDetector::set_threshold ( float threshold )

pure virtual

Set detection threshold.

Parameters

threshold New threshold value

Returns: true if value was accepted

Implemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ set_adaptive_threshold()

virtual bool espectre::BaseDetector::set_adaptive_threshold ( float threshold )

inlinevirtual

Apply a detector-specific startup-calibrated threshold.

Reimplemented in espectre::LightweightDetector.

Definition at line 152 of file base_detector.h.

◆ get_threshold()

virtual float espectre::BaseDetector::get_threshold ( ) const

pure virtual

Get current threshold.

Implemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ get_name()

virtual const char * espectre::BaseDetector::get_name ( ) const

pure virtual

Get detector name for logging.

Implemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ get_startup_threshold_factor()

virtual float espectre::BaseDetector::get_startup_threshold_factor ( ) const

inlinevirtual

Get the detector-specific automatic startup multiplier.

threshold = threshold_metric x factor. Matches the Python runtime's detector STARTUP_THRESHOLD_FACTOR convention, where threshold_metric comes from the shared startup calibrator.

Reimplemented in espectre::LightweightDetector.

Definition at line 171 of file base_detector.h.

◆ startup_gate_enabled()

virtual bool espectre::BaseDetector::startup_gate_enabled ( ) const

inlinevirtual

Whether startup calibration uses the consistency gate (threshold.h).

Enabled only for detectors with a tight quiet floor (l1_delta). Matches the Python runtime's detector STARTUP_GATE convention.

Reimplemented in espectre::LightweightDetector.

Definition at line 179 of file base_detector.h.

◆ on_startup_calibration_begin()

virtual void espectre::BaseDetector::on_startup_calibration_begin ( )

inlinevirtual

Hook called immediately before startup calibration begins.

Reimplemented in espectre::LightweightDetector.

Definition at line 182 of file base_detector.h.

◆ on_startup_calibration_complete()

virtual void espectre::BaseDetector::on_startup_calibration_complete ( )

inlinevirtual

Hook called when startup calibration completes successfully.

Detectors can freeze session-specific state here before the runtime performs its warm clear between calibration and steady-state detection.

Reimplemented in espectre::LightweightDetector.

Definition at line 190 of file base_detector.h.

◆ configure_lowpass()

virtual void espectre::BaseDetector::configure_lowpass	(	bool	enabled,
		float	cutoff_hz = LOWPASS_CUTOFF_DEFAULT )

virtual

Configure low-pass filter.

Parameters

enabled	Whether to enable the filter
cutoff_hz	Cutoff frequency (5.0-20.0 Hz)

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ configure_hampel()

virtual void espectre::BaseDetector::configure_hampel	(	bool	enabled,
		uint8_t	window_size = HAMPEL_TURBULENCE_WINDOW_DEFAULT,
		float	threshold = HAMPEL_TURBULENCE_THRESHOLD_DEFAULT )

virtual

Configure Hampel filter.

Parameters

enabled	Whether to enable the filter
window_size	Window size (3-11)
threshold	MAD multiplier threshold

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ clear_buffer()

virtual void espectre::BaseDetector::clear_buffer ( )

virtual

Clear turbulence buffer (cold restart).

Virtual so detectors with additional state (e.g. L1-Delta profile rings) can extend the cold clear.

Reimplemented in espectre::HighAccuracyDetector, and espectre::LightweightDetector.

◆ get_turbulence_buffer()

const float * espectre::BaseDetector::get_turbulence_buffer ( ) const

inline

Get turbulence buffer pointer.

Definition at line 231 of file base_detector.h.

◆ get_buffer_count()

uint16_t espectre::BaseDetector::get_buffer_count ( ) const

inline

Get number of valid samples in buffer.

Definition at line 236 of file base_detector.h.

◆ get_valid_buffer_count()

uint16_t espectre::BaseDetector::get_valid_buffer_count ( ) const

inline

Definition at line 237 of file base_detector.h.

◆ get_window_size()

uint16_t espectre::BaseDetector::get_window_size ( ) const

inline

Get configured window size.

Definition at line 242 of file base_detector.h.

◆ get_last_turbulence()

float espectre::BaseDetector::get_last_turbulence ( ) const

Get last turbulence value.

◆ is_lowpass_enabled()

bool espectre::BaseDetector::is_lowpass_enabled ( ) const

inline

Check if low-pass filter is enabled.

Definition at line 252 of file base_detector.h.

◆ is_hampel_enabled()

bool espectre::BaseDetector::is_hampel_enabled ( ) const

inline

Check if Hampel filter is enabled.

Definition at line 257 of file base_detector.h.

◆ clear_evaluation_state_()

void espectre::BaseDetector::clear_evaluation_state_ ( )

inlineprotected

Drop the last evaluation result.

Anything that invalidates the window must also invalidate what was derived from it, or the next publish ships a metric computed from samples the detector no longer holds. Owned here so a detector cannot clear one half and forget the other.

Definition at line 268 of file base_detector.h.

◆ process_amplitudes()

void espectre::BaseDetector::process_amplitudes	(	const float *	amplitudes,
		uint8_t	count )

protected

◆ packet_timestamp_us_or()

uint64_t espectre::BaseDetector::packet_timestamp_us_or ( uint64_t fallback ) const

inlineprotected

Definition at line 275 of file base_detector.h.

◆ add_turbulence_to_buffer()

void espectre::BaseDetector::add_turbulence_to_buffer ( float turbulence )

protected

Add turbulence value to buffer (with filtering).

◆ alloc_zeroed_floats()

float * espectre::BaseDetector::alloc_zeroed_floats ( uint16_t count )

staticprotected

Allocate a zeroed float buffer on the heap.

Shared by the detectors so no feature helper puts a window-sized array on the CSI callback stack.

Returns: nullptr when count is 0 or the allocation fails

◆ ordered_turbulence()

const float * espectre::BaseDetector::ordered_turbulence ( uint16_t & count ) const

protected

View the turbulence ring in chronological order.

Returns the ring itself while it is still filling (already in order), and the base-owned reorder buffer once it wraps. Returns nullptr when there is nothing to read or the reorder buffer could not be allocated.

Parameters

count Receives the number of valid samples

Member Data Documentation

◆ turbulence_buffer_

float* espectre::BaseDetector::turbulence_buffer_

protected

Definition at line 306 of file base_detector.h.

◆ ordered_turbulence_

float* espectre::BaseDetector::ordered_turbulence_

protected

Definition at line 307 of file base_detector.h.

◆ buffer_index_

uint16_t espectre::BaseDetector::buffer_index_

protected

Definition at line 308 of file base_detector.h.

◆ buffer_count_

uint16_t espectre::BaseDetector::buffer_count_

protected

Definition at line 309 of file base_detector.h.

◆ valid_buffer_count_

uint16_t espectre::BaseDetector::valid_buffer_count_

protected

Definition at line 310 of file base_detector.h.

◆ minimum_valid_samples_

uint16_t espectre::BaseDetector::minimum_valid_samples_

protected

Definition at line 311 of file base_detector.h.

◆ window_size_

uint16_t espectre::BaseDetector::window_size_

protected

Definition at line 312 of file base_detector.h.

◆ state_

MotionState espectre::BaseDetector::state_

protected

Definition at line 316 of file base_detector.h.

◆ current_metric_

float espectre::BaseDetector::current_metric_

protected

Definition at line 317 of file base_detector.h.

◆ total_packets_

uint32_t espectre::BaseDetector::total_packets_

protected

Definition at line 318 of file base_detector.h.

◆ packet_index_

uint32_t espectre::BaseDetector::packet_index_

protected

Definition at line 319 of file base_detector.h.

◆ packet_timestamp_us_

uint64_t espectre::BaseDetector::packet_timestamp_us_

protected

Definition at line 320 of file base_detector.h.

◆ has_packet_timestamp_

bool espectre::BaseDetector::has_packet_timestamp_

protected

Definition at line 321 of file base_detector.h.

◆ hampel_state_

hampel_filter_state_t espectre::BaseDetector::hampel_state_

protected

Definition at line 324 of file base_detector.h.

◆ lowpass_state_

lowpass_filter_state_t espectre::BaseDetector::lowpass_state_

protected

Definition at line 325 of file base_detector.h.

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

src/cpp/core/base_detector.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BaseDetector() [1/3]

◆ ~BaseDetector()

◆ BaseDetector() [2/3]

◆ BaseDetector() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ process_packet()

◆ set_packet_timestamp_us()

◆ reset()

◆ get_state()

◆ is_ready()

◆ advance_missing_slots()

◆ set_minimum_valid_samples()

◆ get_total_packets()

◆ update_state()

◆ get_motion_metric()

◆ set_threshold()

◆ set_adaptive_threshold()

◆ get_threshold()

◆ get_name()

◆ get_startup_threshold_factor()

◆ startup_gate_enabled()

◆ on_startup_calibration_begin()

◆ on_startup_calibration_complete()

◆ configure_lowpass()

◆ configure_hampel()

◆ clear_buffer()

◆ get_turbulence_buffer()

◆ get_buffer_count()

◆ get_valid_buffer_count()

◆ get_window_size()

◆ get_last_turbulence()

◆ is_lowpass_enabled()

◆ is_hampel_enabled()

◆ clear_evaluation_state_()

◆ process_amplitudes()

◆ packet_timestamp_us_or()

◆ add_turbulence_to_buffer()

◆ alloc_zeroed_floats()

◆ ordered_turbulence()

Member Data Documentation

◆ turbulence_buffer_

◆ ordered_turbulence_

◆ buffer_index_

◆ buffer_count_

◆ valid_buffer_count_

◆ minimum_valid_samples_

◆ window_size_

◆ state_

◆ current_metric_

◆ total_packets_

◆ packet_index_

◆ packet_timestamp_us_

◆ has_packet_timestamp_

◆ hampel_state_

◆ lowpass_state_