BLE-шлюз для дозиметра AtomFast на ESP32. Подключается к прибору по Bluetooth Low Energy, парсит фирменный 13-байт on-air протокол и публикует живые показания в Web UI ESPHome (7 графиков в S3 baseline / 6 в классической прошивке) прямо в браузере — без приложения, без Home Assistant, без облака.

Рекомендованная плата в работе: ESP32-S3-DevKitC-1 N16R8 с внешней U.FL-антенной — приборный прогон ≈ 4 суток без ребутов (2026-06-25).

Шлюз подключается к дозиметру AtomFast по Bluetooth Low Energy и только читает on-air данные прибора — команд на прибор не шлёт, накопленные показания и настройки прибора не меняет. Риск для самого прибора минимален. Прошивка/OTA относится к плате ESP32; прерывание прошивки может потребовать повторной заливки платы через USB.

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

С v0.9.0-c3 файлы прошивок разложены по индивидуальным подпапкам по типу платы:

firmware/
├── esp32-classic/         atomfast_gateway.yaml + include/gatt_dump.h
├── esp32-s3-devkitc/      atomfast_gateway_s3.yaml
├── esp32-c3-supermini/    atomfast_gateway_c3.yaml
├── secrets.example.yaml   (общий шаблон секретов)
├── CHANGELOG.md
├── archive/               (исторические версии классики)
└── .gitignore

Все три YAML не взаимозаменяемы — разные платы, фреймворки, BLE-стеки и компромиссы:

Рекомендация: esp32-s3-devkitc/atomfast_gateway_s3.yaml на ESP32-S3-DevKitC-1 N16R8. Стабильная, актуальная, с запасом по памяти и внешней антенной.

Приложение AtomFast красивое, но:

• закрытое — нет API, данные живут только в телефоне;
• сессионное — записывает только пока приложение открыто;
• только Android/iOS — нельзя интегрировать в умный дом.

Эта прошивка превращает любой ESP32 в постоянно работающий шлюз: он держит связь с прибором 24/7, сохраняет график в памяти ESP, отдаёт JSON через HTTP, и при желании подключается к Home Assistant.

Каждые 2 секунды прибор отправляет полный пакет состояния (тот же, что видит приложение). Прошивка парсит его побайтно и публикует в Web UI:

Декод сходится с протоколом по источнику парсинга — официальное приложение AtomSwift от изготовителя (Am6er/atomswift, приватный репо). Длинное side-by-side сравнение «экран приложения vs Web UI шлюза по каждой метрике» ещё не делалось, но раскладка байтов (val_dose, val_intensity, pulses_2s, battery, temperature) совпадает с upstream-кодом из AtomSwift AtomDeviceNRF.java.

Железо:

• Рекомендуется: ESP32-S3-DevKitC-1 N16R8 (16 MB Flash + 8 MB embedded octal PSRAM, разъём U.FL/IPEX для внешней антенны, Wi-Fi + Bluetooth, USB-C). Стабильна на esp-idf-baseline.
• Альтернатива (архивная): классический ESP32-DevKitC v4 на WROOM-32 с CH340 — только под arduino-baseline atomfast_gateway.yaml. С esp-idf не работает стабильно.
• кабель USB-C (для S3) или Micro-USB (для классического v4) → ПК для первой прошивки
• блок питания 5 V USB или powerbank для постоянной работы
• сам дозиметр AtomFast (модель 5xx с BLE)

Софт:

• Python 3.10+
• ESPHome ≥ 2026.5: pip install esphome
• драйвер CH340 (Windows: WCH-CH340 driver)

Здесь — короткая шпаргалка для тех, у кого уже стоит ESPHome. Полная инструкция с нуля (требования к Windows/Linux/macOS, два пути установки: через Claude Code или через стандартный ESPHome Web Installer) — в INSTALL.md.

