Neural motion detector, using the MLP weights exported by training. More...

#include <high_accuracy_detector.h>

Inheritance diagram for espectre::HighAccuracyDetector:

Public Member Functions
	HighAccuracyDetector (uint16_t window_size=DETECTOR_DEFAULT_WINDOW_SIZE, float threshold=HIGH_ACCURACY_DEFAULT_THRESHOLD, uint16_t lag=L1_DELTA_LAG)
	Constructor.
	~HighAccuracyDetector () override
	HighAccuracyDetector (HighAccuracyDetector &&other) noexcept
HighAccuracyDetector &	operator= (HighAccuracyDetector &&other) noexcept
	HighAccuracyDetector (const HighAccuracyDetector &)=delete
HighAccuracyDetector &	operator= (const HighAccuracyDetector &)=delete
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) override
	Process a CSI packet and update internal state.
void	advance_missing_slots (uint32_t count) override
	Advance packet-indexed feature rings for absent temporal slots.
void	update_state () override
	Update state machine (call at publish interval).
void	clear_buffer () override
	Clear turbulence buffer (cold restart).
bool	is_ready () const override
	Check if detector is ready (buffer filled).
bool	set_threshold (float threshold) override
	Set detection threshold.
float	get_threshold () const override
	Get current threshold.
const char *	get_name () const override
	Get detector name for logging.
void	configure_hampel (bool enabled, uint8_t window_size=HAMPEL_TURBULENCE_WINDOW_DEFAULT, float threshold=HAMPEL_TURBULENCE_THRESHOLD_DEFAULT) override
	Configure Hampel filter.
void	configure_lowpass (bool enabled, float cutoff_hz=LOWPASS_CUTOFF_DEFAULT) override
	Configure low-pass filter.
Public Member Functions inherited from espectre::BaseDetector
	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
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.
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.
float	get_motion_metric () const
	Get current motion metric value.
virtual bool	set_adaptive_threshold (float threshold)
	Apply a detector-specific startup-calibrated threshold.
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.
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.

Additional Inherited Members
Protected Member Functions inherited from espectre::BaseDetector
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 inherited from espectre::BaseDetector
static float *	alloc_zeroed_floats (uint16_t count)
	Allocate a zeroed float buffer on the heap.
Protected Attributes inherited from espectre::BaseDetector
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

Neural motion detector, using the MLP weights exported by training.

Unlike LightweightDetector it does not calibrate to the room: it ships a fixed threshold learned at training time, so it performs best in environments the training corpus represents. Check the per-chip figures in docs/performance/README.md before choosing it over Lightweight.

Same usage as LightweightDetector on the core-only path, and the same threading rules. core/ml_weights.h is generated by the training script and must not be edited by hand; retraining is documented in docs/ML_TRAINING.md.

Definition at line 45 of file high_accuracy_detector.h.

Constructor & Destructor Documentation

◆ HighAccuracyDetector() [1/3]

espectre::HighAccuracyDetector::HighAccuracyDetector	(	uint16_t	window_size = DETECTOR_DEFAULT_WINDOW_SIZE,
		float	threshold = HIGH_ACCURACY_DEFAULT_THRESHOLD,
		uint16_t	lag = L1_DELTA_LAG )

Constructor.

Parameters

window_size	Feature extraction window size (10-200 packets)
threshold	Motion detection threshold (0.0-1.0 on the ML probability scale)
lag	Profile-displacement distance in packets. Production uses the nominal-rate default. Alternate values are for replay experiments and require retraining before deployment.

◆ ~HighAccuracyDetector()

espectre::HighAccuracyDetector::~HighAccuracyDetector ( )

override

◆ HighAccuracyDetector() [2/3]

espectre::HighAccuracyDetector::HighAccuracyDetector ( HighAccuracyDetector && other )

noexcept

◆ HighAccuracyDetector() [3/3]

espectre::HighAccuracyDetector::HighAccuracyDetector ( const HighAccuracyDetector & )

delete

Member Function Documentation

◆ operator=() [1/2]

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

noexcept

◆ operator=() [2/2]

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

delete

◆ process_packet()

void espectre::HighAccuracyDetector::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 )

overridevirtual

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 from espectre::BaseDetector.

◆ advance_missing_slots()

void espectre::HighAccuracyDetector::advance_missing_slots ( uint32_t count )

overridevirtual

Advance packet-indexed feature rings for absent temporal slots.

Reimplemented from espectre::BaseDetector.

◆ update_state()

void espectre::HighAccuracyDetector::update_state ( )

overridevirtual

Update state machine (call at publish interval).

Subclasses implement their detection algorithm here.

Implements espectre::BaseDetector.

◆ clear_buffer()

void espectre::HighAccuracyDetector::clear_buffer ( )

overridevirtual

Clear turbulence buffer (cold restart).

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

Reimplemented from espectre::BaseDetector.

◆ is_ready()

bool espectre::HighAccuracyDetector::is_ready ( ) const

overridevirtual

Check if detector is ready (buffer filled).

Reimplemented from espectre::BaseDetector.

◆ set_threshold()

bool espectre::HighAccuracyDetector::set_threshold ( float threshold )

overridevirtual

Set detection threshold.

Parameters

threshold New threshold value

Returns: true if value was accepted

Implements espectre::BaseDetector.

◆ get_threshold()

float espectre::HighAccuracyDetector::get_threshold ( ) const

inlineoverridevirtual

Get current threshold.

Implements espectre::BaseDetector.

Definition at line 85 of file high_accuracy_detector.h.

◆ get_name()

const char * espectre::HighAccuracyDetector::get_name ( ) const

inlineoverridevirtual

Get detector name for logging.

Implements espectre::BaseDetector.

Definition at line 86 of file high_accuracy_detector.h.

◆ configure_hampel()

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

overridevirtual

Configure Hampel filter.

Parameters

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

Reimplemented from espectre::BaseDetector.

◆ configure_lowpass()

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

overridevirtual

Configure low-pass filter.

Parameters

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

Reimplemented from espectre::BaseDetector.

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

src/cpp/core/high_accuracy_detector.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ HighAccuracyDetector() [1/3]

◆ ~HighAccuracyDetector()

◆ HighAccuracyDetector() [2/3]

◆ HighAccuracyDetector() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ process_packet()

◆ advance_missing_slots()

◆ update_state()

◆ clear_buffer()

◆ is_ready()

◆ set_threshold()

◆ get_threshold()

◆ get_name()

◆ configure_hampel()

◆ configure_lowpass()