Skip to content

About

ESPHome BLE-gateway для радон-детекторов Quarta-Rad / Radex (MR107ion и линейка): READ-poll GATT, ESP32-S3 + Home Assistant + Web UI v3. Open source, MIT.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

103 Commits

Folders and files

Repository files navigation

Radex MR107ion → ESP32 → Home Assistant / Web UI

Прошивка ESP32-платы, превращающая её в постоянный BLE-шлюз между радон-детектором Radex MR107ion (Quarta-Rad, quartarad.com) и локальной сетью. Прибор перестаёт зависеть от приложения RadexM на телефоне — пока ESP32 стоит у розетки, данные читаются круглосуточно и без облака изготовителя.

Radex MR107ion ─BLE READ-poll─► ESP32 ─Web UI─► браузер
                                  │
                                  ├─► Home Assistant (ESPHome API либо MQTT)
                                  │
                                  └─► Народмон (инфраструктура есть, ВЫКЛ по умолчанию)

Полная база знаний — в SKILL.md. Полная BLE-расшифровка — в references/mr107ion.md.


Две ветки прошивки

Репозиторий содержит две независимые реализации одного шлюза. Обе действующие, ни одна не отменяет другую — они рассчитаны на разные задачи.

Ветка ESPHome Ветка ESP-IDF
Исходники firmware/*.yaml firmware-idf/
Релизы v0.1.0 – v0.5.0 v1.0.0 – v1.14.1
Канал связи с прибором BLE BLE и USB-кабель (с v1.13.0), выбор автоматически — раздел «Подключение прибора по USB»
Реализация конфигурация YAML поверх ESPHome C поверх ESP-IDF, без прослойки
Платы пять конфигураций: ESP32-S3 (в том числе N16R8) и классическая ESP32-DevKitC — матрица в KNOWN_ISSUES.md только ESP32-S3-DevKitC-1 N16R8 (16 МБ флеша, 8 МБ octal PSRAM — заданы в sdkconfig.defaults)
Home Assistant нативный протокол ESPHome, устройство обнаруживается автоматически MQTT с автообнаружением
Оценка соответствия НРБ-99/2009 нет есть: вкладка «Соответствие нормативу», рациональный критерий по методике Цапалова
История показаний за время с последней перезагрузки на флеш-памяти платы, раздел 2 МБ, выгрузка в CSV
Переподключение BLE после разрыва доступными средствами конфигурации ESPHome: отключение авто-discovery Bluedroid (v0.5.0) устранение причины в конфигурации Bluedroid: набор возможностей BLE 5.0 выключен (INC-BLE50-001)
Защита веб-интерфейса Basic Auth нет, страница открыта всем в сети платы
Сборка из исходников pip install esphome Docker-образ espressif/idf:v6.1

Какую выбрать. Нужен Home Assistant по нативному протоколу, плата не N16R8 или предпочтительна правка конфигурации вместо C — ветка ESPHome, дальнейшие разделы до «Альтернативная архитектура». Нужна оценка соответствия нормативу, история за месяцы или устойчивое переподключение к прибору — ветка ESP-IDF, раздел «Альтернативная архитектура: чистый ESP-IDF». Порядок установки обеих веток — в INSTALL.md.


С чего начать (ветка ESPHome)

Всё дальнейшее зависит от того, какая у вас плата. Найдите свою строку.

Плата ESP32-S3-DevKitC-1 N16R8

Ваша плата Что делать
ESP32-S3-DevKitC-1 N16R8 — 16 МБ Flash, 8 МБ PSRAM (на снимке справа; маркировка написана прямо на модуле) Собирать ничего не нужно. Возьмите готовый образ firmware.factory.bin из релиза v0.4.2 и залейте прошивальщиком. Порядок — сразу ниже
Другая плата на ESP32-S3 (4 или 8 МБ, без PSRAM) Готовый образ не подойдёт — он рассчитан на 16 МБ флеша. Соберите firmware/radex_gateway_s3.yaml сами, см. INSTALL.md
Классическая ESP32-DevKitC на WROOM-32 Соберите firmware/radex_gateway.yaml, см. INSTALL.md

Где купить подходящую плату, если её ещё нет: например, Ozon (ищите в названии именно «N16R8» — это и есть 16 МБ флеша плюс 8 МБ PSRAM).

Ссылка на релиз указывает конкретный тег. Последний по времени релиз репозитория — v1.14.1, и это ветка ESP-IDF: ассет firmware.factory.bin в нём тоже есть (как и в v1.11.1 и v1.12.0), но это полный образ ESP-IDF-ветки, а не ESPHome; рядом лежит radex-gw-idf.bin (только приложение). Имя ассета одно и то же, поэтому берите именно v0.4.2. Образ ESPHome-ветки берётся из v0.4.2 (последний стабильный) либо из предварительного v0.5.0, где исправлено автообнаружение прибора Bluedroid.

Быстрый старт на плате N16R8 — от коробки до графика (ESPHome)

  1. Залейте образ. Прошивальщик сам скачает firmware.factory.bin из релиза (v0.4.2 — см. выше). Плате нужен один кабель USB-C. На плате два разъёма, и порт в системе появляется только от одного из них — если плата не определилась, переткните кабель во второй (подробнее — в INSTALL.md).
  2. Подключитесь к плате по Wi-Fi. Своей сети она пока не знает, поэтому поднимает собственную точку доступа radex-gw-s3 Fallback, пароль radex123. Подключитесь к ней с телефона или ноутбука.
  3. Укажите домашнюю сеть. Откроется страница настройки (если не открылась сама — зайдите на http://192.168.4.1). Выберите свою сеть 2,4 ГГц, введите её пароль. Плата перезагрузится и уйдёт в вашу сеть — её точка доступа больше не появится.
  4. Откройте веб-страницу платы — это и есть весь интерфейс шлюза: → http://radex-gw-s3.local/ Не открывается — значит в вашей сети не работает mDNS. Тогда посмотрите IP-адрес платы в списке клиентов роутера и откройте http://<этот-адрес>/.
  5. Введите логин и пароль. Для готового образа из релиза это radex и radex. Если собирали прошивку сами — те значения, которые вы вписали в свой secrets.yaml в ключи web_server_auth_user и web_server_auth_pass.
  6. Включите Radex MR107ion рядом с платой. Адрес прибора вводить не нужно — плата находит его в эфире сама. В группе «Сервис» появится поле «Найденный прибор Radex» с адресом, в группе «Данные» — радон, температура и влажность. Если приборов рядом несколько и нужен конкретный, впишите его адрес в поле «MAC Radex (AA:BB:CC:DD:EE:FF)» и нажмите «Применить MAC и перезагрузить».

Выгрузка на Народмон выключена и включается только вручную.

Логин и пароль готового образа одинаковы у всех, кто его залил: образ общий, и они лежат открыто в firmware/secrets.public.yaml. Это не оплошность, а плата за то, что образ не нужно пересобирать. Кому нужны свои значения — вписывает их в secrets.yaml и собирает прошивку сам; заодно можно сразу указать там домашнюю сеть, и тогда шаги 2–3 не понадобятся вовсе.


⚠ Перед использованием

Шлюз подключается к прибору Radex MR107ion по Bluetooth Low Energy и только читает данные (BLE READ-poll по ATT-handle) — команд записи на прибор не шлёт, накопленные показания и настройки прибора не меняет. Риск для самого прибора минимален. Прошивка/OTA относится к плате ESP32; прерывание прошивки может потребовать повторной заливки платы через USB.

Отказ от ответственности

Прошивка предоставляется «как есть», без каких-либо гарантий. Автор не несёт ответственности за любой прямой или косвенный ущерб: потерю данных, неработоспособность прибора или платы, иные последствия использования. Используя прошивку, вы принимаете эти условия и действуете на свой страх и риск.


Какая прошивка для какой платы (ветка ESPHome)

В ветке ESPHome — пять YAML на одной кодовой базе. Различия: целевой ESP32-модуль, сценарий применения, Web UI layout. Ветка ESP-IDF в эту таблицу не входит: у неё одна целевая плата и отдельный порядок установки, см. раздел «Альтернативная архитектура».

Прошивка Целевая плата Что особенного Когда выбирать
firmware/radex_gateway_s3_n16r8.yaml (рекомендуемая, 2026-08-20) ESP32-S3-DevKitC-1 N16R8 (16 МБ Flash, 8 МБ PSRAM octal), framework=arduino Профиль платы задан явно: flash_size: 16MB + блок psram: {mode: octal, speed: 80MHz}. MAC прибора в прошивку не зашит — плата сама ищет Radex в эфире по имени (начинается на MR107 или Radex, регистр не важен) или по UUID сервиса FE651700-… (принимаются оба варианта последнего байта — …8AAA и …8AAB) и запоминает найденный адрес вместе с типом адреса в NVS. Ручной ввод MAC через Web UI сохранён и имеет приоритет. В Web UI добавлены поле «Найденный прибор Radex», кнопка «Забыть прибор и искать заново», датчики «Свободная память» и «Свободная PSRAM». api: без ключа шифрования (сборка публичная), Web UI закрыт Basic Auth Новая установка на плату N16R8. Единственный вариант, который можно поставить готовым бинарником без пересборки — в том числе через прошивальщик (см. ниже)
firmware/radex_gateway_s3.yaml (актуальная, 2026-06-17) ESP32-S3-DevKitC-1 (board: esp32-s3-devkitc-1, framework=arduino) BLE-клиент к 1×MR107ion, Web Server v3 + Basic Auth + sorting_groups (Data / Service), ESPHome API encryption, watchdog WiFi, Народмон-инфраструктура (switch ALWAYS_OFF, 4 протокола), USB-C, 4 параллельных BLE-слота Готовый production-шлюз для одного MR107ion, если вы собираете прошивку сами. Два ограничения: MAC прибора нужен уже на этапе компиляции (ble_client.mac_address — обязательное поле схемы), а профиль памяти платы не задан — ESPHome берёт дефолтные 4 МБ флеша и PSRAM не включает
firmware/radex_gateway_s3_baseline.yaml ESP32-S3-DevKitC-1 Чистый baseline без сенсоров (BLE/API/Web UI без логики опроса) — для проверки железа и OTA Первая прошивка новой платы S3 (smoke-тест перед накатом полной прошивки)
firmware/radex_gateway.yaml ESP32-DevKitC (WROOM-32 / WROVER), framework=esp-idf v0.3.0-step8 (последний шаг — bluetooth_proxy закомментирован), BLE READ-poll 4 handle round-robin, две таблицы Web UI v3 («Данные» / «Сервис»), web_server.log: false против json:111 Старая плата ESP32-DevKitC, ESP-IDF
firmware/radex_gateway_v2.yaml ESP32-DevKitC Альтернатива на Web Server v2 (одна плоская таблица с тематическими префиксами 1.x / 2.x / 3.x / 4.x) Нужен «всё разом» без переключения групп

Все прошивки слушают тот же протокол MR107ion (custom service FE651Y00-…, READ-poll ATT-handle через бэкбон FE651700-…), различаются только UI / стек / HARD-правила.

Установка без пересборки — через прошивальщик

Для radex_gateway_s3_n16r8.yaml в релизах v0.4.2 и v0.5.0 лежит готовый образ firmware.factory.bin (в релизах ESP-IDF-ветки v1.x ассет с тем же именем — другая прошивка, см. выше). Его умеет заливать прошивальщик — он сам скачивает ассет из релиза и пишет его на плату. Ни Python, ни ESPHome, ни правки YAML для этого не нужны.

Дальше по шагам:

  1. Залить образ на плату.
  2. Плата ищет сеть radex-gw-setup. Такой сети не существует — это сделано намеренно, поэтому плата поднимает свою точку доступа radex-gw-s3 Fallback с паролем radex123.
  3. Подключиться к этой точке с телефона или ноутбука, в captive portal выбрать свою Wi-Fi 2.4 ГГц и ввести её пароль. Плата перезагрузится и уйдёт в вашу сеть.
  4. Открыть http://radex-gw-s3.local/, логин radex, пароль radex.
  5. MAC прибора вводить не нужно: плата находит Radex в эфире сама и запоминает его. В группе «Сервис» появится поле «Найденный прибор Radex» с адресом, в группе «Данные» — радон, температура и влажность.

На проверке прошивка нашла прибор Radex MR107ion в течение минуты после старта и стала отдавать показания. Адрес прибора и тип адреса сохраняются в NVS, чтобы после перезагрузки не ждать эфира. Сам тип адреса ESPHome восстанавливает и без этого — при обнаружении прибора в рекламе (parse_device()), — так что хранение типа здесь подстраховка, а не обязательное условие работы.

Пароли из этого списка опубликованы и потому секретом не являются — они лежат в firmware/secrets.public.yaml, с которым собран публичный бинарник. Пока плата стоит в режиме настройки, к её точке доступа может подключиться любой, кто рядом. Тому, кого это не устраивает, нужно собрать прошивку самому: скопировать secrets.public.yaml в secrets.yaml, вписать свои значения ap_password, ota_password, web_server_auth_user / web_server_auth_pass и пересобрать. Если в secrets.yaml сразу указать свою домашнюю сеть, плата подключится к ней при первом старте и точку доступа поднимать не станет.


Альтернативная архитектура: чистый ESP-IDF

Пять прошивок выше собраны на ESPHome. В firmware-idf/ лежит независимая ветка того же шлюза — написанная на C напрямую поверх ESP-IDF, без ESPHome как прослойки. Причина перехода — контроль над BLE-стеком: часть поведения контроллера (выбор LEGACY- или EXTENDED-варианта команды соединения, esp_ble_gattc_open()) ESPHome не экспонирует в конфигурацию, а именно в этом месте лежал корневой дефект переподключения (разбор — в KNOWN_ISSUES.md, INC-BLE50-001). На ESP-IDF sdkconfig управляет фичесетом Bluedroid напрямую, и дефект устраняется отключением набора функций BLE 5.0, а не обходом симптома.

Отличия от ESPHome-веток, помимо языка реализации:

  • Рациональный критерий оценки соответствия по НРБ-99/2009 — отдельная вкладка Web UI «Соответствие нормативу»: выбор планки (200 Бк/м³ для новых и реконструированных зданий, 400 Бк/м³ для эксплуатируемых), учёт временной и инструментальной составляющих неопределённости, заключение о соответствии. Заключение и применённая планка показываются также на вкладке «Показания». Методика публикуется вместе с прошивкой: references/tsapalov-metodika-2025.md.
  • История показаний на флеш-памяти платы — раздел storage 2 МБ в firmware-idf/partitions.csv, уплотнение старых записей по возрасту, выгрузка в CSV (/api/export.csv), отдельный файл на каждый начатый замер.
  • Резервная линия защиты BLE, независимая от корневого исправления: восемь подряд неудачных попыток открытия соединения приводят к программной перезагрузке (RADEX_AUTO_RESTART_AFTER_FAILS в main/ble_radex.c). За 37 часов прогона после исправления конфигурации механизм не сработал ни разу.
  • Кнопка программной перезагрузки в Web UI (/api/reboot) — отдельно от этого счётчика, по решению оператора платы.
  • Шесть вкладок вместо одной плоской таблицы («Результаты измерений», «Соответствие нормативу», «Метод», «Интеграции», «Графики», «Системные»), полноэкранный график, адаптация раскладки под мобильный экран.
  • Доверительный интервал расчётной среднегодовой ОА радона на графике — полоса c(t)·(1 ± √(UV(t)² + U_D²)), сужающаяся по мере набора длительности: момент, когда её верхняя граница опускается ниже норматива, и есть «соответствует». Различаются две величины с общим центром: измеренная средняя ОА радона за тест и расчётная среднегодовая, у которой есть неопределённость по формуле критерия.
  • Сохранение замера под своим именем — кнопка «Сохранить замер» снимает идущий замер в отдельный файл на флеш и подписывает его; список сохранённых замеров с именами — на вкладке «Графики», там же заключение по любому из них (/api/assess?start=<epoch>) отдельно от текущего замера.
  • Публикация в Home Assistant — по MQTT с автообнаружением (homeassistant/sensor/…/config), а не по нативному протоколу ESPHome.

Веб-интерфейс не закрыт паролем. Basic Auth, который есть в ESPHome-ветке, здесь не реализован: страница и все маршруты /api/* доступны любому в той же сети. Пароль Wi-Fi хранится в NVS открытым текстом — шифрование флеша по умолчанию выключено, поскольку включается необратимо (прожиг eFuse).

Готовый образ для платы ESP32-S3-DevKitC-1 N16R8 — в релизе v1.14.1: firmware.factory.bin (полный образ, заливать на 0x0) и radex-gw-idf.bin (только приложение, заливать на 0x20000). Контроль целостности — sha256sums.txt в том же релизе. Пошаговый порядок заливки — в INSTALL.md, раздел «Путь 3».

Плату, которая уже настроена, обновлять только приложением (0x20000). Полный образ — непрерывный от 0x0, и в его диапазон попадает раздел nvs: заливка на 0x0 стирает сохранённую сеть, привязку прибора и параметры критерия, после чего плата поднимает точку RadexGW-Setup и настройку приходится проходить заново. Раздел с историей измерений (storage, 0x620000) лежит за концом образа и не затрагивается ни в том, ни в другом случае.

Внешний вид интерфейса можно посмотреть без прибора и без платы — демонстрационная копия на синтетических данных: https://vibeengineering-llc.github.io/demo-web-pages/radex-gateway-ui/app.html.

Сборка — через Docker-образ espressif/idf:v6.1 (среда фиксирована версией, не системной установкой ESP-IDF):

docker run --rm -v "${PWD}/firmware-idf:/project" -w /project \
  espressif/idf:v6.1 bash /project/build.sh

На Windows — обёртка firmware-idf/build.ps1 (решает проблему кириллицы в пути проекта, которую Git Bash подменяет). Скрипт build.sh при отсутствии sdkconfig сам выполняет idf.py set-target; цель берётся из переменной окружения RADEX_TARGET, по умолчанию esp32s3. Вписывать свою сеть в исходники не обязательно — она задаётся через страницу настройки при первом запуске. Файл firmware-idf/main/secrets_local.h.example нужен только тому, кто не хочет проходить эту страницу после каждой перепрошивки: копия под именем secrets_local.h в репозиторий не попадает (.gitignore), а сеть из неё записывается в NVS только если та ещё не задана.

Эта ветка не заменяет пять ESPHome-прошивок выше. Они остаются рекомендованным путём там, где нужна интеграция с Home Assistant по нативному протоколу ESPHome, закрытый паролем веб-интерфейс либо плата, отличная от N16R8. Требования к железу у ESP-IDF-ветки жёстче: sdkconfig.defaults фиксирует esp32s3, 16 МБ флеша и octal PSRAM, причём PSRAM обязателен — кольцевой буфер лога занимает в нём 384 КБ, и запасного размещения в оперативной памяти не предусмотрено.

Подключение прибора по USB (ESP-IDF, с v1.13.0)

С v1.13.0 ESP-IDF-ветка умеет читать MR107ion не только по BLE, но и по кабелю USB: плата работает USB-хостом, прибор подключается к ней как устройство CDC-ACM (VID:PID ABBA:A204, 230400 бод). Кабель снимает все беды радиоканала — разрывы, очередь команд, дележ эфира с Wi-Fi, — ценой того, что прибор перестаёт быть автономным и привязан проводом к плате. Для стационарного мониторинга это приемлемо, для носимого прибора — нет, поэтому BLE остаётся в той же прошивке.

Схема. На ESP32-S3-DevKitC-1 N16R8 два разъёма USB-C:

  ПК или блок питания 5 В ──USB──► [ UART ]  ESP32-S3-DevKitC-1 N16R8  [ USB (OTG) ] ◄──USB── Radex MR107ion
                                   питание, прошивка, лог                прибор (кабель С ЛИНИЯМИ ДАННЫХ)
  • Разъём UART — питание платы, прошивка и лог, как и раньше.
  • Разъём USB (OTG) — прибор. Кабель нужен с линиями данных: «зарядный» кабель даёт в Windows «неопознанное USB-устройство», на плате — просто ничего.

Перемычка USB-OTG. Для питания прибора по USB на плате нужно замкнуть (запаять) перемычку USB-OTG — по опыту проекта atomspectra-waterfall-esp32, подробности и фото там (INSTALL.md). Перемычка есть на распространённых клонах ESP32-S3-DevKitC-1 (N16R8); на оригинальной плате Espressif такой перемычки нет, питание OTG-разъёма зависит от исполнения платы.

Перемычки на плате — замкните USB-OTG

Фото — из соседнего проекта того же владельца, atomspectra-waterfall-esp32 (INSTALL.md, images/solder-jumper.webp, лицензия MIT).

Как выбирается канал. Ничего переключать не нужно — плата решает сама, на лету и без перезагрузки:

Ситуация Канал Что происходит с BLE
Прибор определился на USB USB На паузе: стек поднят, но не ищет и не подключается
USB нет (или выдернули кабель — через 10 с) BLE, как в v1.12.0 Поиск, выбор прибора по MAC, опрос
Bluetooth выключен в настройках и USB нет нет Не запускается

Задержка 10 с при пропаже USB нужна, чтобы кратковременное переоткрытие порта не дёргало BLE туда-обратно. Активный канал виден на странице — приставкой «USB · » / «BLE · » к строке статуса опроса — и в GET /api/data полем transport (usb | ble | none).

Выключатель Bluetooth — флажок «Bluetooth (когда прибор не на USB)» в карточке «Прибор (MAC)» на вкладке «Системные» (API: POST /api/bt, тело 1 / 0; состояние — поле bt_enabled в /api/system). Хранится в памяти платы и переживает перезагрузку, по умолчанию включён. Выключенный Bluetooth означает «только USB»: BLE-клиент не запускается вовсе.

Что читается по USB. Текущие показания (раз в 10 минут, как по BLE): ОА последнего цикла, средняя сессии прибора и её СКО, температура, влажность. Журнал прибора — кнопкой «Прочитать журнал с прибора», последние 64 записи, в том числе через границу сессий прибора (новая сессия начинается, например, после установки часов в RadexDC); сохранение в историю — как для BLE-журнала. Колонка «ОА» журнала — скользящее среднее прибора (как в BLE-журнале; в v1.13.0 по USB по ошибке отдавалась сырая ОА, исправлено в v1.13.1). По BLE журнал читает только сессию 0 прибора (см. KNOWN_ISSUES.md).

Загрузка всего архива прибора по USB (с v1.14.1). Журнал выше берёт 64 записи — это предел шлюза, а не прибора. Кнопка «Загрузить весь архив (USB)» на вкладке «Системные» (под журналом, видна только при канале USB) читает архив целиком, сквозь все сессии, и вставляет его в историю платы по времени (в конец, если записи не старше хвоста, иначе слиянием): предпросмотр (сколько записей в приборе, в скольких сессиях, сколько поместится в историю) → подтверждение → чтение с прогрессом и оценкой времени → сверка → запись. Кнопка «Отмена» доступна на время чтения. Рядом — отдельная кнопка «Заменить участок архивом» (см. ниже). По BLE прежний журнал на 64 записи, кнопок нет.

  • Как читается. Порядок RadexDC: 0x0C04 → 0x0C0D (заголовок, один раз за задание) → один 0x0C05 на последнюю запись → страницы 0x0C0E по 22 записи; паузы как у RadexDC (150 мс после 0x0C05, 100 мс между страницами), при чужой позиции первой страницы — один повтор 0x0C05. Каждая запись сверяется с ожидаемой парой (сессия, номер); пропуск, дубль, чужая сессия или нарушенный порядок прерывают загрузку. Новых запросов к прибору нет: загрузка использует пять запросов из белого списка (в нём шесть) — 0x0BC2 (показания и часы прибора: шлюз делает его в начале каждого чтения заголовка), 0x0C04, 0x0C0D, 0x0C05, 0x0C0E. Веб-сервер не блокируется: чтение идёт в задаче USB; обычный опрос показаний на это время приостановлен.
  • Ничего не пишется, пока архив не прочитан и проверен целиком. Записи копятся в PSRAM платы (16 байт на запись, до 1 МБ на предельные 65 536 записей; массив строк для истории — до 24 байт на запись; второй такой массив — строки для файла идущего замера, ещё до 24 байт на запись (radex_archive_job.c, trows); строки истории для сверки — 16 байт на строку окна и 1 байт «занятости»; при слиянии в PSRAM читается ещё весь файл и индекс его строк — по расчёту в предельном случае пик до 6–7 МБ из 8 МБ, не измерен; нехватка памяти даёт отказ mem до записи, а для файла замера — ошибку test), потом сверяются с историей, и только затем пишутся. Отмена, обрыв USB, нарушенный порядок, нехватка места или памяти на этапе чтения и сверки оставляют историю нетронутой. Пока задание правит файл истории, живые точки не теряются: плата держит их в очереди на 8 точек и дописывает после (точка приходит раз в цикл прибора, 10–60 минут; при бо́льшем числе точек за время задания лишние отбрасываются, в лог пишется предупреждение, а число потерянных точек доступно как счётчик radon_stats_hold_lost() и печатается в лог в конце задания).
  • Что попадает в историю. Колонка radon — сырая ОА цикла (запись архива, поле @8): так же, как у живых точек (radon_stats_add(..., radon_last, radon_avg, ...) в main.c). Колонка radon_avg у живых точек и у записей архива — РАЗНЫЕ величины. У живой точки это средняя сессии прибора (параметр 0x0040, c->avg в radex_usb.c; radex_ekosf.c), у записи архива — скользящее среднее записи (@12, radex_archive.c), у строки импорта — копия radon (radon_stats.c, разбор строки импорта). Расчёты (оценка, методика, график) берут только radon; radon_avg хранится, усредняется при уплотнении и уходит в экспорт CSV, но ничего не определяет. Бегущее среднее сессии по потоку архива не считается: соответствие «средняя сессии прибора = среднее ОА цикла с начала сессии» на приборе не проверялось, а выдумывать значение нельзя. Журнал на 64 записи (кнопка «Сохранить N точек в историю»): radon = сырая ОА записи журнала (поле unk_f10, USB @8; BLE-запись — та же, сдвинутая на 2 байта), radon_avg = oa (скользящее); если сырая не годна (не число, отрицательная, больше 1e6), radon = oa. Температура вне −60…90 °C и влажность вне 0…100 % записываются как «нет данных»; ОА выше 1e6 или не число — запись отбрасывается (bad). Строки журнала пишутся по ВОЗРАСТАНИЮ времени, в конец истории или слиянием, и в файл идущего замера; POST /api/journal/save во время загрузки архива отвечает 409.
  • Порядок строк в истории — инвариант. Файл radon.csv (и файл идущего замера) остаётся строго неубывающим по времени. Если все новые строки не старше хвоста файла и файл в порядке, они дописываются в конец (пачками по 64 строки); иначе плата сливает их с файлом по времени в временный файл mrg_*.csv и заменяет им исходный только после того, как новый записан полностью и его размер сошёлся (main/hist_merge.c, хост-тест test/host/test_hist_merge.c). Любой сбой до замены (ошибка записи, нехватка места, отмена) оставляет исходный файл цел. Слияние заодно чинит нарушенный порядок, даже когда новых записей нет (тогда в ответе fixed:true); оборванная последняя строка файла (нет перевода строки) при слиянии отсекается, а не склеивается с новой. Для слияния нужно свободное место на целый временный файл (история + новые строки + 64 КБ запаса), поэтому при почти полном разделе слияние отказывает до записи (full).
  • Замена файла и восстановление после сбоя питания (main/hist_swap.c). В SPIFFS переименование поверх существующего файла не работает, поэтому замена идёт в три шага: rename(история → .bak), rename(результат → история), remove(.bak) — исходник всегда существует под каким-то именем. Слияние пишется в mrg_*.wip и после проверки размера принимается переименованием в mrg_*.new. Если второй rename не прошёл (после трёх повторов), исходник возвращается на место. Пока рядом лежит непринятый файл слияния (.new, .bak или файл прежней схемы), дозапись в отсутствующую историю запрещена. Восстановление (при старте и перед слиянием и дозаписью), точно по коду: .wip удаляется всегда; если файл истории цел (читается заголовок и есть хотя бы одна строка данных), .bak и файл прежней схемы удаляются, а .new сравнивается с историей по числу строк: при большем числе строк в .new он становится историей, иначе удаляется; если истории нет, она нечитаема или в ней только заголовок — из истории, .new, .bak и файла прежней схемы выбирается файл с наибольшим числом строк (пустая история проигрывает любой копии с данными). При старте radon.csv НЕ создаётся заново, пока рядом остались .new/.bak/.wip или восстановление не удалось (иначе новый пустой файл при следующем старте считался бы целым). Устаревший .new после отказавшейся замены убирается с повторами, а если remove не проходит — переименованием в .wip, который восстановление удаляет всегда. Следствие: при потере питания между двумя rename выбор идёт по числу строк, поэтому заменённая версия с МЕНЬШИМ числом строк (замена участка, где архив плотнее чистит, чем добавляет) может откатиться к прежней — данные целы, операцию надо повторить. Тем же способом заменяются файл истории при прореживании и уплотнении, файлы при импорте истории и при перестройке заголовка. Хост-тест — с обрывом питания на каждом шаге и отказом rename (test_hist_swap.c, test_hist_replace.c).
  • Дубли и сопоставление с живыми точками. Живая точка истории привязана ко времени опроса платы, запись архива — к концу цикла прибора: живая метка позже на «фазу» 0…период опроса (по умолчанию 600 с, Kconfig.projbuild). Одного окна ±180 с недостаточно: при периоде опроса 600 с на фазах 181…420 с пара не находится совсем (каждый цикл добавлялся бы заново — дубль в истории и в файле замера), а на 421…599 с запись сопоставилась бы с соседним циклом. Правило: (1) строка истории в пределах ±180 с — дубль, кроме строки, чьё значение равно ОА соседней записи и не равно ОА этой (она принадлежит соседу); (2) иначе — ближайшая не занятая строка истории с тем же значением ОА (допуск 0,006, то есть округление до 2 знаков) в интервале до max(цикл прибора, период опроса) + 60 с после записи (radex_arch_lag_s: цикл — медиана интервалов между записями); строка, уже сопоставленная другой записи, второй не достаётся. Проверено хост-тестом на всех фазах с шагом 10 с для шести пар (цикл, опрос): (600, 600), (600, 300), (600, 60), (600, 10), (1200, 600), (3600, 600) с — для истории и для трёх из них (600/600, 600/300, 1200/600) — для файла замера (test/host/test_live_match.c); на плате не проверялось. Слабое место: если ОА двух соседних записей совпала до 2 знаков, живая строка может достаться «не той» записи (значение то же, потерь нет). Тот же механизм сверяет журнал («Сохранить N точек в историю») и файл замера. Порядок пометки строк как «занятых» одинаков в двух местах кода (сопоставление истории и сверка файла замера); это проверено перекрёстным тестом. Живая точка после загрузки архива. Запись архива и живая точка одного цикла различаются меткой (0…период опроса). После загрузки плата опрашивает прибор в свой срок, видит то же значение и без защиты писала бы рядом вторую строку того же цикла. Поэтому живая точка не пишется, если та же величина (допуск 0,006) не позже HIST_LIVE_DUP_S = 590 с после последней строки файла (hist_live_dup, radon_stats.c); законный следующий цикл с тем же значением приходит не раньше чем через цикл (не короче 600 с) и защитой не гасится. Последняя строка берётся из хвоста файла (последние 256 Б). Запись отбрасывается, если её время вне допустимых границ — раньше RADON_TIME_MIN = 1 700 000 000 (14.11.2023), позже RADON_TIME_MAX (≈ 2043 год) или позже часов платы более чем на 600 с; если ОА или скользящее среднее не число, отрицательные или больше 1e6 (иначе строка не помещалась бы в буфер слияния). Время записи — часы прибора плюс поправка «часы платы − часы прибора» из пары, снятой при последнем чтении заголовка; если часы прибора не прочитаны (0x0BC2 не дал корректной даты), загрузка отклоняется (noclock), в историю ничего не пишется. Если часы прибора когда-либо ставились неверно, старые записи получат неверное время. Условие запуска: часы платы должны быть синхронизированы (NTP); иначе запрос отклоняется (409, reason: "clock not synced", «Часы платы не синхронизированы — загрузка невозможна»). После перезагрузки платы подождите 2–3 минуты, пока часы синхронизируются (на плате оператора это около 150 с): до этого любая загрузка отвечает «Часы платы не синхронизированы» — это штатно; страница подсказывает то же.
  • Замена участка архивом (POST /api/archive/start?mode=replace, кнопка «Заменить участок архивом»; обычная загрузка по умолчанию не меняется). Отдельная операция, автоматически не запускается. Границы — от метки первой годной записи архива до метки последней. Внутри границ из истории и из файла идущего замера (только строки с меткой не раньше начала замера) убираются ВСЕ строки, которых нет среди записей архива точно такой же строкой (та же метка и те же значения: такие остаются как есть и не переписываются), а на их место кладутся записи архива с сырой ОА в radon. Снаружи границ не трогается ничего — кроме одного расширения: строки в интервале (последняя запись архива, последняя запись
    • lag], где lag = max(цикл, опрос) + 60 с (обычно 660 с), тоже убираются. Причина: живая точка последнего цикла привязана ко времени опроса и лежит ПРАВЕЕ конца цикла, то есть вне границ, хотя это дубль последней записи. Обратная сторона: живая точка, записанная в этом интервале и не имеющая записи в архиве (если прибор закрыл новый цикл уже после чтения архива), тоже будет убрана; обычная загрузка архива вернёт её как новую запись. Завершённые замеры не изменяются никогда. Что делает операция и чего не делает:
    1. Работает в два приёма. Сначала &dry=1 — только подсчёт (ничего не пишется): границы, сколько строк истории и файла замера будет убрано, добавлено и остаётся без изменений. Страница показывает это в окне подтверждения («Действие необратимо — сначала сохраните выгрузку истории (/api/export.csv)») и только после «ОК» шлёт настоящий запрос. Если менять нечего — вопроса нет.
    2. Отказ без записи (400/409, либо ошибка задания с пометкой «ничего не записано»): часы прибора не прочитаны (noclock); цепочка сессий не сходится (chain); число прочитанных записей не равно заявленному в ПЕРВОМ заголовке задания (partial; заголовок за задание читается один раз, чтение идёт по нему); внутри границ есть запись с недопустимым временем или значением, то есть дыра (hole); нет ни одной годной записи (empty); не хватает места на временные файлы истории и замера (full); идёт другое задание (busy); часы платы не синхронизированы; строка запроса разбирается строго: любой неизвестный, повторный, усечённый или лишний параметр, dry без mode=replace, ?max= вместе с mode и значение mode, отличное от replace, — 400 без запуска (bad mode или bad max). Перед реальной заменой сверьте границы (rlo, rhi, hdel в ответе подсчёта dry=1): единая поправка часов прибора применяется ко всем сессиям, поэтому ручной перевод часов прибора или переход на летнее время сдвигает метки записей старых сессий, а границы замены — от минимальной до максимальной метки по всем записям; защита от этого только сверка границ и числа удаляемых строк по подсчёту.
    3. Замена файла — только через .bak (см. выше): потеря питания на любом шаге оставляет файл прежним или новым целиком, при старте он восстанавливается по правилам выше. Отмена в ходе чтения оставляет всё как было. Сначала заменяется история, потом файл замера; если второй шаг не прошёл (test), история уже заменена, а замер нет — повторный запуск довершит (он сверяется с самим файлом). Отмена между двумя файлами — partial.
    4. Повторный запуск подряд ничего не меняет и файлы не переписывает (проверено). Проверено хост-тестом на боевых копиях данных (test/host/test_hist_replace.c, вход — копии файлов платы до ремонта: история 581 строка, файл замера 585 строк): в границах остаются ровно записи архива (392), вне границ строки на месте, пар «живая + архивная» нет. Архив в этом тесте восстановлен по истории, а не прочитан с прибора (реального дампа архива в тестовых данных нет: сетка 600 с от первой парной строки до последней строки истории), поэтому тест доказывает логику замены, а не совпадение с настоящим приборным архивом. Кроме того — синтетика: все фазы 0…600 с шаг 10 с, ряд живых точек, сдвинутый на цикл, дыры в живой серии, дыры в архиве (отказ), 65 536 записей, сбой на каждом шаге замены, отмена, повтор. Проверка на плате оператора — в конце раздела («Что проверено»).
  • Уже испорченная история. Если в истории остались строки от предрелизных сборок этой функции (сглаженное среднее в обеих колонках; запись архива, легшая в конец «не по порядку», из-за чего график «Всё время» рисует ломаные поперёк; пары «живая + архивная» с расхождением меток 196–399 с и равным значением; близкие пары со сдвигом на цикл) — достаточно один раз выполнить «Заменить участок архивом»: в границах архива все такие строки заменятся сырой ОА, порядок восстановится. На плате оператора до замены было 73 пары «живая + архивная» (Δ 196–399 с) и около 90 близких пар — след раннего окна ±180 с; замена участка на плате выполнена (результат — в «Что проверено»). Строки СЛЕВА от первой записи архива (если история старше архива) операция не трогает. Ручная процедура без режима замены: выгрузить /api/export.csv → python firmware-idf/scripts/fix_history_csv.py radon-history.csv fixed.csv --drop-from <с> --drop-to <по> (границы — unix-время загруженных строк; без них скрипт только упорядочивает) → POST /api/history/import с содержимым fixed.csv (история заменяется целиком; импорт порядок не проверяет и не чинит) → «Загрузить весь архив (USB)»: строки вернутся из прибора с сырой ОА. Сырую ОА восстановить из самого CSV нельзя — её там нет.
  • Ёмкость истории. Раздел storage — SPIFFS 2 МБ; по формуле SPIFFS в него помещается около 1,92 МБ данных, строка истории — около 34 байт, но при расчёте берётся худшая новая строка — 45 байт (HIST_ROW_BYTES_MAX в main/hist_space.h: время 10 знаков, radon и radon_avg до «1000000.00», T «-60.0», RH «100», вес «1», пять запятых и перевод строки; проверено тестом на самой длинной строке). Прореживание (каждая вторая строка, вес сохраняется) запускается заранее — когда свободного места остаётся меньше половины файла плюс 160 КБ, то есть при истории около 1,17 МБ (≈ 34 000 строк): порог 1,8 МБ вместе с временным файлом не помещался в раздел (подробнее — KNOWN_ISSUES.md). Прореживание решает по двум величинам: свободному месту и размеру самой истории — историю меньше 256 КБ оно не трогает (если раздел занят чужими файлами, например сохранёнными замерами, прореживать мало толку). Загрузка принимает только то, после чего прореживание не потребуется сразу и место на временный файл слияния есть. При почти пустой истории (8,7 КБ; формулы main/hist_space.h): дописывание в конец — не более ≈ 25 800 новых записей; если идёт замер (строки дублируются в его файл) — ≈ 15 500 и не больше, чем позволяет слияние файла замера (нужно место на его временный файл: при истории 600 КБ, замере 600 КБ и свободных 800 КБ ёмкость дописывания по одной истории — 2 988 строк, по слиянию замера — 1 494; берётся меньшая, ДО записи); слияние — до ≈ 40 800 (нужен целый временный файл). Год (52 560 записей) целиком не помещается. Если не помещается, предпросмотр предлагает загрузить только последние N записей; если после сверки новых записей всё равно больше, чем помещается, загрузка отказывает до записи с понятным текстом.
  • Пределы прибора и протокола. Сквозной индекс — 16 бит: не более 65 536 записей. Заголовок перечисляет до 26 сессий: по трассам RadexDC (они не публикуются) заголовок 0x0C0D — 486 байт; буфер приёма прошивки — 2 048 байт (main/radex_usb.c). Что делает прибор при большем числе сессий, не известно; если сессий больше 26, остальные читаются по цепочке номеров без сверки с количеством. Ёмкость памяти самого прибора неизвестна.
  • Файл идущего замера. В него идут ВСЕ годные записи архива не старше начала замера — и новые для истории, и уже бывшие в ней: история и файл замера могут расходиться (прореживание истории, импорт, строки, которых в замере нет), поэтому запись сверяется с самим файлом замера (±180 с и правило по значению — как для истории), а не с множеством «новых для истории». Файл читается целиком в PSRAM и переписывается слиянием (те же гарантии: временный файл, проверка размера, замена через .bak, при сбое исходный цел); если менять нечего (порядок в норме, новых строк нет, дублей нет) — файл не трогается. Завершённый замер не изменяется никогда.
  • Метки одной записи при разных загрузках (±1 с). Абсолютное время записи = часы прибора + поправка «часы платы − часы прибора». Часы прибора идут целыми секундами, часы платы читаются уже после обмена 0x0BC2/0x0C04/0x0C0D (десятые доли секунды), поэтому поправка при каждой загрузке округляется по-своему, и одна и та же запись получает метку t или t+1. Пара «часы платы — часы прибора» снимается сразу после каждого чтения заголовка (io_header): это убирает часть задержки, но не округление. «Верной» метки нет — истинное время известно с точностью до секунды; меньшая метка, как правило, ближе к истине (тенденция, не гарантия). Загрузка архива от этого не зависит (дубли ±180 с).
  • Ремонт задвоенного замера. Сглаженная строка файла (radon == radon_avg — так клали среднее в обе колонки журнал «Сохранить N точек в историю» в v1.13.x и предрелизные сборки этой функции; сырая строка имеет разные значения) убирается, если рядом (не дальше 30 с) есть несглаженная строка файла или строка из архива: остаётся сырая. 30 с выбраны по данным: наблюдаемое расхождение — 1 с; законные соседние точки идут не чаще цикла прибора (не короче 10 минут = 600 с), то есть запас в 20 раз; сглаженная строка без пары не трогается. Правило работает по содержимому файла и не требует знать, какая версия «новая». Ремонт происходит при следующей загрузке архива; итог — в ответе tadd/tfix и на странице. Если места на временный файл слияния замера нет, а годных записей архива не старше начала замера нет вовсе (nt == 0, radex_archive_job.c), — сверка пропускается (запись в логе); если такие записи есть (nt > 0), ошибка test.
  • Ошибки записи. Если основной файл обновлён, а файл замера нет (нет места), загрузка завершается ошибкой test; повторная загрузка догрузит его (файл замера сверяется сам). Запись живой точки после ошибки записи не склеивается с оборванной строкой: перед дозаписью хвост файла проверяется, обрывок без перевода строки отсекается.
  • Зависание запроса. Принятый запрос, который задача USB не взяла за 20 с (прибора нет), снимается с ошибкой timeout; потеря прибора снимает непринятый запрос и устаревший предпросмотр. Параметр ?max= разбирается строго: не число, 0, больше 65 536 или слишком длинный запрос — 400, а не «весь архив».
  • Время. Страница архива уходит за ≈ 0,15 с (пауза 100 мс между страницами плюс обмен): 52 560 записей — ≈ 2 390 страниц, около 6 минут чтения плюс запись в историю. Оценка расчётная (по паузам RadexDC и трассам); на плате время большого архива не измерялось; страница показывает оставшееся время по фактической скорости.
  • Что проверено. Хост-тесты (pwsh -File test/host/run.ps1, gcc в образе espressif/idf:v6.1; счётчики — в примечаниях к релизу) на синтетическом архиве до 65 536 записей (одна сессия, 20, 26 и 40 сессий, пустые сессии, границы страниц), дедуп с границами окна ±180 с, расчёт ёмкости, отмена, обрыв USB, повтор при чужой позиции, порча потока (пропуск и дубль страницы, чужая сессия, порядок, потеря записи); слияние по времени (архив старше, новее, в середине истории, чересполосица, равные метки, файл вразнобой на 8 000 строк, нарушенный файл на 561 строку с обратным шагом на строке 452, мусорные строки, оборванный хвост), внедрённые сбои (ошибка записи посреди слияния, несошедшийся размер, отказ замены, отмена — исходный файл цел байт-в-байт); замена файла с обрывом питания на каждом шаге и отказом rename; сопоставление с живыми точками (шесть пар цикл/опрос, см. выше); сверка файла замера; защита живой точки от повтора; ёмкость по обоим файлам; сырая и сглаженная ОА раздельно; режим замены (см. выше); прореживание при занятом чужими файлами разделе. Мутации (порча исходника → красный именно тот тест) — test/host/mutate.sh. Проверено на плате оператора 19.09.2026 на предыдущей сборке v1.14.1-r2 (релизная сборка отличается исправлениями из CHANGELOG, «Исправлено перед выпуском (проход по коду)»): загрузка архива и порядок истории; режим замены — подсчёт dry, затем замена: в истории удалено 518, добавлено 425, в замере удалено 509, добавлено 419; после замены история 513 строк без нарушений порядка, без дублей меток и без пар «живая + архивная» ближе 400 с (минимальный интервал 599 с), замер 420 строк (минимальный интервал 477 с), «только в замере» 1 строка; повторный dry — «менять нечего» (hsame 425 / 419); обычная загрузка после замены: новых 0, дублей 425, в файл замера добавлена 1 и убрана 1 строка; запас стека задачи radex_usb 2 680 Б из 6 144 (после замены) и 3 208 Б (после dry); минимум свободной внутренней RAM int_min 47 232 Б; потерянных живых точек очереди 0. Часы платы после перезагрузки синхронизируются (в первом запуске — около 150 с). Прибор: 2 сессии; записей было 278 на момент первой трассы, в ходе проверок 19.09 — 333, 384, 392, 401, 408, 409 и 425 (прибор копит запись раз в 10 минут); тысячи записей проверить нечем. Проверка релизной сборки (v1.14.1-r3) на плате: на плате оператора 19.09.2026 образ запущен и проверен: строгий разбор запроса /api/archive/start (без параметров — 200; ?dry=1, ?foo=1, mode длиннее 15 символов, mode=replace&max=5 — 400); подсчёт замены dry=1 прочитал 430 записей (убрать 5 строк истории и 4 замера, добавить 5 и 5, остальное без изменений); обычная загрузка: новых 0, дублей 430; после неё история 518 строк и замер 425 строк — порядок не нарушен, дублей меток нет, пар «живая + архивная строка» с равным значением ближе 400 с нет; запас стека radex_usb 2820 Б из 6144, int_min 47 924 Б. Не проверялось на плате: ветка старта без radon.csv, восстановление после потери питания на шагах замены и hist_discard (только хост-тесты).. Не проверено на плате (перед использованием проверить самому): защита живой точки от повтора; восстановление после потери питания на каждом шаге замены файла; запас стека httpd при сохранении журнала (слияние идёт в задаче httpd); пик PSRAM при слиянии предельного архива; скорость слияния и записи в SPIFFS для десятков тысяч строк; время чтения большого архива.

Ограничения USB:

  • Питание. Прибор заряжается от платы. Один раз при подключении прибора наблюдалась перезагрузка платы по питанию (POWERON) — возможна просадка напряжения от тока заряда (не подтверждено). Питайте плату от нормального блока 5 В / не менее 1 А, а не от USB-порта ноутбука.
  • Кабель — только с линиями данных (см. выше).
  • Порт эксклюзивен. Пока прибор подключён к плате, RadexDC с ним работать не может, и наоборот.
  • Запросы к прибору — белый список из шести (main/radex_ekosf.c, radex_ekosf.h, radex_req_allowed()): три чтения (0x0BC2 показания, 0x0C0D заголовок архива, 0x0C0E страницы архива), два позиционирования архива (0x0C04, 0x0C05; смысл параметров вскрыт не полностью, кадры повторяют трассы RadexDC) и одна запись — установка часов (0x0006; с v1.13.1 по умолчанию не вызывается, см. ниже). Все прочие RPC отклоняются до отправки; сброс, выключение, загрузчик, удаление файлов и загрузка прошивки не отправляются ни при каких условиях.
  • Установка часов прибора выключена по умолчанию (с v1.13.1). По наблюдению за RadexDC установка времени закрывает текущую сессию замера на приборе и открывает новую, а с платы 0x0006 не проверялась — поэтому шлюз часы прибора не выставляет; в образе кода синхронизации нет. ВНИМАНИЕ, если включить (CONFIG_RADEX_USB_CLOCK_SYNC=y в firmware-idf/sdkconfig.defaults и пересборка; menuconfig → «Radex MR107ion gateway» → «USB: выставлять часы прибора (RPC 0x0006) по NTP»): шлюз после синхронизации платы по NTP при расхождении часов больше порога (CONFIG_RADEX_USB_CLOCK_MAX_DRIFT_S, по умолчанию 5 с; не чаще раза в 6 ч) сам пошлёт 0x0006, а это может начать на приборе новую сессию — «средняя сессии» (radon_avg) начнётся заново. Поведение шлюза выведено из наблюдения за RadexDC, на плате не проверялось. Переключателя в работе (без пересборки) нет. В v1.13.0 синхронизация была включена по умолчанию.

Что измеряется

Набор величин у обеих веток один — он задан протоколом прибора; таблица ниже приводит имена сенсоров ESPHome. Ветка ESP-IDF читает те же handle и публикует радон (последний и средний), температуру, влажность и RSSI (main/ha_mqtt.c), а средние за произвольные периоды считает по собственной истории на флеш-памяти, а не скользящим окном.

Прошивка циклически опрашивает 4 BLE-handle прибора (round-robin, 4.3 с между read'ами, полный цикл ≈ 17.2 с) и публикует следующий набор сенсоров в Web UI:

Метрика Единицы Источник на приборе ESPHome sensor
Метрика Единицы Источник на приборе ESPHome sensor
--- --- --- ---
Радон последний Bq/m³ float32 LE @ handle 0x0049 (OAR_last) radon_bqm3
Радон среднее (прибор) Bq/m³ float32 LE @ handle 0x0040 (OAR_sred) radon_avg_bqm3
Радон среднее за час Bq/m³ sliding_window 60 × 60 c, filter_out: nan radon_avg_hour
Радон среднее за день Bq/m³ sliding_window 1440 × 60 c, filter_out: nan radon_avg_day
Температура °C int16 LE @ handle 0x0058 (temper_x10), декод ÷10 temperature_c
Влажность % uint8 @ handle 0x005E (humidity) humidity_pct
RSSI BLE dBm из advertise-пакетов (on_ble_advertise) rssi_radex

Полная карта 15 характеристик сервиса FE651700-… (включая Sko_OAR_sred, OAR_min/max, OAR_mov_avr, t_izm_last) — в разделе «Полная расшифровка BLE-протокола» ниже и в references/mr107ion.md.

Радон — интегральная статистика по минутным окнам внутри прибора (ионизационная камера накапливает счёт за ≥1 мин). Поэтому period опроса 4.3 с — это плотность ради UI-плавности и точного скользящего окна на стороне ESPHome, а не из-за физики измерения. Для standalone-клиентов 30–60 с — разумный практичный дефолт.


Поддерживаемые приборы

Прибор Что измеряет BLE Готовая прошивка
Radex MR107ion Радон в воздухе (Bq/m³, ионизационная камера) + температура + влажность ✅ firmware/radex_gateway_s3.yaml (актуальная)
Radex RD1212-BT Гамма-фон (мощность дозы, Geiger-счётчик) ✅ планируется после реверса протокола
Radex One Гамма-фон ❌ USB-only вне скилла (BLE-шлюз не применим)

Линейка определяется через единое приложение производителя RadexM (Android, iOS). Все BLE-приборы используют один шаблон GATT-сервисов (FE651Y00-…).


Что НЕ нужно для запуска

  • ❌ Учётная запись Quarta-Rad / привязка к облаку
  • ❌ Постоянно работающий смартфон рядом с прибором
  • ❌ Pairing / bonding (Radex не требует)
  • ❌ Платное ПО

Что нужно

Что Зачем
ESP32-S3-DevKitC-1 N16R8 (актуальная плата) мозг шлюза, USB-C. 16 МБ флеша и 8 МБ PSRAM — то, подо что собрана прошивка. Пример: Ozon
USB Type-C кабель прошивка и питание
Radex MR107ion с BLE источник данных
Wi-Fi 2.4 ГГц + интернет для Home Assistant / Web UI
esphome 2026.5+ на ПК pip install esphome
Адрес BLE-прибора (MAC) не нужен: прошивка находит прибор в эфире сама. Понадобится, только если рядом несколько приборов Radex и нужен конкретный

Развёртывание ветки ESPHome (5 минут)

Здесь — короткая шпаргалка для тех, у кого уже стоит ESPHome и PlatformIO кэш прогрет. Полная пошаговая инструкция с нуля (требования к Windows/Linux/macOS, установка драйверов USB-Serial, Python 3.10–3.12, ESPHome, два пути установки — через Claude Code или через стандартный ESPHome Web Installer, troubleshooting на 10+ проблем) — в INSTALL.md.

1. Подготовить secrets

git clone https://github.com/VibeEngineering-LLC/radex-esp32.git
cd radex-esp32\firmware\
Copy-Item secrets.example.yaml secrets.yaml

Открыть secrets.yaml и заполнить:

  • wifi_ssid / wifi_password — домашняя Wi-Fi 2.4 GHz.
  • ap_password — пароль captive-portal AP «radex-gw-s3 Fallback» (≥8 символов).
  • api_encryption_key — openssl rand -base64 32.
  • ota_password — длинный пароль для OTA.
  • web_server_auth_user / web_server_auth_pass — для Basic Auth на /.
  • radex_mac — можно оставить placeholder, MAC задаётся через Web UI после первой загрузки.

2. Скомпилировать и прошить

$esp = "$env:LOCALAPPDATA\Programs\Python\Python312\Scripts\esphome.exe"
$env:PYTHONIOENCODING = "utf-8"; $env:PYTHONUTF8 = "1"
& $esp compile radex_gateway_s3.yaml
& $esp upload  radex_gateway_s3.yaml --device COM<N>

Найти COM-порт:

Get-CimInstance Win32_PnPEntity | Where-Object { $_.Name -match 'CH340|CP210|FTDI|USB Serial' }

⚠️ На некоторых машинах COM5 — это SoundBlaster, НЕ ESP32. Брать порт, у которого имя содержит USB-SERIAL CH340 / Silicon Labs CP210x / USB Serial Device.

3. Первый запуск → captive portal

Если WiFi не настроен — ESP поднимает AP «radex-gw-s3 Fallback» с паролем из ap_password. С телефона подключиться → http://192.168.4.1/ → выбрать домашнюю сеть → ввести пароль → Save. ESP перезагрузится.

4. Web UI и MAC-привязка

http://radex-gw-s3.local/ (логин/пароль = web_server_auth_user/pass).

  • Группа «Service» → запустить BLE-скан → найти строку MR107ion-12AB, скопировать MAC.
  • Вставить в поле «MAC Radex (AA:BB:CC:DD:EE:FF)» → «Применить MAC и перезагрузить».
  • После рестарта в группе «Data» побегут радон/температура/влажность.

5. Home Assistant

Settings → Devices & Services → Add Integration → ESPHome → host radex-gw-s3.local (или IP), encryption key — тот, что в secrets.yaml.


Что увидишь в Web UI (ветка ESPHome)

Интерфейс ветки ESP-IDF устроен иначе — пять вкладок, описаны в разделе «Альтернативная архитектура».

ESPHome Web UI v3 в radex_gateway_s3.yaml рисует спарклайн на каждой карточке и полноразмерный график при клике. Две тематические группы (sorting_groups):

Группа «Данные» (sg_data)

Карточка Что показывает
Радон последний свежий OAR_last от прибора, Bq/m³, обновляется ~ раз в 17 с (round-robin цикл)
Радон среднее прибор OAR_sred от прибора (внутренняя статистика MR107ion), Bq/m³
Радон среднее за час sliding-window 60 × 60 c по OAR_last, считается на ESP, Bq/m³
Радон среднее за день sliding-window 1440 × 60 c по OAR_last, Bq/m³
Температура int16 LE / 10, °C
Влажность uint8, %

Группа «Сервис» (sg_service)

Карточка Что делает
BLE-сканер кнопка «Start BLE scan» + список найденных приборов; используется при первой привязке MAC
MAC Radex (AA:BB:CC:DD:EE:FF) поле для ручного ввода MAC + кнопка «Применить MAC и перезагрузить» (MAC сохраняется в NVS)
BLE подключён ON/OFF, статус GATT-сессии к прибору
BLE: коннекты / реконнекты счётчики, для диагностики стабильности
RSSI BLE сила сигнала прибора, dBm
Переподключиться к Radex форсированный BLE-disconnect + новый коннект
Сбросить счётчики BLE обнуляет коннекты/реконнекты
WiFi сигнал / SSID / BSSID / IP / MAC шлюза диагностика сети
API подключён статус ESPHome API (есть ли HA на той стороне)
Uptime время с последнего ребута
Switch «Выгружать на Народмон» главный выключатель (по умолчанию OFF, restore_mode: ALWAYS_OFF)
Select «Способ отправки» 4 транспорта Народмона: HTTP GET / HTTP POST / HTTPS POST / JSON POST
Имена метрик RR1 / T1 / H1 имена на стороне Народмона
Кнопка «Отправить на Народмон сейчас» ручной триггер; работает только при ON
Reboot / Safe Mode / Factory reset штатные кнопки управления платой

В альтернативной прошивке radex_gateway_v2.yaml (Web Server v2) — одна плоская таблица с тематическими префиксами 1.x (прибор) / 2.x (BLE+Сеть) / 3.x (Народмон) / 4.x (Система); содержание то же.


Архитектура (ветка ESPHome)

┌────────────┐  BLE READ-poll   ┌────────────────┐  HTTP/WiFi  ┌──────────────┐
│  Radex     │ ───────────────► │  ESP32-S3      │ ──────────► │  Браузер,    │
│  MR107ion  │  4 handle        │  -DevKitC-1    │  JSON +     │  HA,         │
│ (Quarta-   │  каждые 4.3 с    │  N16R8         │  Web UI v3  │  Python      │
│  Rad)      │  (~17.2 с цикл)  │  (ESPHome,     │             │              │
│            │                  │   arduino)     │             │              │
└────────────┘                  └────────────────┘             └──────────────┘
                                       │ I/O
                                       ▼
                                ┌──────────────┐
                                │  Round-robin │
                                │  read pump   │
                                │  4 handle →  │
                                │  6 sensors + │
                                │  sliding-win │
                                │  hour/day    │
                                └──────────────┘
                                       │
                                       │ опционально, ВЫКЛ по умолчанию
                                       ▼
                                ┌──────────────┐
                                │  Народмон    │
                                │  HTTP/HTTPS/ │
                                │  JSON, 600 с │
                                │  ALWAYS_OFF  │
                                └──────────────┘

Никаких облаков. Никаких аккаунтов. Всё крутится в твоей локальной сети, исходники открыты, прошивка — твоя.


Протокол MR107ion

Полная карта BLE GATT + разбор всех 15 характеристик сервиса FE651700-… — references/mr107ion.md.

Кратко: 2 custom-сервиса с базой FE651Y00-00B0-4240-BA50-05CA45BF8AAA, где Y=6 для конфигурации и Y=7 для измерений. Опрос ATT Read (НЕ Notify), приложение RadexM в эфире делает 5 184 read-request за 27 минут (≈ 3.2 req/с, по ~324 read'а на handle).

Самодокументированный протокол: каждая характеристика занимает 3 handle подряд (Decl + Value + User Description 0x2901 с человекочитаемым именем ASCII-транслитом).


Стабильность платформ — почему arduino на S3, почему log: false на классике

Короткий итог: ESP32-S3-DevKitC-1 N16R8 (16 МБ Flash + 8 МБ embedded octal PSRAM) + framework: arduino — стабильная и рекомендованная конфигурация. Классический ESP32-DevKitC v4 (WROOM-32 / 4 МБ flash / без PSRAM) + esp-idf работает только с web_server.log: false и с зафиксированным bluetooth_proxy: # active: true (закомментирован) — каждая попытка включить отладочный лог или вернуть btproxy ломает heap при первом же F5 в браузере.

Проверено серией инцидентов в этом проекте за июнь 2026:

json:111 на DevKitC без PSRAM (v0.3.0-broken-no-log-false)

Первая v0.3.0 после rebuild от bt-proxy baseline шла с web_server.log: true (упомянут в комментарии, физически в YAML отсутствовал = default true). DevKitC при открытом браузере + SSE Debug Log + параллельный http_request к Народмону уходил в каскады:

[E][json:111]: JSON document overflow
[W][component:522] web_server took a long time (73 ms)

min_free_heap пробивал ~12 КБ, Web UI грузился пустым. Лечение одной строкой: web_server: log: false (v0.3.0-step5b, 2026-06-14). Зашито в radex_gateway.yaml как HARD default для DevKitC.

lit fix на v3 sorting_groups (v0.3.0-step6b)

web_server: version: 3 использует web-component lit-element; пустая sorting_group (например, sg_re без сенсоров внутри) ломает рендеринг — карточки не появляются. Лечение: не создавать пустые группы; если временно нет сущностей под группу — удалить блок целиком.

Auth Expired на esp-idf + ручной 600/180 (INC-12 из atomfast/radoneye)

На esp-idf BLE-стек уважает свой собственный coex-балансер; ручные scan-параметры interval: 600ms, window: 180ms (стабильные на arduino) ломают эту модель — WiFi-радио недополучает воздух, STA_DISCONNECTED reason=15 (AUTH_EXPIRE) каждые несколько секунд. HARD-правило по итогу: на esp-idf — 640ms / 32ms (~5 % duty) или вообще снять scan_parameters. На S3 + arduino — не воспроизводится, оператор оставил scan-параметры дефолтные.

log: true на S3 — сознательное исключение

ESP32-S3-DevKitC-1 N16R8 несёт 8 МБ embedded octal PSRAM. Запас heap на порядок больше, чем на классическом DevKitC; json:111 при F5 не достигается. В radex_gateway_s3.yaml оставлен web_server: log: true — Debug Log виджет работает. Условие отката (зашито в комментарий YAML): любые ребуты / json:111 / OOM на S3 → вернуть log: false и не активировать заново, без переспроса.

Итог: что выбрать

  • ⭐ ESP32-S3-DevKitC-1 N16R8 → radex_gateway_s3_n16r8.yaml (arduino, log: true) — профиль памяти платы задан явно, MAC прибора искать не нужно, ставится готовым образом.
  • ESP32-S3-DevKitC-1 N16R8, сборка своими руками с MAC в secrets.yaml → radex_gateway_s3.yaml (arduino, log: true).
  • Классический ESP32-DevKitC v4 (если уже на руках) → radex_gateway.yaml (esp-idf, v0.3.0-step8, log: false, bluetooth_proxy: # active: true закомментирован). Стабилен в этой конфигурации; на esp-idf с другими настройками — нет.
  • Альтернативный UX на классике → radex_gateway_v2.yaml (Web Server v2, одна плоская таблица с префиксами).
  • Smoke-тест железа на новой S3-плате до полной заливки → radex_gateway_s3_baseline.yaml (минимальный набор: BLE/API/Web UI без логики опроса).

Полная расшифровка BLE-протокола Radex MR107ion

Цифры ниже — результат live HCI-capture 2026-06-12 (Android RadexM, btsnoop_hci, 27 мин, 46 840 пакетов) + ble-explorer sweep v0.1.4/v0.1.5 с реального прибора MR107ion 0214. Подробности — в references/mr107ion.md.

Идентификация прибора в эфире

Параметр Значение
Модель MR107ion (новая ревизия MR107 с BLE)
advertising local_name MR107ion 0214 (последние 4 цифры — ревизия)
Тип PDU ADV_IND
Pairing / bonding НЕ требуется

GATT-таблица (live HCI capture)

Handle range Service UUID Назначение
0x0001–0x0009 0x1800 GAP (стандарт)
0x000a–0x000d 0x1801 GATT (стандарт)
0x000e–0x0013 6E400001-B5A3-F393-E0A9-E50E24DCCA9E Nordic UART (NUS) — placeholder, не работает
0x0014–0x0020 0x180a Device Information
0x0021–0x003d FE651600-00B0-4240-BA50-05CA45BF8AAA Custom Config (R/W, 14 chars)
0x003e–0x006b FE651700-00B0-4240-BA50-05CA45BF8AAA Custom Measurement (R, 15 chars)

Основная работа — через два custom-сервиса с базой FE651Y00-00B0-4240-BA50-05CA45BF8AAA, где Y=6 для конфигурации и Y=7 для измерений.

Pattern взаимодействия — READ-poll, НЕ Notify

Главная находка реверса. Приложение RadexM опрашивает прибор циклическими ATT Read, не подписывается на Notify. За 27-минутную HCI-сессию:

  • Total ATT Read requests: 5 184 (≈ 3.2 req/sec средне).
  • Каждый ключевой handle опрошен 324 раза (≈ 1 раз / 5 с per handle).
  • Notify пакеты за сессию: 0. Прибор честно отвергает CCCD-write на NUS.

Это сильно отличается от RadonEye / AtomFast (push-only), но облегчает ESP32-port: не нужно ждать асинхронные Notify, можно поллить с любым удобным периодом.

Самодокументированный протокол (User Description 0x2901)

Каждая характеристика сервиса FE651700-… занимает 3 последовательных handle:

  1. Decl (нечётный, начиная с 0x003F) — Properties + value_handle + 128-bit UUID с базой FE6517NN-00B0-4240-BA50-05CA45BF8AAA, где NN = 01, 02, 03 … 15 (hex).
  2. Value (decl+1) — собственно данные (float32 LE / uint32 LE / uint16 LE / uint8).
  3. User Description (decl+2, UUID 0x2901) — человекочитаемое имя поля ASCII (транслит русского, почерк QuartaRad).

Сначала читаешь desc-handle → получаешь имя поля; потом читаешь value по offset −1.

Полная карта сервиса FE651700 (live values от MR107ion 0214)

# Decl Value Desc Имя Тип Сырое значение Декод Смысл
1 0x003F 0x0040 0x0041 OAR_sred float32 LE 55 89 93 42 73.79 Радон среднее, Bq/m³
2 0x0042 0x0043 0x0044 Sko_OAR_sred float32 LE A1 2A 39 41 11.572 СКО среднего, Bq/m³
3 0x0045 0x0046 0x0047 t_izm_last uint32 LE 8B 58 00 00 22667 Uptime / время посл. изм., сек (+1/сек)
4 0x0048 0x0049 0x004A OAR_last ⭐ float32 LE 00 00 8A 42 69.0 Радон последнее, Bq/m³
5 0x004B 0x004C 0x004D OAR_mov_avr float32 LE 55 55 92 42 73.17 Скользящее среднее, Bq/m³
6 0x004E 0x004F 0x0050 Qakk (trunc) uint16 LE 61 00 97 Имя обрезано до 4 байт; вероятно Qakkum_OAR
7 0x0051 0x0052 0x0053 OAR_min float32 LE 7C 3B 47 42 49.81 Радон минимум, Bq/m³
8 0x0054 0x0055 0x0056 OAR_max float32 LE 23 F7 99 42 76.98 Радон максимум, Bq/m³
9 0x0057 0x0058 0x0059 temper_x10 int16 LE *) 0A 01 266 Температура × 10 → 26.6 °C
10 0x005A 0x005B 0x005C preassure (sic) uint16 LE 00 00 0 Давление (нет датчика?)
11 0x005D 0x005E 0x005F humidity uint8 31 0x31 = 49 Влажность, %
12 0x0060 0x0061 0x0062 quantity_izm uint16 LE 04 00 4 количество единиц измерения
13 0x0063 0x0064 0x0065 num_izmer uint16 LE 03 00 3 число измерений
14 0x0066 0x0067 0x0068 t_prepare uint16 LE 00 00 0 время подготовки, сек
15 0x0069 0x006A 0x006B mis_psw uint16 LE 80 00 128 misc / status flags

Sanity-checks (внутренняя согласованность реверса)

  • OAR_last (69.0) укладывается в диапазон min/max (49.81 / 76.98) и близко к среднему/скользящему (73.79 / 73.17) — все значения консистентны.
  • temper_x10 = 266 → 26.6 °C, humidity = 49 % — типовые комнатные условия.
  • t_izm_last растёт на +1 в секунду (+25 за 25 c наблюдения) — uptime.

Минимальный poll-set для ESPHome-port

Достаточно 4 read'ов на цикл:

Handle Поле Формат Сенсор
0x0049 OAR_last float32 LE radon_bqm3 — главное значение
0x0040 OAR_sred float32 LE radon_avg_bqm3
0x0058 temper_x10 int16 LE / 10 *) temperature_c
0x005E humidity uint8 humidity_pct

Период опроса в прошивке скилла — 4.3 с round-robin на 4 хэндла (≈17.2 с на полный цикл). Радон — интегральная статистика по минутным окнам, поэтому для standalone-клиентов 30-60 с — разумный практичный дефолт. Приложение RadexM поллит ~5 Hz исключительно ради UI-плавности.

*) temper_x10 декодируется как int16 LE — super-set, корректно работает и при uint16, и при int16 two's complement. Подробное обоснование — в references/mr107ion.md.

UUID для ESPHome ble_client.characteristic

База характеристик — FE6517NN-00B0-4240-BA50-05CA45BF8AAB (последний байт AAB); номер характеристики NN стоит на позиции 17NN. Не путать с базой сервиса Custom Measurement — FE651700-00B0-4240-BA50-05CA45BF8AAA (последний байт AAA). У Quarta-Rad сервис и его характеристики оканчиваются на разные байты — это видно во всех 15 char-UUID.

NN UUID характеристики Поле
01 FE651701-…AAB OAR_sred (handle 0x0040)
04 FE651704-…AAB OAR_last (0x0049) ⭐
09 FE651709-…AAB temper_x10 (0x0058)
11 FE651711-…AAB humidity (0x005E)

Handle на ревизии 0214 совпал между двумя reset'ами, межревизионная стабильность не верифицирована. UUID — более устойчивый контракт: он зашит в прошивку прибора и переживает реорганизацию GATT-таблицы. При портировании на новую ревизию или другой Radex-прибор: пересобрать GATT-карту через ble-explorer (0x2901 descriptors) и проверить handle'ы; если расходятся — переключить ESPHome-конфиг на UUID-read.

Подтверждение, что NUS — placeholder

CCCD-write на 0x0013 (NUS TX descriptor) приложение делает дважды при подключении (value=0100 — subscribe Notify), оба запроса прибор молча игнорирует. NUS-сервис у MR107ion декларирован только для совместимости с поиском в магазинах приложений, фактически не работает.


Где живёт график

В оперативной памяти ESP. Web UI v3 ESPHome хранит историю sensor'ов с момента последней перезагрузки (~ час на типичную карточку). Если нужна постоянная история — подключи к Home Assistant через ESPHome API (api_encryption_key уже сгенерирован в secrets.yaml). HA подхватывает все entities автоматически.


Народмон-инфраструктура — ВЫКЛ по умолчанию (HARD)

Switch «Выгружать на Народмон» в прошивке создан, но ОБЯЗАН иметь restore_mode: ALWAYS_OFF:

- platform: template
  name: "Выгружать на Народмон"
  id: narodmon_enabled
  restore_mode: ALWAYS_OFF     # ← HARD: после reboot/safe-mode/OTA всегда OFF
  optimistic: true

После ребута, кратковременного отключения питания, safe-mode, factory_reset, OTA — switch всегда возвращается в OFF. Оператор не получит «сюрприза» включённой выгрузки в облако.

Select «Способ отправки» предлагает 4 транспорта (описаны во внутреннем скилле narodmon-iot того же автора):

  • HTTP GET — narodmon.ru/get?ID=<MAC>&RR1=<value>&T1=<value>&H1=<value>
  • HTTP POST — narodmon.ru/post, form-urlencoded
  • HTTPS POST — то же, но через mbedTLS
  • JSON POST — narodmon.ru/json, application/json

Минимальный интервал на стороне сервера — 5 минут; короче = бан IP на час. В прошивке жёстко 600 с.


HARD anti-patterns (нарушение → утечка секретов / порча прибора)

  • ❌ Не публиковать firmware.bin / firmware.factory.bin — бинарник содержит WiFi-SSID, WiFi-пароль, MAC прибора, OTA-пароль, API encryption key в plain ASCII. Только YAML + secrets.example.yaml с placeholder'ами.
  • ❌ Не убирать restore_mode: ALWAYS_OFF со switch Народмона (HARD 2026-06-17).
  • ❌ Не запускать esphome logs --device COM<N> — DTR/RTS ребутает плату и обрывает BLE-сессию. Использовать OTA-logger (--device <hostname>.local) или mode COM<N> DTR=OFF RTS=OFF + Python-serial.
  • ❌ Не пытаться подписаться на Notify NUS (6E400003-…) — это placeholder, никогда не шлёт Notify. Только READ-poll по FE651700-….
  • ❌ Не путать MR107 (USB-only старый) и MR107ion (BLE-новый) — старые USB reverse-инструменты не подходят.
  • ❌ Не использовать web_server.log: true на C3/S3 без явного решения оператора — SSE Debug Log при F5-шторме = json:111 overflow + near-OOM (корень фикса v0.3.0-step5b/6g). На S3 это исключение оператора оставлено как true — если пойдут ребуты, вернуть false без переспроса.

Совместимость с лимитом 3× ble_client (старая плата) / 4× (S3)

Плата BLE central слотов Сколько занимает эта прошивка
ESP32-DevKitC (Bluedroid) 3 1
ESP32-S3 4 (esp32_ble.max_connections: 4) 1

Свободные слоты — под AtomFast и/или RadonEye на той же плате. Это укладывается в концепцию единого BLE-шлюза (1 ESP32-S3 → несколько приборов через ble_client). Параллельный публичный шлюз AtomFast — см. VibeEngineering-LLC/atomfast-esp32.


Известные проблемы и ограничения

📋 Полная матрица совместимости плат, рекомендации по выбору железа и журнал инцидентов — в KNOWN_ISSUES.md. В частности — почему ESP32-C3 SuperMini не подходит для текущих YAML (инцидент INC-C3-001: OSError: [Errno 28] No space left on device).

  • Handle-based read привязан к ревизии 0214 MR107ion. На другой ревизии — заменить на UUID-read (медленнее, но устойчиво к смене handle-карты).
  • MTU 23 (не растёт) — не критично, payload'ы влезают.
  • Pseudo-NUS (6E400001-…) объявлен прибором, но не шлёт Notify — не пытаться подписаться через CCCD.
  • Народмон-select имеет 4 опции. Минимальный интервал сервера — 5 мин; короче = бан IP на час. В прошивке жёстко 600 с.
  • Кэш ESPHome при правке только secrets.yaml: esphome upload может залить старый кэшированный firmware.bin без пересборки. Лечение — esphome clean <yaml> перед compile/upload всегда после правки секретов.

Ограничения ветки ESP-IDF (перечисленные пункты, кроме привязки к ревизии прибора и MTU, относятся к ESPHome-ветке):

  • Одна целевая плата. sdkconfig.defaults фиксирует esp32s3, 16 МБ флеша и octal PSRAM; PSRAM обязателен. Проверок на других платах не проводилось.
  • Веб-интерфейс без аутентификации. Пароля нет ни на странице, ни на маршрутах /api/*, включая перезагрузку и изменение настроек.
  • Пароль Wi-Fi в NVS открытым текстом. Читается из флеша при физическом доступе к плате; шифрование флеша выключено по умолчанию, так как включается необратимо.
  • Перед сменой целевого чипа удалить sdkconfig — он привязан к чипу и перекрывает значения из sdkconfig.defaults.

Структура скилла

radex-esp32/
├── README.md                          ← эта инструкция
├── INSTALL.md                         ← установка обеих веток с нуля
├── KNOWN_ISSUES.md                    ← матрица плат и журнал инцидентов
├── SKILL.md                           ← обзор семейства + методология RE нового прибора
├── firmware/                          ← ВЕТКА ESPHome (релизы v0.1.0 – v0.5.0)
│   ├── radex_gateway_s3_n16r8.yaml    ← РЕКОМЕНДУЕМАЯ (ESP32-S3-DevKitC-1 N16R8, автопоиск прибора)
│   ├── radex_gateway_s3.yaml          ← АКТУАЛЬНАЯ (ESP32-S3-DevKitC-1)
│   ├── radex_gateway_s3_baseline.yaml ← baseline для S3 (smoke-тест)
│   ├── radex_gateway.yaml             ← v0.3.0-step8 (ESP32-DevKitC, ESP-IDF, Web UI v3)
│   ├── radex_gateway_v2.yaml          ← альтернатива (Web Server v2, плоский UI)
│   ├── secrets.example.yaml           ← шаблон секретов
│   ├── secrets.public.yaml            ← значения, с которыми собран публичный бинарник
│   ├── CHANGELOG.md                   ← история версий
│   ├── include/                       ← C-хедеры (BLE hooks)
│   ├── www/                           ← кастом-CSS/JS для v2 (log_limit.css, reorder_v2.js)
│   └── archive/                       ← старые YAML
├── firmware-idf/                      ← ВЕТКА ESP-IDF (релизы v1.x), только ESP32-S3 N16R8
│   ├── CMakeLists.txt · partitions.csv · sdkconfig.defaults
│   ├── build.sh · build.ps1           ← сборка в Docker espressif/idf:v6.1
│   ├── main/
│   │   ├── main.c                     ← порядок инициализации подсистем
│   │   ├── ble_radex.c/.h             ← BLE-клиент к прибору, переподключение, счётчик отказов
│   │   ├── wifi_manager.c             ← STA, страница настройки, полевой AP, mDNS
│   │   ├── web_server.c               ← веб-интерфейс и маршруты /api/*
│   │   ├── radon_stats.c/.h           ← история на флеш, средние за периоды, рациональный критерий
│   │   ├── poll_cycle.c/.h            ← распознавание цикла пересчёта прибора
│   │   ├── ha_mqtt.c · narodmon.c · net_time.c · log_ring.c
│   │   └── secrets_local.h.example    ← необязательная предзапись сети (в git не попадает)
│   └── web/                           ← исходники страницы, сборка одностраничного HTML
└── references/
    ├── mr107ion.md                    ← полная GATT-таблица MR107ion (live HCI + ble-explorer sweep)
    ├── family-patterns.md · re-methodology.md
    └── tsapalov-metodika-2025.md      ← методика рационального критерия (+ PDF первоисточника)

Как добавить новый прибор Radex

Подробная методология — в SKILL.md, раздел «Reverse-стратегия для нового Radex-прибора». Кратко:

  1. Снять btsnoop HCI capture с Android RadexM (Developer options → Enable Bluetooth HCI snoop log → adb bugreport → FS/data/misc/bluetooth/logs/btsnoop_hci.log).
  2. Прогнать через scripts/parse_btsnoop_v2.py или Wireshark.
  3. Зафиксировать GATT-карту в references/<model>.md.
  4. Верифицировать на железе через ble-explorer — внутренний BLE-RE инструмент того же автора (Web UI с GATT-enum + Notify capture).
  5. Сделать копию firmware/radex_gateway_s3.yaml, подменить UUID/handles и lambda-парсер под новый формат.

Связанные скиллы

Публичный из них только atomfast-esp32; остальные — внутренние инструменты того же автора, отдельного публичного адреса у них нет.

  • atomfast-esp32 — соседний скилл по AtomFast (Notify-based γ-дозиметр), служит шаблоном для Народмон-выгрузки.
  • esp32-dev — общие практики разработки на ESP32 + ESPHome.
  • ble-explorer — универсальный BLE-RE шлюз (GATT-enum, 0x2901, Notify capture).
  • radoneye-esp32 — RadonEye Plus2 (тоже радон, но Notify, не READ-poll).
  • narodmon-iot — протокол выгрузки на narodmon.ru.

Производитель

Quarta-Rad / QuartaRad, Москва, RU.

Приложение производителя: RadexM Android · RadexM iOS.


Лицензия

MIT.

About

ESPHome BLE-gateway для радон-детекторов Quarta-Rad / Radex (MR107ion и линейка): READ-poll GATT, ESP32-S3 + Home Assistant + Web UI v3. Open source, MIT.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages