Passive RSSI-based motion and presence detector. More...

#include <PoliticianSense.h>

Public Member Functions
	PoliticianSense ()

void	begin (Politician &engine, const uint8_t *anchorBssid=nullptr)
	Attaches the sensor to a Politician engine.

bool	beginBySSID (Politician &engine, const char *ssid)
	Looks up an AP by SSID in the engine cache and anchors to its BSSID.

void	setSenseCallback (SenseCb cb)
	Sets the state-change callback.

void	setPacketLogger (Politician::PacketCb cb)
	Registers a pass-through raw-packet callback.

void	setThreshold (float dBm2)
	Sets the variance threshold (dBm²) that triggers SENSE_MOTION.

void	setWindowSize (uint8_t n)
	Sets the sliding window size in samples (clamped to [4, POLITICIAN_SENSE_MAX_WINDOW]).

void	setDebounce (uint32_t ms)
	Sets the debounce hold-time (ms).

void	setStaleTimeout (uint32_t ms)
	Sets the stale-data timeout (ms).

void	tick ()
	Main worker — call from loop() alongside engine.tick().

float	getVariance () const

float	getMeanRssi () const

SenseEvent	getState () const

uint32_t	getTotalSamples () const

bool	hasAnchor () const

const uint8_t *	getAnchor () const

void	reset ()
	Clears the sample window and resets state without detaching from the engine.

void	end ()
	Detaches from the engine and clears its packet logger.

	~PoliticianSense ()

Static Public Attributes
static constexpr uint8_t	DEFAULT_WINDOW = 32
	Sliding window (samples).

static constexpr float	DEFAULT_THRESHOLD = 6.0f
	Variance threshold (dBm²).

static constexpr uint32_t	DEFAULT_DEBOUNCE = 2000
	Motion hold-time (ms).

static constexpr uint32_t	DEFAULT_STALE_MS = 10000
	Max gap before ignoring stale data (ms).

Detailed Description

Passive RSSI-based motion and presence detector.

Hooks into a Politician engine via the packet logger callback and tracks RSSI variance from a fixed anchor AP over a configurable sliding window. Fires a SenseCb whenever the space transitions between quiet and active.

Definition at line 105 of file PoliticianSense.h.

Constructor & Destructor Documentation

◆ PoliticianSense()

politician::PoliticianSense::PoliticianSense ( )

inline

Definition at line 113 of file PoliticianSense.h.

◆ ~PoliticianSense()

politician::PoliticianSense::~PoliticianSense ( )

inline

Definition at line 408 of file PoliticianSense.h.

Member Function Documentation

◆ begin()

void politician::PoliticianSense::begin	(	Politician &	engine,
		const uint8_t *	anchorBssid = `nullptr`
	)

inline

Attaches the sensor to a Politician engine.

Parameters

engine	The running Politician instance.
anchorBssid	6-byte BSSID of the anchor AP, or nullptr to sample every AP.

Installs an internal packet logger on the engine. If you also need raw frame access, call sense.setPacketLogger() before begin() to chain a pass-through callback. Setting it after begin() is a data race — the engine worker task may be concurrently reading _userPacketCb.

The engine must already be initialized (begin() called) before calling this. For continuous sensing, lock the engine to the anchor's channel: engine.lockChannel(anchorChannel);

Note: cfg.capture_filter must include LOG_FILTER_BEACONS before engine.begin() is called. Beacons are the primary RSSI source and PoliticianSense will collect no samples without them. Set it in Config:
Config cfg;

cfg.capture_filter |= LOG_FILTER_BEACONS;

engine.begin(cfg);

sense.begin(engine, anchorBssid);

LOG_FILTER_BEACONS
#define LOG_FILTER_BEACONS
Definition PoliticianTypes.h:54

engine
Politician engine
Definition main.cpp:6

politician::Config::capture_filter
uint8_t capture_filter
Definition PoliticianTypes.h:122

politician::Config
Configuration for the Politician engine.
Definition PoliticianTypes.h:106

Definition at line 158 of file PoliticianSense.h.

References engine, and politician::Politician::setPacketLogger().

◆ beginBySSID()

bool politician::PoliticianSense::beginBySSID	(	Politician &	engine,
		const char *	ssid
	)

inline

Looks up an AP by SSID in the engine cache and anchors to its BSSID.

Parameters

engine	The running Politician instance.
ssid	Exact SSID string to match.

Returns: true if the SSID was found and the sensor was anchored. false if the SSID is not yet in the engine's AP cache — call again after the engine has had time to scan.

When multiple BSSIDs share the same SSID the strongest signal is chosen.

Definition at line 197 of file PoliticianSense.h.

References engine, and politician::ApRecord::ssid.

◆ end()

void politician::PoliticianSense::end ( )

inline

Detaches from the engine and clears its packet logger.

Sets _active = false first so any _onPacket() invocation already in flight on the engine worker task will bail out immediately without touching members. Then clears the engine's packet logger slot so no further calls are dispatched.

Warning: This does NOT provide a hard synchronisation barrier. If the engine worker task has already passed the if (!_active) guard before end() writes the flag, it may still access members after end() returns. This window is narrow but real on a multi-core ESP32.

Safe usage pattern when destroying from a different core/task:

sense.end();
delay(20); // > one engine tick — guarantees any in-flight call has returned
// now safe to destroy or reuse

Calling end() from the same task/core as the engine worker (e.g. in loop()) is always safe with no delay required.

Definition at line 397 of file PoliticianSense.h.

◆ getAnchor()

const uint8_t * politician::PoliticianSense::getAnchor ( ) const

inline

Returns: Pointer to the 6-byte anchor BSSID (all-zeros if any-anchor mode).

Definition at line 367 of file PoliticianSense.h.

