v2.5.0 - ML Detector, Training Pipeline & Pre-built Firmware

[francescopace]

Highlights

• ML Detector (Experimental): Neural network-based motion detection with ~3s boot time (no calibration needed)
• Training Pipeline: Collect data, train, and export models for both platforms
• Pre-built Firmware: Ready-to-flash binaries for all 6 ESP32 variants via GitHub Releases
• PCA & P95 Removed: Simplified to MVS + ML detectors, NBVI-only calibration

ML Detector

First experimental release of a neural network-based motion detector, available in both C++ (ESPHome) and Python (Micro-ESPectre).

• Configuration: detection_algorithm: ml in YAML
• Performance: ~97-100% F1 score depending on chip
• Boot time: ~3 seconds (vs ~10s for MVS) — no band calibration needed
• Zero dependencies: Manual MLP inference, no TFLite required

espectre:
  detection_algorithm: ml

The pre-trained model shipped with this release was trained on a limited dataset collected in a single environment. It performs well in initial testing, but we need your help to make it better. If you try the ML detector, consider contributing baseline (empty room) and movement recordings from your environment — the more diverse the training data, the more robust the model becomes. See ML_DATA_COLLECTION.md for how to collect and submit data via pull request.

For architecture and feature details, see ALGORITHMS.md.

Training Pipeline

Collect labeled data, train a model, and export weights for both platforms:

./me collect --label <name> --duration <sec>   # Collect data
python tools/10_train_ml_model.py               # Train model

Exports ml_weights.py (Python), ml_weights.h (C++), and TFLite checkpoint. See ML_DATA_COLLECTION.md for the full workflow.

Pre-built Firmware & Easy Install

New release.yml workflow builds and publishes firmware for all supported chips (ESP32, S2, S3, C3, C5, C6) on every tagged release.

SETUP.md now offers two installation paths:

• Option A: Web Flash — Download from Releases, flash via ESPConnect in Chrome
• Option B: ESPHome CLI — Traditional esphome run workflow

Based on PR #77 by @WLaoDuo.

Removed

PCA Detection Algorithm: While PCA itself is a well-known statistical technique, our implementation was based on Espressif's open-source esp-radar library. Since Espressif has transitioned this library to closed source, we have removed our PCA implementation to ensure full compliance with our GPLv3 license.

MVS remains the recommended algorithm with excellent performance. Future development will focus on the ML detector, which shows very promising results in early testing and requires no initial calibration.

P95 Calibrator: NBVI (Normalized Band Variance Index) is now the sole calibration algorithm. NBVI consistently outperforms P95 by selecting non-consecutive subcarriers for better spectral diversity and resilience to narrowband interference.

Improvements

• Gain lock: Median-based calibration (replaces mean), signed FFT gain fix, CV normalization when gain lock is skipped
• Bug fixes: Double amplitude calculation fix, stack allocation in Hampel filter

Micro-ESPectre (R&D Platform)

• Extended hardware support: me CLI now supports ESP32, C3, S3, C6 with auto-detection and SHA256 firmware verification
• ML detector filter support: ML detector now accepts low-pass and Hampel filter parameters, matching C++ implementation
• Import standardization: All src/ modules now use try/except ImportError pattern for MicroPython/CPython compatibility
• Bug fixes: Signed int8 CSI parsing, ESP32 flash offset corrected, LowPass default cutoff aligned to 11.0 Hz

For Contributors

Architecture changes and internal improvements

Architecture

• Calibrator simplification: Removed ICalibrator interface and BaseCalibrator base class, merging all functionality into NBVICalibrator
• Window size centralization: segmentation_window_size (default: 75) is now defined in a single source of truth (DETECTOR_DEFAULT_WINDOW_SIZE in C++, SEG_WINDOW_SIZE in Python) and passed to both detector and calibrator
• Calibration buffer size: Now calculated as 10 × window_size (default: 750 packets), automatically adapts if window size changes
• CV normalization: Both platforms use CV normalization consistently when gain lock is skipped
• Unified window size in tools: All analysis tools now use SEG_WINDOW_SIZE from config.py instead of hardcoded values

---

---

This discussion was created from the release v2.5.0 - ML Detector, Training Pipeline & Pre-built Firmware.