nRF24L01+

nRF24L01+ — беспроводной радиомост

Радиомост на паре модулей nRF24L01+ между двумя ESP32: одна плата в роли передатчика шлёт пакеты телеметрии, вторая принимает их через собственный прикладной класс NrfLink поверх библиотеки RF24.

nRF24L01+ — беспроводной радиомост между двумя ESP32

Компонент реализует радиомост на паре модулей nRF24L01+: одна ESP32 в роли передатчика (Transmitter) шлёт пакеты телеметрии, вторая в роли приёмника (Receiver) их принимает. Обмен идёт через готовую библиотеку RF24, поверх которой компонент даёт собственный прикладной класс NrfLink — подробнее о том, зачем нужен ещё один слой поверх уже готового драйвера чипа, см. THEORY.md.

Файлы

include/NrfLink.h / src/NrfLink.cpp — драйвер.
src/main.cpp — тестовый стенд с тремя ролями (передатчик/приёмник/тест железа).
tools/link_quality_view.py — живой график качества связи (см. раздел “Визуализация” ниже).
THEORY.md — физика радиоэфира 2.4 ГГц, Auto-ACK, лимиты payload.
WIRING.md — схема подключения (SPI).
Lesson.md — методический план урока для учителя.

Подключение (кратко)

nRF24L01+	ESP32 (по умолчанию в `main.cpp`)
VCC	3.3V
GND	GND
CE	GPIO4
CSN	GPIO27
SCK	GPIO18
MISO	GPIO19
MOSI	GPIO23

Полная схема, включая важное примечание про конденсатор питания, — в WIRING.md.

Быстрый старт

Нужны две платы ESP32 с двумя модулями nRF24L01+.

Собрать схему по WIRING.md на обеих платах.
Прошить первую плату ролью передатчика: pio run -e transmitter -t upload.
Прошить вторую плату ролью приёмника: pio run -e receiver -t upload.
Открыть Serial Monitor на каждой (115200 бод) — передатчик покажет долю успешных подтверждений (AckRate), приёмник — принятые пакеты и оценочную задержку.

Если нужно просто проверить, что чип отвечает по SPI (без второй платы) — окружение по умолчанию: pio run -e test_hw -t upload.

Роли и окружения PlatformIO

Окружение	Роль	Плата
`test_hw`	Проверка присутствия чипа по SPI, без радиообмена	esp32dev
`transmitter` / `transmitter_s3` / `transmitter_c6`	Передатчик	esp32dev / esp32-s3 / esp32-c6
`receiver` / `receiver_s3` / `receiver_c6`	Приёмник	esp32dev / esp32-s3 / esp32-c6

Если прошиваете обе платы с одного компьютера, PlatformIO может перепутать порты при автоопределении — как найти и закрепить свой порт, см. комментарий в platformio.ini.

Визуализация

Serial Monitor с текстовыми числами — не самый наглядный формат для группы учеников. tools/link_quality_view.py рисует живой график:

cd tools
pip install -r requirements.txt
python3 link_quality_view.py /dev/ttyUSB0 --role tx   # для передатчика
python3 link_quality_view.py /dev/ttyUSB0 --role rx   # для приёмника

На стороне передатчика хорошо видно, как разносится плата с приёмником (закройте антенну ладонью, отойдите подальше) — AckRate падает в реальном времени. Serial Monitor прошивки на момент запуска скрипта должен быть закрыт.

API драйвера

Метод	Назначение
`begin(role, address, channel, dataRate, paLevel)`	Инициализация SPI и настройка радиоэфира под выбранную роль.
`sendTelemetry(TelemetryPacket)`	Отправка пакета (только Transmitter). `false` — Auto-ACK не получен.
`receiveTelemetry(TelemetryPacket&)`	Приём пакета, если он есть (только Receiver).
`getAckSuccessRate()`	Доля успешных подтверждений с момента `begin()`.
`isChipConnected()`	Прямая проверка присутствия чипа по SPI.
`isAlive(timeoutMs)`	Была ли недавняя протокольная активность (отправка/приём).

Известные ограничения

