PoliticianSense.h File Reference

Opt-in passive RSSI-based presence and motion sensing for the Politician engine. More...

#include "Politician.h"
#include <freertos/FreeRTOS.h>
#include <freertos/portmacro.h>
#include <string.h>

Include dependency graph for PoliticianSense.h:

Go to the source code of this file.

Classes
class	politician::PoliticianSense
	Passive RSSI-based motion and presence detector. More...

Namespaces
namespace	politician

Macros
#define	POLITICIAN_SENSE_MAX_WINDOW   64
	Maximum ring-buffer capacity (samples).

Typedefs
using	politician::SenseCb = std::function< void(SenseEvent event, float variance)>
	Callback fired on SENSE_STILL ↔ SENSE_MOTION transitions.

Enumerations
enum	politician::SenseEvent : uint8_t {   politician::SENSE_MOTION = 0 ,   politician::SENSE_STILL = 1 }
	State transition delivered to the SenseCb callback. More...

Detailed Description

Opt-in passive RSSI-based presence and motion sensing for the Politician engine.

Hooks into the engine's promiscuous-mode packet stream and monitors beacon RSSI variance from a fixed anchor AP to detect human presence and motion — device-free, zero mode switching, zero conflicts with the core engine.

A human body walking between the anchor AP and the ESP32 scatters and absorbs 2.4GHz/5GHz radio waves, producing measurable fluctuations in received signal strength. By tracking the statistical variance of beacon RSSI over a sliding window, PoliticianSense classifies the monitored space as SENSE_STILL or SENSE_MOTION.

Usage:

#include <Politician.h>
#include <PoliticianSense.h>
 
politician::Politician   engine;
politician::PoliticianSense sense;
 
// Lock the engine to the anchor AP's channel for continuous data.
// During free channel hopping, samples only arrive when the radio
// happens to land on the anchor's channel (coarser, but still works).
uint8_t anchorBssid[] = {0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
 
// LOG_FILTER_BEACONS must be set before engine.begin().
politician::Config cfg;
cfg.capture_filter |= politician::LOG_FILTER_BEACONS;
engine.begin(cfg);
engine.lockChannel(6); // anchor AP's channel
 
sense.begin(engine, anchorBssid);
sense.setSenseCallback([](politician::SenseEvent ev, float variance) {
    if (ev == politician::SENSE_MOTION)
        Serial.printf("[SENSE] Motion detected!  variance=%.2f dBm²\n", variance);
    else
        Serial.printf("[SENSE] Area is still.    variance=%.2f dBm²\n", variance);
});
 
// In loop():
engine.tick();
sense.tick();

Anchor modes:

• Pass a 6-byte BSSID to anchor to a specific AP (recommended — most stable).
• Call beginBySSID() to look up the BSSID by SSID from the engine cache.
• Pass nullptr to sample all visible APs (noisier, useful without a fixed AP).

Threading: RSSI samples are written from Politician's internal worker task. tick() and all sense callbacks run on your calling task (usually loop()). A FreeRTOS spinlock protects the ring buffer across tasks.

Packet logger chaining: PoliticianSense installs itself as the engine's packet logger. If you also need raw frame access, call sense.setPacketLogger() before begin() to register a pass-through callback that fires on every frame after sensing.

Compile-time tuning: #define POLITICIAN_SENSE_MAX_WINDOW 128 // Enlarge maximum window (default 64)

Definition in file PoliticianSense.h.

Macro Definition Documentation

POLITICIAN_SENSE_MAX_WINDOW

#define POLITICIAN_SENSE_MAX_WINDOW   64

Maximum ring-buffer capacity (samples).

Definition at line 93 of file PoliticianSense.h.