Гайд по сборке простого Wi-Fi-радара

Подробное руководство по сборке радара для мониторинга присутствия в помещении человека и даже просто его дыхания.

Общий механизм выглядит так: ESP32-S3 измеряет параметры канала Wi-Fi 100 раз/сек, а Raspberry Pi их анализирует, в реальном времени выводя результат в браузере. Эта система обнаруживает абсолютно неподвижно сидящего человека по одному только движению его грудной клетки во время дыхания — без каких-либо камер, датчиков PIR или носимых устройств.

Содержание

• Что умеет эта система

• Чего она не умеет

• Принцип работы

• Что нужно купить

• Необходимое ПО

• Подключение компонентов

• Пошаговая сборка

• Запуск

• Чтение показаний в дашборде

• Как получить качественные результаты

• Все команды в одном месте

• Решение типичных проблем

• Готовые прошивки и образы контейнеров

• Структура репозитория

1. Что умеет система

2. Чего она не умеет

Этот раздел важнее списка возможностей, так как в большинстве тех заявлений о технологии Wi-Fi-sensing, которые можно встретить в сети, описываются совсем другие приборы.

К тому же, это не медицинский прибор. Это инструмент для спальни на базе микроконтроллера за $5.

3. Принцип работы

Общее описание:

Wi-Fi-сигнал приходит на приёмник сразу несколькими путями — как напрямую, так и в виде отражений от стен, мебели и людей. Все эти копии сигнала накладываются друг на друга с разными задержками, в результате чего некоторые частоты усиливаются, а некоторые друг друга гасят. Такая картина взаимодействия частот называется информацией о состоянии канала (Channel State Information, CSI), и её могут сообщать большинство микросхем Wi-Fi. Поместите что-либо в комнату, и длина пути сигнала изменится. Тело человека состоит преимущественно из воды и хорошо отражает волны на частоте 2,4 ГГц, что и делает людей видимыми. Длина волны на 2,4 ГГц составляет 12,5 см, так что смещение грудной клетки в диапазоне 6 мм при дыхании изменяет путь сигнала достаточно, чтобы это можно было измерить.

Путь данных

Поскольку мы сканируем пространство между роутером и ESP32, эти устройства нужно расположить в противоположных частях комнаты так, чтобы человек находился между ними.

Необходимость генерировать трафик

CSI существует только в момент получения пакетов. Сам по себе пустой канал не генерирует никаких данных, какое бы качественное оборудование вы ни использовали.

В данном проекте использован конкретно третий вариант, в связи с чем плату ESP32 необходимо полноценно подключать к Wi-Fi-сети. Благодаря этому, частота опроса задаётся программно, а не определяется случайно, и замеры происходят через равные промежутки времени, что нам и нужно для точного анализа дыхания.

Роль Pi

Две важные детали, от которых зависит, будет ли вообще работать эта схема:

• Оба частотных диапазона представляют доплеровские частоты, а не демонстрируют скорость движения человека. Отражатель, движущийся со скоростью v, сдвигает сигнал на величину v / длина волны. Таким образом, ходьба со скоростью 1 м/с ведёт к появлению всплеска в районе 8 Гц — но никак не на частоте шагов. Дыхание же остаётся в пределах всего 0,13—0,7 Гц, и это единственная причина, почему его удаётся разделить с движением.

• Все показания измеряются в дБ относительно собственного шума приёмника, поэтому для пустой комнаты они всегда будут равны 0 дБ — в любом помещении, на любом расстоянии и при любой мощности передатчика. Здесь нет этапа калибровки или заранее измеренного эталона, который мог бы со временем сбиваться. Собственный шум прибора определяется путём разложения ковариационной матрицы поднесущих частот. Суть в том, что внутри радиомодуля шум на каждой из этих частот является независимым в то время, как происходящие в комнате действия вызывают синхронное изменение всех поднесущих сразу.

4. Что нужно купить

Минимальная конфигурация (регистрация движения, присутствия, дыхания).

Вот и весь список покупок. Если малинка у вас уже есть, то общая стоимость практически сводится к цене ESP32.