У nRF24L01+ нет измерения настоящей силы сигнала (RSSI) — метрика качества связи здесь построена на проценте успешных Auto-ACK, см. THEORY.md.
Оценка задержки (DelayMs) на приёмнике не учитывает рассинхронизацию часов millis() двух независимых плат — годится для сравнения “быстрее/медленнее”, не для точного измерения времени в миллисекундах.
Максимальный размер пакета — 32 байта (аппаратный лимит чипа), проверяется на этапе компиляции через static_assert в NrfLink.cpp:15-16.

Теория: как две ESP32 разговаривают по радио

1. Диапазон 2.4 ГГц: общий эфир для всех

nRF24L01+ работает в том же диапазоне частот (2.4 ГГц), что Wi-Fi и Bluetooth — это не совпадение, а стандарт: этот диапазон выделен для нелицензируемого использования почти во всём мире, поэтому в нём одновременно “разговаривают” роутеры, наушники, беспроводные мыши и наш модуль. Чтобы не мешать друг другу, устройства делят диапазон на каналы — узкие полосы частот.

Формула канала у nRF24L01+ простая: частота = 2400 + номер_канала МГц. В этом компоненте выбран канал 110 (main.cpp:13), то есть частота 2510 МГц — она находится выше типового диапазона Wi-Fi (2412-2472 МГц, каналы 1-13) и Bluetooth, поэтому меньше шансов, что домашний роутер или чей-то телефон будут “перебивать” наш сигнал.

2. Auto-ACK: как понять, что пакет дошёл

В радиоэфире нет гарантии, что отправленный пакет долетел — сигнал может потеряться из-за помех, расстояния или препятствия. Библиотека RF24 использует аппаратный механизм Auto-ACK (automatic acknowledgement): после каждого отправленного пакета приёмник автоматически, без участия кода, отправляет короткое подтверждение “получил”. Если передатчик за отведённое время не дождался этого подтверждения — он считает пакет потерянным.

Именно это возвращает radio.write() внутри RF24, и именно на этом построен весь смысл NrfLink::sendTelemetry() (NrfLink.cpp:29-37): true — ACK получен, пакет точно дошёл, false — ACK не пришёл, пакет считается потерянным (или потерялось само подтверждение — со стороны передатчика это неотличимо, и это нормальное ограничение протокола).

3. Почему “качество связи” — это не RSSI

У Wi-Fi и Bluetooth чипов обычно есть прямое измерение силы принятого сигнала (RSSI, Received Signal Strength Indicator) — число в дБм, которое можно прочитать из регистра. У nRF24L01+ такого измерения нет.

Поэтому в этом компоненте “качество связи” — это не сила сигнала, а доля успешных подтверждений (Auto-ACK success rate):

ackRate = packetsAcked / packetsSent

реализовано в NrfLink::getAckSuccessRate(). Это косвенная, но честная метрика: чем хуже физическая связь (дальше расстояние, больше помех, экранирована антенна), тем чаще Auto-ACK не успевает дойти, и тем ниже становится ackRate. Это не “сила сигнала в дБм”, а “процент успешных попыток” — этот компонент нигде не выдаёт одно за другое.

4. Payload: сколько данных влезает в один пакет

nRF24L01+ аппаратно ограничивает размер одного пакета данных (payload) 32 байтами — это физическое ограничение чипа, а не настройка, которую можно изменить в коде. TelemetryPacket (NrfLink.h:16-20) занимает всего 13 байт (4+4+4 плюс выравнивание), что оставляет запас для будущих компонентов, которым потребуется передавать больше полей. Соответствие лимиту проверяется не “на глаз”, а автоматически на этапе компиляции:

static_assert(sizeof(TelemetryPacket) <= NrfLink::kMaxPayloadBytes, ...);

(NrfLink.cpp:15-16) — если кто-то добавит в структуру слишком много полей, прошивка просто не соберётся, а не будет загадочно “терять” часть данных на реальном железе.

5. Скорость эфира и дальность — компромисс

RADIO_SPEED можно выставить в 250 kbps, 1 Mbps или 2 Mbps. Более низкая скорость означает, что каждый бит “звучит” в эфире дольше — приёмнику легче отличить сигнал от шума, поэтому дальность и устойчивость к помехам выше. Более высокая скорость — обратный компромисс: меньше задержка, но короче надёжная дальность. В этом компоненте выбрана RF24_250KBPS (main.cpp:14) — приоритет отдан устойчивости связи, а не скорости передачи, что разумно для учебного демонстрационного проекта.

