high_accuracy_detector.h

Go to the documentation of this file.

/*
 * ESPectre - High-Accuracy Detector
 *
 * Neural network-based motion detection algorithm.
 *
 * Algorithm:
 * 1. Calculate spatial turbulence per packet using CV normalization
 *    (`std/mean`)
 * 2. Apply optional Hampel filtering to turbulence and L1-delta streams
 * 3. Apply optional low-pass filter for noise reduction
 * 4. Extract statistical features from turbulence buffer
 * 5. Run MLP inference using exported architecture metadata
 * 6. Compare probability to threshold for motion detection
 *
 * Author: Francesco Pace <francesco.pace@gmail.com>
 * SPDX-License-Identifier: GPL-3.0-only
 * Commercial licensing available under separate agreement; see LICENSING.md.
 */
#pragma once
 
#include "base_detector.h"
#include "csi_format.h"
#include "csi_features.h"
#include "filtered_turbulence_ring.h"
#include "l1_delta_tracker.h"
#include "ml_feature_trackers.h"
#include <cstdint>
#include <cstddef>
 
namespace espectre {
 
/**
 * 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`.
 */
class HighAccuracyDetector : public BaseDetector {
public:
    /**
     * Constructor
     * 
     * @param window_size Feature extraction window size (10-200 packets)
     * @param threshold Motion detection threshold (0.0-1.0 on the ML probability scale)
     */
    /**
     * @param lag Profile-displacement distance in packets. Production uses the
     *        nominal-rate default. Alternate values are for replay experiments
     *        and require retraining before deployment.
     */
    HighAccuracyDetector(uint16_t window_size = DETECTOR_DEFAULT_WINDOW_SIZE,
               float threshold = HIGH_ACCURACY_DEFAULT_THRESHOLD,
               uint16_t lag = L1_DELTA_LAG);
    
    ~HighAccuracyDetector() override;
    
    // Move semantics inherited from BaseDetector
    HighAccuracyDetector(HighAccuracyDetector&& other) noexcept;
    HighAccuracyDetector& operator=(HighAccuracyDetector&& other) noexcept;
    
    // Disable copy
    HighAccuracyDetector(const HighAccuracyDetector&) = delete;
    HighAccuracyDetector& operator=(const HighAccuracyDetector&) = delete;
    
    // ========================================================================
    // BaseDetector interface implementation
    // ========================================================================
 
    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;
    void advance_missing_slots(uint32_t count) override;
    void update_state() override;
    void clear_buffer() override;
    bool is_ready() const override;
    bool set_threshold(float threshold) override;
    float get_threshold() const override { return threshold_; }
    const char* get_name() const override { return "High Accuracy"; }
    void configure_hampel(
        bool enabled,
        uint8_t window_size = HAMPEL_TURBULENCE_WINDOW_DEFAULT,
        float threshold = HAMPEL_TURBULENCE_THRESHOLD_DEFAULT) override;
    void configure_lowpass(
        bool enabled,
        float cutoff_hz = LOWPASS_CUTOFF_DEFAULT) override;
 
private:
    /**
     * Extract ML features from the turbulence buffer and tracker state
     */
    void extract_features(float* features_out);
 
    /**
     * L1-delta ring capacity for this window: window_size - lag (0 if window
     * is not larger than the lag).
     */
    uint16_t l1_delta_capacity_() const;
 
    /**
     * Total size of the single feature-scratch block, in floats.
     */
    uint16_t feature_scratch_size_() const;
 
    /**
     * Sorted-series view onto the scratch block. Empty when allocation failed.
     */
    MLSeriesScratch series_scratch_() const;
 
    void add_aggregated_turbulence_(float turbulence);
    const float* ordered_aggregated_turbulence_(uint16_t& count) const;
 
    /**
     * Run MLP inference on features.
     *
     * The hidden-layer layout is defined by the auto-generated
     * `ml_weights.h` metadata rather than hardcoded in this class.
     *
     * @param features Feature vector expected by the exported model
     * @return Motion probability (0.0-1.0)
     */
    float predict(const float* features);
 
    float threshold_;
 
    // L1-delta profile-displacement state, maintained only when the exported
    // model actually uses L1-delta features (checked against ML_FEATURE_IDS).
    // Mirrors the shared L1-delta tracker rings; keep aligned with the Python
    // lag ratio reference.
    bool uses_l1_tracker_;
    bool uses_shape_trajectory_tracker_;
    bool uses_aggregated_turbulence_;
    uint16_t lag_;
    L1DeltaTracker l1_tracker_;
    ChannelShapeTrajectoryTracker shape_trajectory_tracker_;
 
    // Single heap block reused for packet amplitudes, chronological aggregate
    // reconstruction, and sorted feature statistics, so these non-overlapping
    // phases do not each reserve a window-sized buffer.
    float* feature_scratch_;
    float* aggregated_turbulence_buffer_;
    FilteredTurbulenceRing aggregated_turbulence_;
};
 
}  // namespace espectre