По желанию: беспроводное подключение (установка узла в любом месте)

По желанию: мониторинг окружающей среды

Также пригодятся: макетная плата, соединительные провода Dupont и отдельный от Pi источник питания на 5 В, если вы планируете добавить MQ135 (его нагревательный элемент непрерывно потребляет ток ~150 мА).

5. Необходимое ПО

Установка пакетов ОС:

sudo apt update
sudo apt install -y git python3-venv python3-pip python3-numpy python3-scipy

6. Подключение

Простейший вариант сборки с одним кабелем

Raspberry Pi 4  ──── USB-кабель ────  макетка ESP32-S3 

Собственно, и всё. По кабелю передаётся питание и поток данных CSI. Ниже перечислены возможные дополнительные радиомодули и датчики.

Прочтите, прежде чем подключать что-либо к ESP32

Модуль N16R8 оснащён 16 МБ флэш-памяти Quad SPI и 8 МБ Octal PSRAM. При этом Octal PSRAM занимает выводы (GPIO) с 33 по 37. Если подключить периферию к неправильному выводу, плата просто не будет загружаться без какой-либо информативной ошибки. Именно так чаще всего этот модуль превращают в кирпич.

Что происходит на каждой шине

На одной шине SPI висит три устройства, каждое из которых имеет свою линию для выбора микросхемы. Датчик DHT22 работает по собственному однопроводному протоколу, а MQ135 является аналоговым.

Общая распиновка ESP32-S3

Сторона Raspberry Pi 4 (только при добавлении радиомодулей)

Общая шина SPI0 — подключается к обоим модулям:

nRF24L01+ → /dev/spidev0.0:

CC1101 → /dev/spidev0.1:

Расположение контактов на модулях CC1101 зависит от конкретной платы. Существует как минимум три популярных варианта разводки, и позиции пинов на них отличаются. Ориентируйтесь только по маркировкам на самой плате, а не по очерёдности выводов.

Датчики состояния окружающей среды (на ESP32)

BMP280 (SPI — использует общую шину и требует только собственной линии выбора микросхемы):

В режиме SPI линия SDA работает как вход, а SDO — как выход. То есть здесь не тот механизм, который предполагают маркировки для интерфейса I2C. Так что, если считать ID чипа не удаётся, первым делом поменяйте эти два провода местами.

Подключение DHT22 — VCC→3V3, DATA→GPIO16, GND→GND. Если у вас голый 4-контактный датчик, то потребуется добавить подтягивающий резистор на 10 kΩ между линиями DATA и 3V3; на 3-контактных модулях он уже присутствует.

Подключение MQ135 — VCC→5V, GND→GND, AO→GPIO4 через делитель напряжения:

   MQ135 AO ────[ 10k ]────┬────[ 10k ]──── GND
                           │
                           └──────► ESP32 GPIO4   (2.5 V max)

Нагреватель рассчитан на 5 В, а питаемый от 5 В контакт AO может выдавать напряжение до 5 В, что сожжёт АЦП ESP32, рассчитанный на 3,3 В. Здесь сгодится любая пара одинаковых резисторов — важно только соотношение их сопротивлений.

Альтернатива без резисторов: запитайте модуль от 3,3 В и подключите контакт AO напрямую (напряжение на нём физически не сможет превысить уровень питания датчика), а затем один раз укажите плате следующую настройку:

python tools/node.py mq135 supply 3v3

Выбор GPIO 4 не случаен: это должен быть один из выводов между GPIO 1 и 10, которые относятся к первому блоку АЦП (ADC1). Второй блок — ADC2 (выводы GPIO 11—20) — физически невозможно использовать во время работы Wi-Fi, так как радиомодуль полностью забирает этот преобразователь под свои нужды. Поскольку работа Wi-Fi — это главная цель данного проекта, использование блоков ADC2 исключено в принципе.

Питание — слабые места этой конфигурации