◆ getMeanRssi()

float politician::PoliticianSense::getMeanRssi ( ) const

inline

Returns: Mean RSSI across the window (dBm). Updated by tick().

Definition at line 350 of file PoliticianSense.h.

◆ getState()

SenseEvent politician::PoliticianSense::getState ( ) const

inline

Returns: Current sense state (SENSE_STILL or SENSE_MOTION).

Definition at line 353 of file PoliticianSense.h.

◆ getTotalSamples()

uint32_t politician::PoliticianSense::getTotalSamples ( ) const

inline

Returns: Total RSSI samples collected since begin().

Definition at line 356 of file PoliticianSense.h.

◆ getVariance()

float politician::PoliticianSense::getVariance ( ) const

inline

Returns: Current RSSI variance across the window (dBm²). Updated by tick().

Definition at line 347 of file PoliticianSense.h.

◆ hasAnchor()

bool politician::PoliticianSense::hasAnchor ( ) const

inline

Returns: True if anchored to a specific BSSID, false if sampling all APs.

Definition at line 364 of file PoliticianSense.h.

◆ reset()

void politician::PoliticianSense::reset ( )

inline

Clears the sample window and resets state without detaching from the engine.

Useful when the environment changes (furniture moved, AP relocated, etc.).

Definition at line 373 of file PoliticianSense.h.

◆ setDebounce()

void politician::PoliticianSense::setDebounce ( uint32_t ms )

inline

Sets the debounce hold-time (ms).

MOTION state is held for this long after the last variance spike before returning to STILL, preventing rapid flickering during intermittent movement. Default: 2000 ms

Definition at line 266 of file PoliticianSense.h.

◆ setPacketLogger()

void politician::PoliticianSense::setPacketLogger ( Politician::PacketCb cb )

inline

Registers a pass-through raw-packet callback.

Called on every frame after PoliticianSense has processed it, so you can use raw packet access alongside sensing.

Note: Like all Politician callbacks, this must be set before begin() or after end(). Changing it while the engine is running is not thread-safe.

Definition at line 234 of file PoliticianSense.h.

◆ setSenseCallback()

void politician::PoliticianSense::setSenseCallback ( SenseCb cb )

inline

Sets the state-change callback.

Fired once when the space transitions STILL→MOTION or MOTION→STILL. Do not call engine.tick() or blocking operations from inside the callback.

Definition at line 224 of file PoliticianSense.h.

◆ setStaleTimeout()

void politician::PoliticianSense::setStaleTimeout ( uint32_t ms )

inline

Sets the stale-data timeout (ms).

If no new RSSI samples arrive for this duration, tick() skips processing to avoid acting on stale window data (e.g., when hopping away from the anchor). Default: 10000 ms

Definition at line 274 of file PoliticianSense.h.

◆ setThreshold()

void politician::PoliticianSense::setThreshold ( float dBm2 )

inline

Sets the variance threshold (dBm²) that triggers SENSE_MOTION.

Lower values = more sensitive; higher values = less false positives. Useful range: 3.0–15.0. Default: 6.0

Definition at line 243 of file PoliticianSense.h.

◆ setWindowSize()

void politician::PoliticianSense::setWindowSize ( uint8_t n )

inline

Sets the sliding window size in samples (clamped to [4, POLITICIAN_SENSE_MAX_WINDOW]).

At ~10 beacons/sec on a locked channel, 32 samples ≈ 3 seconds of history. Smaller = faster response; larger = smoother, fewer false triggers. Default: 32

Definition at line 250 of file PoliticianSense.h.

References POLITICIAN_SENSE_MAX_WINDOW.

◆ tick()

void politician::PoliticianSense::tick ( )

inline

Main worker — call from loop() alongside engine.tick().

Computes variance from the current window snapshot and fires the SenseCb if a STILL↔MOTION transition is detected.

Definition at line 283 of file PoliticianSense.h.

References millis(), POLITICIAN_SENSE_MAX_WINDOW, politician::SENSE_MOTION, and politician::SENSE_STILL.

Member Data Documentation

◆ DEFAULT_DEBOUNCE

constexpr uint32_t politician::PoliticianSense::DEFAULT_DEBOUNCE = 2000

staticconstexpr

Motion hold-time (ms).

Definition at line 110 of file PoliticianSense.h.

◆ DEFAULT_STALE_MS

constexpr uint32_t politician::PoliticianSense::DEFAULT_STALE_MS = 10000

staticconstexpr

Max gap before ignoring stale data (ms).

Definition at line 111 of file PoliticianSense.h.

◆ DEFAULT_THRESHOLD

constexpr float politician::PoliticianSense::DEFAULT_THRESHOLD = 6.0f

staticconstexpr

Variance threshold (dBm²).

Definition at line 109 of file PoliticianSense.h.

◆ DEFAULT_WINDOW

constexpr uint8_t politician::PoliticianSense::DEFAULT_WINDOW = 32

staticconstexpr

Sliding window (samples).

Definition at line 108 of file PoliticianSense.h.

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

src/PoliticianSense.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PoliticianSense()

◆ ~PoliticianSense()

Member Function Documentation

◆ begin()

◆ beginBySSID()

◆ end()

◆ getAnchor()

◆ getMeanRssi()

◆ getState()

◆ getTotalSamples()

◆ getVariance()

◆ hasAnchor()

◆ reset()

◆ setDebounce()

◆ setPacketLogger()

◆ setSenseCallback()

◆ setStaleTimeout()

◆ setThreshold()

◆ setWindowSize()

◆ tick()

Member Data Documentation

◆ DEFAULT_DEBOUNCE

◆ DEFAULT_STALE_MS

◆ DEFAULT_THRESHOLD

◆ DEFAULT_WINDOW