francescopace/espectreESPectre — система обнаружения движения на основе анализа Wi-Fi спектра (CSI) с интеграцией с Home Assistant.
Система обнаружения движения на основе анализа Wi-Fi спектра (CSI), с нативной интеграцией Home Assistant через ESPHome.
[!TIP] Новый ML-детектор: Обнаружение движения на основе нейронной сети. Не требует калибровки, работает на устройстве. Это экспериментальная функция, и мы приветствуем обратную связь в специальном обсуждении ML-детектора. Также доступна снапшот-сборка с последними изменениями (используйте ресурсы
-mlдля детектора на основе машинного обучения) или следуйте руководству по настройке для пользовательской конфигурации.
ESP32-S3 DevKit с внешними антеннами
Время настройки: ~10-15 минут
Сложность: Легко (только конфигурация YAML)
Панель Home Assistant с обнаружением движения в реальном времени, управлением порогом и отладочными датчиками
Когда кто-то движется в комнате, он «возмущает» волны Wi-Fi, распространяющиеся между роутером и датчиком. Это похоже на то, как вы двигаете рукой перед фонариком и видите, как меняется тень.
Устройство ESP32 «слушает» эти изменения и определяет, есть ли движение.
Хотите понять технические детали? Смотрите ALGORITHMS.md для объяснения CSI и документации по обработке сигналов.
Оптимальное размещение датчика имеет решающее значение для надёжного обнаружения движения.
Оптимальный диапазон: 3-8 метров
Делайте:
Не делайте:
┌─────────────┐ │ CSI Data │ Raw Wi-Fi Channel State Information └──────┬──────┘ │ ▼ ┌─────────────┐ │ Gain Lock │ AGC/FFT stabilization (~3 seconds) │ │ Locks hardware gain for stable measurements └──────┬──────┘ │ ▼ ┌─────────────┐ │ Auto │ Automatic subcarrier selection (once at boot) │ Calibration │ Selects optimal 12 subcarriers (NBVI) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Adaptive │ auto: P95 × 1.1 | min: P100 │ Threshold │ or fixed manual value └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hampel │ Turbulence outlier removal │ Filter │ (enabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Low-pass │ Noise reduction (smoothing) │ Filter │ (optional, disabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Detection │ MVS or ML score │ Evaluation │ every evaluation_interval packets └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hit Filter │ motion_on_hits / motion_off_hits │ │ edge-driven IDLE ↔ MOTION └──────┬──────┘ │ ▼ ┌─────────────┐ │ Home │ Edge-driven motion binary + │ Assistant │ periodic Movement Score / Threshold └─────────────┘
### Один или несколько датчиков```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Каждый датчик автоматически обнаруживается Home Assistant с помощью:
ESPectre реализует NBVI (Normalized Band Variance Index) для автоматического выбора поднесущих, достигая почти оптимальной производительности (F1>96%) без ручной настройки. Алгоритм выбирает 12 непоследовательных поднесущих на основе показателей стабильности и спектрального разнообразия.
⚠️ ВАЖНО (режим MVS): Оставьте комнату тихой и неподвижной в течение 10 секунд после запуска устройства. Автоматическая калибровка выполняется в это время, и движение повлияет на точность обнаружения. Режим ML пропускает калибровку.
Подробности алгоритма см. в ALGORITHMS.md.
В: Нужны ли знания программирования для использования?
О: Нет! ESPectre использует файлы конфигурации YAML. Просто скачайте пример, прошейте его и настройте Wi-Fi через приложение ESPHome или веб-интерфейс.
В: Работает ли с моим роутером?
О: Да, если ваш роутер поддерживает Wi-Fi 2,4 ГГц (практически все современные роутеры это имеют).
В: Сколько это стоит в общей сложности?
О: Оборудование: ~€10 за устройство ESP32 (рекомендуется S3/C6, другие варианты тоже работают). Программное обеспечение: всё бесплатно и с открытым исходным кодом. Также вам понадобится работающий Home Assistant (Raspberry Pi ~€35-50 или любой существующий ПК/NAS).
В: Нужно ли что-то менять в роутере?
О: Нет! Роутер работает нормально. Датчик «слушает» сигналы Wi-Fi, ничего не изменяя.
В: Работает ли сквозь стены?
О: Да, сигнал Wi-Fi 2,4 ГГц проникает через гипсокартон. Стены из армированного бетона снижают чувствительность, но обнаружение остается возможным на уменьшенных расстояниях.
В: Сколько датчиков нужно для дома?
О: Зависит от размера. Один датчик может контролировать ~50 м². Для больших домов используйте несколько датчиков (1 датчик на каждые 50-70 м² для оптимального покрытия).
В: Может ли система различать людей и домашних животных?
О: Система использует двухсостоятельную модель сегментации (IDLE/MOTION), которая определяет общее движение, не различая людей, животных или другие движущиеся объекты. Для более сложной классификации (люди против животных, распознавание активности, обнаружение жестов) потребуются обученные модели ИИ/МО (см. раздел Будущее развитие).
В: Работает ли с mesh-сетями Wi-Fi?
О: Да, работает нормально. Убедитесь, что ESP32 подключается к диапазону 2,4 ГГц.
В: Насколько точное обнаружение?
О: Точность обнаружения сильно зависит от окружения и требует правильной настройки. Факторы, влияющие на производительность: планировка комнаты, материалы стен, расположение мебели, расстояние до роутера (оптимально: 3-8 м) и уровень помех. В оптимальных условиях с правильной настройкой система обеспечивает надежное обнаружение движения. Настройте параметр segmentation_threshold для регулировки чувствительности под ваше конкретное окружение.
В: Какое энергопотребление?
О: ~500 мВт в типичном режиме непрерывной работы. Прошивка включает поддержку оптимизации энергопотребления, а режимы глубокого сна могут быть реализованы для развертывания на батарейках, хотя для этого потребуются индивидуальные модификации кода.
Система собирает анонимные данные, связанные с физическими характеристиками радиоканала Wi-Fi:
Данные CSI представляют собой только свойства среды передачи и не содержат прямой идентифицирующей информации.
ПРЕДУПРЕЖДЕНИЕ: Несмотря на внутреннюю анонимность данных CSI, эта система может использоваться для:
Пользователь несет единоличную ответственность за использование этой системы и должен:
Подробности алгоритмов (MVS, калибровка NBVI, фильтр Хампеля) см. в ALGORITHMS.md.
Показатели производительности (матрица ошибок, F1-мера, бенчмарки) см. в PERFORMANCE.md.
Этот проект использует двухплатформенный подход для баланса между скоростью инноваций и стабильностью производства:
Цель: Конечные пользователи, энтузиасты умного дома, пользователи Home Assistant
Цель: Исследователи, разработчики, академические/промышленные приложения
Micro-ESPectre предоставляет основы для:
┌─────────────────────┐ Validated ┌──────────────────────┐ │ Micro-ESPectre │ ─────────────────► │ ESPectre │ │ (R&D Platform) │ algorithms │ (Production Platform)│ │ │ │ │ │ • Fast prototyping │ │ • ESPHome component │ │ • Algorithm testing │ │ • Home Assistant │ │ • Data analysis │ │ • End-user ready │ │ • MQTT flexibility │ │ • Native API │ └─────────────────────┘ └──────────────────────┘
**Цикл инноваций**: Новые функции и алгоритмы сначала разрабатываются и валидируются в Micro-ESPectre (Python), затем портируются в ESPectre (C++) после доказательства эффективности.
---
## Будущее развитие
В то время как ESPectre v2.x сосредоточен на **обнаружении движения** (MVS + автоматический выбор поднесущей), проект исследует возможности машинного обучения для продвинутых приложений:
| Возможность | Статус | Описание |
|------------|--------|-------------|
| **ML Detector** | Экспериментальный | Нейронная сеть (MLP 9→32→16→1)|
| **Распознавание жестов** | Запланировано | Обнаружение жестов рук (свайп, толчок, круг) для управления умным домом |
| **Распознавание активности человека** | Запланировано | Определение действий (сидение, ходьба, падение) |
| **Подсчёт людей** | Запланировано | Оценка количества людей в комнате |
| **3D-локализация** | Исследование | Внутреннее позиционирование (точность 30-50 см) с помощью когерентной по фазе антенной решётки |
ML Detector уже доступен с параметром `detection_algorithm: ml` в вашей YAML-конфигурации. Подробности об алгоритме см. в [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector), а текущие метрики — в `PERFORMANCE.md`.
Инфраструктура сбора данных и обучения ML описана в [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md).
Подробные планы, сроки и информацию о том, как внести вклад, см. в [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md).
---
## Документация
### ESPectre (Продукт)
| Документ | Описание |
|----------|-------------|
| [Введение](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Этот файл) Обзор проекта, быстрый старт, FAQ |
| [Руководство по настройке](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Установка и настройка с ESPHome |
| [Руководство по настройке параметров](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Настройка параметров для оптимального обнаружения |
| [Производительность](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Бенчмарки, матрица ошибок, F1-мера |
| [Игра](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Браузерная игра, USB-потоковый API, интерактивная настройка порога |
| [Набор тестов](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | Документация тестов PlatformIO Unity |
### Micro-ESPectre (R&D)
| Документ | Описание |
|----------|-------------|
| [Введение](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Обзор R&D-платформы, CLI, MQTT, веб-монитор |
| [Алгоритмы](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Научная документация MVS, калибровки NBVI, фильтра Хэмпеля |
| [Инструменты анализа](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | Скрипты анализа и оптимизации CSI |
| [Сбор данных ML](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Создание размеченных наборов данных для машинного обучения |
| [Ссылки](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Академические статьи и исследовательские ресурсы |
### Проект
| Документ | Описание |
|----------|-------------|
| [Дорожная карта](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Видение проекта и планы по ML |
| [Участие](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | Как внести вклад (код, данные, документация) |
| [История изменений](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | История версий и примечания к релизам |
| [Безопасность](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Политика безопасности и сообщение об уязвимостях |
| [Кодекс поведения](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Правила сообщества |
---
## Медиа
| Статьи | Название |
|-------------|-------|
| Medium | [How I Turned My Wi-Fi Into a Motion Sensor - Part 1](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-61a631a9b4ec?sk=c7f79130d78b0545fce4a228a6a79af3&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| Medium | [How I Turned My Wi-Fi Into a Motion Sensor - Part 2](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-part-2-62038130e530?sk=7c8b6f11cf3fcb8d279648016ebff72a&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| IoT For All | [How I Turned My Wi-Fi Into a Motion Sensor](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Make Your Own ESP32-Based Person Sensor, No Special Hardware Needed](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [ESPectre Human Detector for Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Deploying Espectre on Seeed Studio XIAO ESP32 Series with ESPHome](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Блог | Обсуждение |
|----------|------------|
| Home Assistant | [ESPectre - Wi-Fi Motion Detection for Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Видео | Видео |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Подкасты | Выпуск |
|-------------|---------|
| Hackaday | [Podcast Episode 355: Person Detectors, Walkie Talkies, Open Smartphones...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Связанные проекты
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): дополняющий проект для определения присутствия, ориентированный на наблюдения BLE-радио с хост-устройств (Python), с опциональной HTTP-панелью управления.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): кастомный форк MicroPython, открывающий доступ к API CSI ESP32, используемый как прошивочная основа для быстрого прототипирования CSI в рабочем процессе Micro-ESPectre.
---
## Благодарности
ESPectre использует нативные возможности CSI Wi-Fi чипов ESP32. Спасибо [Espressif](https://www.espressif.com/) за то, что сделали CSI доступным в фреймворке ESP-IDF и признали ESPectre [проектом сообщества](https://github.com/espressif/esp-csi#6-related-resources) в своём репозитории [esp-csi](https://github.com/espressif/esp-csi).
---
## Лицензия
Этот проект выпущен под лицензией **GNU General Public License v3.0 (GPLv3)**.
GPLv3 гарантирует, что:
- Программное обеспечение остаётся свободным и с открытым исходным кодом
- Каждый может использовать, изучать, модифицировать и распространять его
- Модификации должны распространяться под той же лицензией
- Защищаются права конечных пользователей и свобода ПО
Полный текст лицензии см. в [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE).
Вклады принимаются на условиях GPLv3 и должны содержать DCO-метку
`Signed-off-by` в каждом коммите (`git commit -s`).
## Автор
**Франческо Паче**
Email: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Если вы считаете ESPectre полезным и хотите поддержать его разработку, вы можете угостить меня кофе. Это совершенно необязательно.
Я работаю над этим проектом, потому что я увлечён им. Ваши пожертвования помогают мне покупать новое оборудование для расширения списка протестированных и поддерживаемых устройств, а также уделять больше времени новым функциям.
<a href="https://www.buymeacoffee.com/espectre" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/9574/a7e8174c892355a24fbaec083cbef385d097a0b488fd4823dbbb0061643bb5e2.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
| Расстояние | Сигнал | Многолучёвость | Чувствительность | Шум | Рекомендация |
|---|
| < 2м | Слишком сильный | Минимальная | Низкая | Низкий | ❌ Слишком близко |
| 3-8м | Сильный | Хорошая | Высокая | Низкий | ✅ Оптимально |
| > 10-15м | Слабый | Переменная | Низкая | Высокий | ❌ Слишком далеко |
В: Если не работает, могу ли я получить помощь?
О: Да, откройте Issue на GitHub или свяжитесь со мной по электронной почте.