• Самый проблемный элемент — это модуль nRF24L01+ PA/LNA. В моменты всплесков на мощности +20 дБм скачки тока здесь достигают 115 мА, и шина питания 3,3 В малинки просто с ними не справляется. Симптом этой проблемы очень характерный: прибор успевает передать несколько пакетов, а затем замолкает. Чтобы решить проблему, припаяйте электролитический конденсатор на 10—100 мкФ вместе с керамическим на 100 нФ прямо к контактам VCC и GND радиомодуля — именно на плате модуля, а не на шине макетной платы. А ещё лучше — запитайте его от отдельного стабилизатора AMS1117-3.3, подключённого к 5 В.

• Подключайте антенны до включения питания. Передача сигнала в открытый порт может привести к повреждению усилителя.

• Подбирайте антенну для CC1101 строго под его частотный диапазон. Антенны на 433 и 868 МГц не взаимозаменяемы, и со стороны это их различие выглядит так, будто сгорел радиомодуль.

• Нагреватель MQ135 непрерывно потребляет ток около 150 мА. Если после его добавления ESP32 начинает уходить в перезагрузку из-за просадки питания, либо частота опроса CSI становится нестабильной — организуйте для датчика отдельное питание 5 В с общей землёй.

Вся логика процесса, вместе с пятью багами nRF24, которые пришлось исправлять для обеспечения надёжной связи, описана в разделе 4 файла PROJECT.txt.

7. Поэтапная сборка

Шаг 1 — скачайте код

git clone https://github.com/The-Masked-Bear/wifisense-pi.git
cd wifisense-pi

Шаг 2 — настройте окружение Python

Флаг --system-site-packages позволяет повторно использовать установленные через apt пакеты numpy и scipy, исключая необходимость их долгой компиляции на Pi.

python3 -m venv --system-site-packages .venv
./.venv/bin/pip install -r requirements.txt

Шаг 3 — протестируйте без подключения устройств

Синтетический канал связи — это не просто рандомная имитация, а полноценный симулятор, основанный на законах физики. Он запускает реальную цепочку детекторов, поэтому веб-панель ведёт себя точно так же, как и при подключении настоящего железа. Выполните этот тест в первую очередь. Так вы проверите корректность установки ПО до того, как начнёте разбираться, что и куда подключать.

cd pi
../.venv/bin/python -m wifisense --link synthetic

Откройте http://localhost:8080. Вы должны увидеть бегущий график “водопад” и изменение статусов. Остановить визуализацию можно комбинацией Ctrl-C.

Шаг 4 — прошейте ESP32

Скачайте готовый бинарник, или скомпилируйте его сами:

pip install platformio
cd firmware
pio run -t upload --upload-port /dev/ttyUSB0

Не обнаруживается подключение через USB? Выполните ls /dev/ttyUSB* и lsusb | grep -i "silicon labs". Если ничего не появится, сначала попробуйте использовать другой USB-кабель.

Шаг 5 — укажите узлу, к какому WiFi подключаться

Нужна сеть строго на 2,4 ГГц. Учётные данные сохраняются во флэш-памяти ESP32 и при отключении питания не стираются. Так что это разовый шаг, который не требует повторной компиляции.

cd pi
../.venv/bin/python tools/node.py wifi "YourSSID" "YourPassword"
../.venv/bin/python tools/node.py info      # Ищите assoc=yes и IP.

При открытии последовательного порта плата перезагружается, поэтому в течение нескольких первых секунд она будет недоступна. Скрипт tools/node.py дожидается её готовности, но при прямом подключении через терминал такого автоматического ожидания не будет.

Шаг 6 — полноценный запуск

cd pi
cp config.example.json config.json        # Не обязательно; вполне сгодятся и базовые установки.
../.venv/bin/python -m wifisense --link serial

Шаг 7 — правильное расположение устройств

Это самый важный этап:

Роутер ────────────  Человек ────────────  Узел ESP32

Расстояние между ними от 2 до 8 метров. Узел и роутер должны находиться в противоположных концах области, которую вы планируете сканировать.          

Проверьте показания RSSI в дашборде: пригодный диапазон от -40 до -60 dBm.

Шаг 8 — Автозапуск при загрузке