🔑 Правило: настраиваем ТОЛЬКО secrets.yaml. YAML-конфиги копируются как есть, внутрь не лезем. С v0.9.1 MAC прибора задаётся в одном месте — secrets.yaml::atomfast_mac. Никаких substitution в YAML править не надо. WiFi, пароли, MAC, API-ключ — всё ТОЛЬКО secrets.yaml.

# 1. Скопировать прошивку к себе
git clone https://github.com/VibeEngineering-LLC/atomfast-esp32.git
cd atomfast-esp32/firmware

# 2. Заполнить секреты — ЕДИНСТВЕННЫЙ файл, который ты редактируешь
cp secrets.example.yaml secrets.yaml
# Открыть secrets.yaml в редакторе, заполнить ВСЕ поля:
#   wifi_ssid, wifi_password, ap_password,
#   api_encryption_key (см. INSTALL.md Шаг 4.1 — обязательно сгенерировать!),
#   ota_password, web_username, web_password,
#   atomfast_mac (MAC твоего AtomFast),
#   atomfast_s3_*  / atomfast_c3_* — если шьёшь S3- или C3-вариант.

# 3. ВАЖНО: положить secrets.yaml В ПОДПАПКУ платы, которую шьёшь
#    ESPHome ищет !secret в той же папке, что и YAML.
#    Если шьёшь S3:
cp secrets.yaml esp32-s3-devkitc/secrets.yaml
#    Если шьёшь C3:
cp secrets.yaml esp32-c3-supermini/secrets.yaml
#    Если шьёшь classic:
cp secrets.yaml esp32-classic/secrets.yaml
#    (Файл уже в .gitignore — в git не попадёт.)

# 4. Прошить через USB — YAML-файлы НЕ ПРАВИМ, они работают как есть
#    a) ESP32-S3-DevKitC-1 N16R8, esp-idf, baseline bluetooth-proxies upstream (РЕКОМЕНДУЕТСЯ):
esphome run --device COM3 esp32-s3-devkitc/atomfast_gateway_s3.yaml          # Windows
esphome run --device /dev/ttyUSB0 esp32-s3-devkitc/atomfast_gateway_s3.yaml  # Linux

#    b) Классический ESP32-DevKitC v4 (архивная сборка для старых плат, только arduino):
esphome run --device COM3 esp32-classic/atomfast_gateway.yaml

#    c) ESP32-C3 SuperMini (mini-baseline, arduino + NimBLE, без bt-proxy):
esphome run --device COM3 esp32-c3-supermini/atomfast_gateway_c3.yaml

# 5. Открыть Web UI (логин/пароль = web_username / web_password из secrets.yaml)
# http://atomfast-gw-s3.local/   (mDNS, для esp-idf S3 baseline — РЕКОМЕНДУЕТСЯ)
# http://atomfast-gw.local/      (mDNS, для arduino-прошивки на классическом DevKitC)
# http://atomfast-gw-c3.local/   (mDNS, для C3 SuperMini)
# или   http://<IP-ESP-в-сети>/

⚠ Если Web UI не пускает или WiFi не подцепился — почти всегда secrets.yaml лежит не в той папке. ESPHome ищет !secret в той же подпапке, что и YAML прошивки (esp32-c3-supermini/, esp32-s3-devkitc/, esp32-classic/), а не только в корне firmware/. См. Шаг 3 выше.

После первой прошивки следующие обновления — по воздуху (OTA):

esphome run --device atomfast-gw-s3.local esp32-s3-devkitc/atomfast_gateway_s3.yaml   # S3 (рекомендуется)
esphome run --device atomfast-gw.local    esp32-classic/atomfast_gateway.yaml         # classic
esphome run --device atomfast-gw-c3.local esp32-c3-supermini/atomfast_gateway_c3.yaml # C3 SuperMini

ESPHome Web UI v3 рисует спарклайн на каждой карточке и полноразмерный график при клике. Группы:

AtomFast — показания (главная)

• CPS (мгновенный)
• Мощность дозы µSv/h
• Мощность дозы µR/h
• Импульсы за 2 с
• Накопленная доза µSv
• CPS (среднее за окно)
• Мощность дозы (среднее за окно)

Настройки

• слайдер «Интервал агрегации» (1..60 с, init 5) — окно усреднения CPS/dose. Только в S3 baseline (atomfast_gateway_s3.yaml, number.agg_interval_s). В классической прошивке слайдера нет — фиксированное окно.
• кнопка «Перечитать GATT» (для отладки BLE) — только в классической прошивке (atomfast_gateway.yaml, через include/gatt_dump.h). В S3 baseline GATT-UI нет.

RE / Отладка BLE (только в классической прошивке)

• сырой hex последнего notify-пакета
• дамп GATT-таблицы прибора

Диагностика

• батарея AtomFast
• температура AtomFast
• RSSI BLE
• WiFi сигнал
• uptime

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

Для CSV-логирования на ПК — отдельный Python-демон (см. scripts/ в исходном проекте, либо подключиться к JSON-эндпоинту /sensor/cps_instant).

┌────────────┐  BLE notify   ┌──────────────┐  HTTP/WiFi  ┌───────────┐
│  AtomFast  │ ──────────►  │  ESP32-DevKit │ ──────────► │ Браузер,  │
│  (Plus2)   │   13 байт    │   (ESPHome)   │   JSON +    │ HA, Python│
│            │   раз в 2 с  │               │   Web UI v3 │           │
└────────────┘              └──────────────┘             └───────────┘
                                   │ I/O
                                   ▼
                            ┌──────────────┐
                            │  парсер      │
                            │  13 байт →   │
                            │  7 sensors   │
                            └──────────────┘

Никаких облаков. Никаких аккаунтов. Всё крутится в твоей локальной сети.

Полная карта BLE GATT + разбор on-air payload — references/atomfast-onair-protocol.md.

Кратко: 13 байт каждые 2 с по characteristic 70BC767E-7A1A-4304-81ED-14B9AF54F7BD сервиса 63462a4a-c28c-4ffd-87a4-2d23a1c72581 — флаги + 2 float32 LE (накопленная доза mSv, мощность дозы µSv/h) + uint16 LE (импульсы) + батарея + температура.

[AtomSwift app на телефоне (опционально)]
            │
            BLE single-central — выйти из app перед запуском шлюза!
            │
            ▼
   ┌─────────────────────┐
   │  AtomFast Plus2     │  ◄── BLE notify push (0.5 Hz, 13 байт)
   │  Service 63462a4a...│
   │  bond не требуется  │
   └─────────────────────┘
            │
            │ BLE advertise + connect
            │
            ▼
   ┌─────────────────────┐
   │  ESP32-DevKitC      │
   │  (ESPHome           │
   │   atomfast_gateway) │
   └─────────────────────┘
            │
            │ WiFi 2.4 GHz (co-existence с BLE)
            │
            ├──► Web UI — http://atomfast-gw.local/ :80 (sparkline + 7 графиков)
            ├──► Home Assistant — ESPHome API :6053 (encrypted)
            └──► Народмон — http://narodmon.ru/get каждые 5 мин (R1/D1/T1/BAT1)

Тип: чистый push-only Notify. Host подписывается через CCCD на 70BC767E-..., прибор сам шлёт пакет раз в 2 с. Никакого опкода / команды слать не нужно — данные идут сразу после CCCD write 01 00.

Live verification: 00 EE EE E1 3C 07 7A BA 3D 26 00 40 19 → доза 27.58 µSv, rate 0.091 µSv/h, 38 имп/2с (19 cps), 64 % батарея, 25 °C (см. references/atomfast-onair-protocol.md).

esp32_ble_tracker:
  scan_parameters:
    active: true       # defaults (320/30 ms ≈ 9 % duty)

ble_client:
  - mac_address: !secret atomfast_mac
    id: ble_atomfast
    auto_connect: true   # AtomFast advertise'ит регулярно
    services:
      - uuid: "63462a4a-c28c-4ffd-87a4-2d23a1c72581"
        characteristics:
          - uuid: "70BC767E-7A1A-4304-81ED-14B9AF54F7BD"
            on_notify:
              then:
                - lambda: |-
                    // parse 13-byte payload, publish 7 sensors

Историческая заметка: в atomfast v0.4.x использовался ручной scan_parameters: { interval: 600ms, window: 600ms, active: true } (взято из retry_delay = 600 в AtomSwift firmware). Это работает при одиночном ble_client без HA-нагрузки. Как только в прошивке появляется второй сервис (ESPHome API + Web UI + Народмон HTTP), defaults становятся обязательными — см. esp32-dev/SKILL.md → "scan_parameters defaults для WiFi co-existence" и инцидент radex v0.1.2 → v0.1.3.

Короткий итог: ESP32-S3-DevKitC-1 N16R8 (16 МБ Flash + 8 МБ embedded octal PSRAM, U.FL/IPEX, USB-C) + esp-idf — стабильная и рекомендованная конфигурация. Классический («синий») ESP32-DevKitC с WROOM-32 / 4 МБ flash / без PSRAM + esp-idf — НЕ стабилен: WiFi/BLE coexistence ломает реконнекты, web_server без PSRAM уходит в json:111. На том же классическом DevKitC arduino-фреймворк работает, но это исторический baseline для уже имеющихся плат, а не рекомендация для новой установки.

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

При попытке мигрировать AtomFast-шлюз с arduino на esp-idf (v0.7.0–v0.7.1) на той же плате DevKitC с теми же scan-параметрами оператор получил:

• rsn 0x3e × 2 — Connection Establishment Failure: HCI ESP'а пытается установить link, прибор не отвечает, повтор.
• CONNECTED #7 — успешный коннект только с седьмой попытки после reboot (на arduino — с первой).
• сессия 7 секунд, реконнект 13 секунд — на arduino сессии многочасовые.

Откат на arduino (v0.7.2, тот же 600 ms / 180 ms scan) → 40-минутный прогон: CONNECTED #1 за ~21 с, 0× rsn 0x3e, 0 ребутов. Регрессия чисто эспидфовая.

Корень: esp-idf включает встроенный BLE/WiFi coexistence-механизм (CONFIG_ESP_COEX_SW_COEXIST_ENABLE), который динамически режет тайминги BLE-сканера для защиты WiFi-радио. Эти подрезы конфликтуют с активным ble_client, который пытается удерживать GATT-сессию — и проигрывает.

При прошивке RadonEye HA Gateway на esp-idf со стандартным «арудино-стабильным» interval: 600ms, window: 180ms (duty 30%) — плата уходит в Auth Expired сразу после ассоциации к WiFi:

• пинг — 50% потерь;
• web server мёртв (curl exit 28 — connection refused);
• UART флудит wifi: STA_DISCONNECTED reason=15 (AUTH_EXPIRE).

Корень: на arduino эти 600/180 — твои персональные scan-окна, BLE-стек ESP'а просто их слушает. На esp-idf coex-субсистема ожидает дефолтные «короткие» окна и применяет свои коррекции поверх; ручные interval/window ломают её модель и заставляют BLE занимать радио по жёсткому расписанию. WiFi-радио (один и тот же чип!) недополучает воздух и не успевает обновить ключ авторизации.

HARD-правило по итогу INC-12: на esp-idf с активным ble_client — 640ms / 32ms (~5% duty) или вообще оставить только active: false (esp-idf сам сбалансирует). На arduino — 600 ms / 180 ms (30% duty).

В atomfast_gateway_s3.yaml стоит 640/32 — соблюдено.

Когда в Web UI ESPHome v3 включена панель Debug Log, она подписывается на тот же SSE-стрим /events, что и состояния сенсоров. На esp-idf-сборке ESP32-DevKitC (320 КБ RAM, без PSRAM) каждое сообщение лога — отдельный JSON-event. При интервале опроса сенсоров 5 с + WiFi-флапы + лог DEBUG'а это даёт десятки event/с, ArduinoJSON document переполняется:

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