6. Почему у драйвера есть свой класс поверх RF24

Библиотека RF24 уже сама по себе полноценный низкоуровневый драйвер чипа — она умеет говорить с ним по SPI, читать/писать регистры, включать Auto-ACK. Класс NrfLink не переписывает эту работу заново — он не наследуется от RF24 и не оборачивает каждый её метод один в один. Вместо этого он добавляет прикладной уровень поверх готового транспорта: типизированный TelemetryPacket вместо голых байт, счётчики packetsSent/packetsAcked, единый isAlive() для обеих ролей. Это тот же принцип, что у I2C-компонентов этого репозитория, где Wire — транспорт, а класс-драйвер — прикладная логика.

Подключение nRF24L01+

Схема

     ESP32                    nRF24L01+
  ┌───────────┐             ┌─────────────┐
  │       3V3 ├─────────────┤ VCC         │
  │       GND ├─────────────┤ GND         │
  │     GPIO4 ├─────────────┤ CE          │
  │    GPIO27 ├─────────────┤ CSN         │
  │    GPIO18 ├─────────────┤ SCK         │
  │    GPIO19 ├─────────────┤ MISO        │
  │    GPIO23 ├─────────────┤ MOSI        │
  └───────────┘             └─────────────┘

Схема одинакова для обеих плат (передатчик и приёмник) — разница только в том, какая роль зашита в прошивке (ROLE_TRANSMITTER/ROLE_RECEIVER, см. README.md).

Таблица пинов

nRF24L01+	ESP32 (esp32dev)	Назначение
VCC	3V3	Питание — строго 3.3V, 5V выведет чип из строя
GND	GND	Общий провод
CE	GPIO4	Chip Enable — переключает чип между режимами приёма/передачи
CSN	GPIO27	SPI Chip Select
SCK	GPIO18	SPI Clock
MISO	GPIO19	SPI Master In / Slave Out
MOSI	GPIO23	SPI Master Out / Slave In

Пины NRF_CE_PIN/NRF_CSN_PIN заданы в main.cpp:5-6 — при необходимости смените их под свою распиновку. SPI-пины (SCK/MISO/MOSI) используются автоматически как стандартный аппаратный SPI платы esp32dev.

Конденсатор на питании — не опционально

nRF24L01+ (особенно версии с усилителем PA/LNA — большая антенна вместо маленькой печатной) потребляет резкий пик тока в момент включения радиопередатчика. Многие платы ESP32 не могут выдать этот пик стабильно через встроенный стабилизатор 3.3V, из-за чего модуль либо не отвечает по SPI, либо ESP32 неожиданно перезагружается в момент передачи.

Решение: поставить электролитический конденсатор ~470 мкФ между VCC и GND модуля, максимально близко к самому nRF24L01+ (не на плате ESP32, а прямо на проводах питания модуля). Это сглаживает пик тока и почти всегда решает проблему “чип не найден”/случайных перезагрузок при первом включении.

Типичные проблемы

Симптом	Вероятная причина	Решение
`[!] Чип не найден` при старте	Обрыв на SPI-линии или недостаточное питание	Проверить пайку SCK/MISO/MOSI, добавить конденсатор (см. выше)
`AckRate` всегда 0%	Не совпадает адрес трубы или канал на двух платах	Сверить `RADIO_ADDRESS`/`RADIO_CHANNEL` в `main.cpp` на обеих прошивках
Случайные перезагрузки при передаче	Просадка питания при включении PA	Конденсатор 470 мкФ, короткие толстые провода питания
`AckRate` плавает от 100% до 0% на близком расстоянии	Помехи в диапазоне 2.4 ГГц (Wi-Fi рядом)	Сменить `RADIO_CHANNEL` дальше от каналов Wi-Fi, см. THEORY.md

План занятия: «Невидимый провод» — nRF24L01+

Формат: один урок 40-45 минут, работа в парах (каждой паре нужны две платы ESP32 с двумя модулями nRF24L01+). Аудитория — 14-17 лет, базовое знакомство с Arduino/C++ и ESP32 приветствуется, но не обязательно.