./install.sh              # Только сервер.
./install.sh --kiosk      # Плюс полноэкранный браузер на дисплее Pi.
./install.sh --uninstall  # Удаление.

8. Запуск

systemctl status wifisense       # Проверка работоспособности системы.
journalctl -u wifisense -f       # Логи в реальном времени.
sudo systemctl restart wifisense

Запуск вручную (сначала остановите службу):

cd pi
../.venv/bin/python -m wifisense --link serial      # USB-кабель.
../.venv/bin/python -m wifisense --link synthetic   # Без подключения оборудования.
../.venv/bin/python -m wifisense --link nrf24       # Радиомодуль на 2,4 ГГц.

9. Показания дашборда

На калибровку детекции движения уходит 6 секунд, а на детекцию дыхания 30.

О показателе качества воздуха. При его вычислении используются стандартная шкала AQI (индекс качества воздуха) от 0 до 500, стандартные категории и та же кусочно-линейная интерполяция, что и в настоящем AQI. Отличие в том, что вычисляются эти данные исключительно на основе показаний эквивалента CO2 от датчика MQ135. При расчёте нормативного AQI преобладают твёрдые микрочастицы PM2.5, которые этот датчик вообще не умеет измерять, поэтому даже в задымлённом помещении прибор может сообщать статус «Good». Так что ориентируйтесь на динамику изменения этого значения, а не на саму абсолютную цифру. Подробно этот принцип и работа самокорректирующегося базового уровня объясняются в разделе 6d файла PROJECT.TXT.

10. Как получить качественные результаты

• Плата и роутер должны находиться на противоположных сторонах сканируемого пространства. Вы фиксируете то, что происходит между ними, а не вокруг самой платы.

• Разнесите их на расстояние от 2 до 8 метров.

• Если сигнал сильнее, это не значит, что он лучше. При очень близком расположении начинает преобладать сигнал по прямому пути, и отражения просто теряются в нём. Уровень RSSI должен быть в диапазоне от -40 до -60 дБм.

• Усядьтесь где-нибудь посередине, в идеале строго по центру — но не рядом с платой.

• Для регистрации дыхания требуется неподвижность. Ориентируйтесь по показаниям MOTION, а не собственному ощущению неподвижности: система фиксирует как движение рук при использовании клавиатуры, так и шевеления на стуле. Дыхание начинает обнаруживаться чуть ниже +5 дБ. Если вы двигаетесь, дашборд просто покажет «subject moving» и никаких показаний не выведет, что вполне корректно.

• Хороший захват сигнала выглядит так: движение (Motion) ниже +5 дБ, жизненные показатели (Vitals) выше +20 дБ, частота плавно меняется на десятые доли, а уровень достоверности (confidence) выше 0,4.

• Система регистрирует движение вентиляторов, занавесок и животных. Всё это не относится к ложным положительным, так как здесь действительно происходит движение.

11. Все команды в одном месте

Выполните эти команды из каталога pi/.

Сервер

Взаимодействие с платой

Датчики окружающей среды

Проверка корректности

REST API

12. Решение типичных проблем

Более подробные объяснения даны в разделе 9 файла PROJECT.txt.

13. Готовая прошивка и образы контейнеров

Прошивка без установки PlatformIO

Каждый релиз сопровождается готовыми для прошивки бинарниками — ищите их на странице Releases. Едины комбинированный образ заливается с нулевого адреса (0x0):

pip install esptool
esptool.py --chip esp32s3 --port /dev/ttyUSB0 --baud 921600 
    write_flash 0x0 wifisense-firmware-v1.0.0.bin

Сначала проверьте, что именно скачали:

sha256sum -c SHA256SUMS

В бинарном файле содержится временный радиоключ, состоящий из одних нулей. Это абсолютно нормально для работы через USB-кабель, так как данные по нему всё равно передаются без шифрования. Но если вы используете радиоканал, вам потребуется задать собственный ключ и пересобрать проект вручную — готовый бинарный файл не может содержать в себе приватный ключ. См. раздел «Безопасность радиоканала».