Один залп = ~20 строк/сек, длится пока браузер открыт, иногда уносит свободную heap до ~12 КБ. Пустой левый сайдбар Web UI — следствие.

Лечение (одна строка): web_server: log: false — Debug Log панель в браузере исчезает, state-events идут штатно. Для atomfast_gateway.yaml это default.

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

• ⭐ ESP32-S3-DevKitC-1 N16R8 (16 МБ Flash + 8 МБ embedded octal PSRAM, U.FL/IPEX, USB-C) → esp32-s3-devkitc/atomfast_gateway_s3.yaml (esp-idf, 640/32, log:true). Рекомендованная актуальная конфигурация. Внешняя антенна через IPEX повышает дальность BLE до прибора, embedded octal PSRAM решает INC-05, S3-чип развязывает coex. Подтверждено приборным прогоном на самом AtomFast (2026-06-25): живая S3-плата отработала ≈ 96 ч (≈ 4 суток) непрерывно, 0 ребутов, BLE-сессии многочасовые (последняя — 5.6 ч на момент съёмки, реконнектов всего 12 за 4 суток), все сенсоры публикуют, web_server без json:111 при log:true. Лог прогона: references/run-logs/atomfast-s3-soak-2026-06-25.md. Это снимает прежнюю оговорку «перенос гипотезы с Radex-S3» — тезис «S3 решает INC-09/12» теперь подтверждён на AtomFast напрямую.
• Классический ESP32-DevKitC v4 (WROOM-32, 4 MB flash, без PSRAM) → esp32-classic/atomfast_gateway.yaml (arduino, 600/180, log:false). Работает только на arduino-baseline. С esp-idf на этой плате — INC-09 (rsn 0x3e, медленные коннекты) и INC-12 (Auth Expired). Имеет смысл, только если плата уже есть на руках и не хочется покупать S3.
• ESP32-C3 SuperMini (4 МБ Flash, 400 КБ SRAM, без PSRAM, single-band 2.4 ГГц, ≈ 22×18 мм) → esp32-c3-supermini/atomfast_gateway_c3.yaml (arduino + NimBLE, 1024/16, log:false). Compile PASS, smoke у клиента pending. Flash занят на 92.3 % (узкий запас 142 KB) — рост Web UI требует кастомный partition CSV. Подходит для носимых / mini-шлюзов где габариты критичнее запаса памяти. Не пытайся прошить S3 YAML на C3 — INC-C3-001 (ENOSPC, 16 MB partition на 4 MB Flash).
• ESP32-S3 без PSRAM или дешёвая клон-плата с QSPI вместо octal → меняй psram: mode: octal на quad или убирай блок целиком; ставь web_server: log: false. Лучший вариант — взять оригинальную N16R8 от Espressif.

Не ставь esp-idf на классический DevKitC. Реконнекты будут хуже, чем на arduino, а проблема в BLE/WiFi coex и нехватке RAM — её на этой плате не починить.

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

• MTU 23 — AtomFast не отвечает на запрос увеличения MTU; payload 13 байт всё равно влезает.
• Один прибор на ESP — в текущей версии. ESP32 поддерживает до 3 BLE-клиентов одновременно, см. ветку multi-device (TODO).
• Service UUID и формат payload валидны для семейства AtomFast Plus2; на старых моделях (Plus, обычный) формат может отличаться — pull request с реверсом приветствуются.
• gatt_dump.h помощник показывает «count=0» через esp_ble_gattc_get_attr_count даже когда ble_client уже подписан — известный баг, не влияет на работу основной прошивки.

MIT, см. корень репозитория.

• AtomFast ( КБ Радар) — отличный карманный дозиметр.
• Am6er/atomswift (приватный репо) — авторитетный источник GATT-карты и формулы парсинга on-air payload.
• ESPHome — лучший фреймворк для ESP32 в нашей вселенной.
• Глубинный реверс протокола: skill atomfast-tester в этом же репо.