Цель занятия: собрать работающий беспроводной канал связи между двумя контроллерами, увидеть вживую, как ухудшается радиосвязь при удалении и помехах, и разобраться, почему “качество связи” здесь — это не то же самое, что шкала сигнала на телефоне.

Блок I. Зачем радио, если есть провода (5-7 минут)

Вопрос классу: «Почему пульт от телевизора работает без проводов, а зарядка телефона — нет?» — подвести к разнице между передачей энергии (нужен провод или контакт) и передачей информации (можно по радиоволнам).

nRF24L01+ — маленький радиочип, который умеет и слать, и принимать данные на частоте 2.4 ГГц — том же диапазоне, где работает Wi-Fi.
Показать WIRING.md: всего 5 проводов управления (плюс питание) — чип разговаривает с ESP32 по протоколу SPI.

Блок II. Роли: кто говорит, кто слушает (7-10 минут)

Разбить класс на пары. У каждой пары — две платы: одна станет передатчиком, другая приёмником.
Показать, что это не два разных устройства, а одна и та же прошивка с разным флагом сборки (ROLE_TRANSMITTER/ROLE_RECEIVER, platformio.ini) — обсудить, зачем так сделано (один код, меньше дублирования, легче поддерживать).
Прошить обе платы: pio run -e transmitter -t upload на одну, pio run -e receiver -t upload на другую.
Открыть Serial Monitor на обеих — увидеть первые пакеты.

Блок III. Auto-ACK и честная метрика качества (10-12 минут)

Обсудить: как передатчик вообще узнаёт, что сообщение дошло? (Аналогия: ты крикнул другу через двор — откуда ты знаешь, что он услышал, если он не крикнул в ответ?) Ввести понятие Auto-ACK — подробнее в THEORY.md, раздел 2.
Показать строку у передатчика: Seq:.., AckRate:.., Sent:.., Acked:...
Ключевой момент: у этого чипа нет измерения силы сигнала (RSSI), как у Wi-Fi. AckRate — это единственная доступная метрика, и она косвенная — см. THEORY.md, раздел 3.

Блок IV. Практика: разносим платы (10-15 минут)

Запустить визуализацию на передатчике:

cd tools && pip install -r requirements.txt
python3 link_quality_view.py <порт> --role tx

Задание парам: постепенно увеличивать расстояние между платами (выйти в коридор, на другой этаж) и наблюдать, как падает AckRate на графике.
Затем — закрыть антенну передатчика или приёмника ладонью/металлическим предметом на близком расстоянии. Обсудить, почему металл экранирует сигнал сильнее, чем просто расстояние.
Кто первым потеряет связь полностью (AckRate → 0%) на минимальной мощности (RF24_PA_MIN, уже стоит по умолчанию в main.cpp)?

Вопросы для обсуждения

Почему нельзя просто сказать “пакет отправлен успешно” сразу после radio.write(), не дожидаясь ACK? Потому что сам факт отправки ничего не говорит о том, дошёл ли сигнал — в радиоэфире потери обычные. Только подтверждение от приёмника даёт уверенность, что данные реально получены.
Почему AckRate — не то же самое, что “сила сигнала” на экране телефона? Потому что это не прямое измерение мощности принятого сигнала (RSSI), а статистика успешности протокола подтверждений — косвенная метрика, которая коррелирует с качеством связи, но измеряет другое.
Почему у пакета телеметрии ограничение в 32 байта? Это аппаратный лимит самого чипа nRF24L01+, а не выбор программиста — см. THEORY.md, раздел 4.
Почему в коде есть отдельный класс NrfLink, если библиотека RF24 уже умеет отправлять и принимать данные? RF24 — это транспорт (говорит с чипом по SPI), а NrfLink — прикладной уровень (типизированные пакеты, статистика, единый isAlive()). Это тот же принцип разделения, что в компонентах с I2C-датчиками.

Материалы для раздачи

Схема подключения из WIRING.md.
Таблица типичных проблем оттуда же — полезна во время сборки.
Готовый шаблон кода (src/main.cpp) — ученики фокусируются на эксперименте с дальностью и помехами, а не на написании протокола с нуля.