Запуск сервера в контейнере

Готовые образы публикуются в GitHub Container Registry для архитектур linux/amd64 и linux/arm64:

# Только дашборд, без оборудования, по адресу http://localhost:8080
docker run --rm -p 8080:8080 ghcr.io/the-masked-bear/wifisense-pi:latest

# С платой, подключенной по USB.
docker run --rm -p 8080:8080 --device /dev/ttyUSB0 
    ghcr.io/the-masked-bear/wifisense-pi:latest python -m wifisense --link serial

Безопасность радиоканала

Данные CSI позволяют узнать, когда в комнате кто-то есть, когда люди двигаются и когда они спят. Если передавать их в открытом виде, любой человек в радиусе действия радиосигнала, имеющий такой же радиомодуль на том же канале, сможет их перехватить. Поэтому все данные, отправляемые по радиоканалу, шифруются алгоритмом AES-128 в режиме счётчика с генерацией нового случайного идентификатора сессии при каждой загрузке платы и защитой от повтора пакетов.

Сгенерируйте ключ и укажите одно и то же значение на обоих сторонах канала:

python3 -c "import secrets;print(secrets.token_hex(16))"

При несовпадении ключей счётчик cobs_errors начинает стремительно расти, в то время как показатель frames_ok застывает на нуле. Это обеспечивает конфиденциальность, но не аутентификацию: наличие CRC-16 внутри зашифрованной полезной нагрузки означает, что случайная подделка пакета сработает с вероятностью всего 1/65536. Для домашнего датчика такой защиты вполне достаточно, но полноценным кодом аутентификации сообщения (MAC) это не является.

14. Структура репозитория

PROJECT.txt              документация: вся в одном файле
requirements.txt         зависимости Python
Dockerfile               образ контейнера для сервера на Pi
install.sh               установщик автозапуска
systemd/                 шаблон службы

firmware/                прошивка ESP32-S3 (PlatformIO)
  platformio.ini         конфигурация платы. Для N15R8 обязателен режим qio_opi.
  src/config.h           настраиваемые параметры: режим, контакты, частоты, выключатели датчиков
  src/main.cpp           захват данных CSI, формирование кадров, обработка команд 
  src/radio_tx.*         передача данных по радиоканалу через nRF24/CC1101, арбитраж шины SPI 
  src/cc1101_driver.*    внутренний драйвер регистров CC1101
  src/bmp280.*           внутренний SPI-драйвер для BMP280/BME280
  src/sensors.*          DHT22, MQ135 и фоновая задача для опроса датчиков
  src/link_crypto.*      алгоритм AES-128-CTR для защиты радиоканала

pi/
  wifisense/
    protocol.py          формат передачи данных: формирование кадров методом COBS, проверка CRC-16, карта поднесущих частот
    stimulus.py          UDP-генератор запросов, задающий частоту опроса
    archive.py           долгосрочное хранилище в SQLite + отчёт о сне
    spectrum.py          мониторинг субгигагерцевого диапазона радиомодуля CC1101
    dsp/                 csi -> фильтры -> движение / дыхание -> пайплайн вычислений
    link/                последовательный порт, nrf24, cc1101, воспроизведение (replay), симулятор
    api/server.py        FastAPI, WebSocket, REST
  web/                   дашборб + страница истории. Никакой сборки и зависимостей
  tools/node.py          утилита для управления ESP32 через командную строку
  tools/validate_dsp.py  проверка корректности по заданному эталону

Документация

PROJECT.txt — это основной документ, написанный так, чтобы его было удобно читать прямо за рабочим столом вдали от терминала. В нём есть всё: полная схема разводки проводов, настройка, калибровка, поиск неисправностей и обоснование каждой константы в коде. Там же описаны исправленные баги и симптомы, которыми они проявлялись — включая случай, когда из-за нестандартного дыхания человека мощность седьмой гармоники сигнала оказалась на 2,4 дБ выше основной частоты, и алгоритм выбора пиков уверенно выдал частоту дыхания, завышенную в семь раз.

Показатели системы