10 · Устранение неполадок
Руководство по отладке компонента rbamp в ESPHome по симптомам. Каждая запись имеет одинаковую структуру: что вы видите в журнале, что это значит, как диагностировать и конкретное исправление.
Contents:
- I2C / аппаратная часть
- Качество данных
- Энергия и сохранение
- Интеграция с Home Assistant
- Сборка и инструментарий
- Идентичность / возможности / ошибки (v1.3)
1. I²C / аппаратная часть
Probe failed at 0x50 — нет ответа
Что вы видите в журнале:
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.
Компонент затем вызывает mark_failed() и прекращает дальнейшие вызовы update(). Все привязанные датчики остаются «Unknown» в Home Assistant.
Что это значит:
ESP32 отправил фазу адреса на 0x50 (или другой адрес из address:) и не получил ACK. Модуль либо отсутствует, либо не запитан, либо находится на другом адресе.
Как диагностировать:
-
Убедитесь, что
scan: trueзадан в YAML-блокеi2c:. Перезагрузите ESP32 и смотрите на:Text[I][i2c.arduino:069]: Found i2c device at address 0x50Если сканирование нашло устройство, ключ
address:в вашем блокеrbamp:неверен — обновите его. -
Измерьте питание на выводе VCC модуля мультиметром: должно быть 4.5..5.5 В (номинально 5 В, см. 04_hardware.md). Ноль или ниже 4.5 В означает, что питания нет или оно нестабильно.
-
Проверьте непрерывность SDA и SCL от GPIO ESP32 до разъёма модуля. Отсутствующий или перепутанный провод — самая частая причина в новых сборках.
-
Проверьте подтягивающие резисторы на SDA и SCL (4.7 кОм к 3.3 В). Без подтяжки шина лежит на низком уровне, и каждая фаза адреса выглядит как NACK.
-
Если вы недавно меняли адрес (ключ
new_address:), модуль может теперь находиться на новом адресе. Добавьтеscan: true, найдите устройство, соответственно обновитеaddress:и удалитеnew_address:.
Исправление: исправьте подключение / питание и обновите address:, если модуль сместился. Если модуль не отвечает после смены адреса, см. ниже раздел «Адрес изменён, но модуль не отвечает».
Блок RT не готов — публикация пропущена
Что вы видите:
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish
Что это значит: регистр состояния сообщил, что модуль не готов. Это происходит, когда модуль ещё не зафиксировал первый блок мгновенных значений после старта, находится в записи во флеш или в мягком сбросе.
Как диагностировать:
-
Если запись появилась однократно при загрузке (в первые 30 с после включения) и затем пропала, это нормально. Модулю нужен один цикл фиксации (~100 мс), чтобы установить бит READY после включения. Стартовый снимок в
setup()тоже даёт один пропущенный цикл. -
Если сообщения идут непрерывно после прогрева, модуль может зависнуть. Проверьте повторяющиеся записи
ct_model:/ct_models:(например, ключ, оставленный в YAML и записываемый при каждой загрузке, создаёт постоянное окно записи во флеш). -
Если сообщение появляется изредка (раз в несколько циклов), это обычная изменчивость, связанная с NACK. Цикл повторов перехватывает большинство сбоев; иногда чтение статуса всё равно не удаётся, и это вызывает запись DEBUG.
Fix:
- Пропуски при разогреве после загрузки ожидаемы; подождите два полных цикла
update_interval. - Если
ct_model:/ct_models:задан в YAML, оставьте его: при каждой загрузке повторная запись идемпотентна (модуль не пишет, если значение уже во флеше). Если прогрев мешает, закомментируйте ключ после успешного первого запуска. - Если модуль остаётся не готовым 60+ с, выключите питание модуля (не ESP32) для чистого холодного старта.
"rbamp took a long time for an operation (XXX ms)"
Что вы видите:
[W][component:522]: rbamp took a long time for an operation (406 ms), max is 30 ms
Что это значит: это предупреждение срабатывает, когда update() любого компонента превышает бюджет 30 мс по умолчанию у кооперативного планировщика ESPHome. Для компонента rbamp это ожидаемо и безвредно.
На прошивке v1.3 поддерживается автоинкремент READ для блока мгновенных значений (непрерывный диапазон, охватывающий U / I / P / PF / Q для всех объявленных каналов). Компонент выполняет одно пакетное чтение этого блока — одна фаза адреса и затем ~36 байт данных — что стоит ≈ 8–10 мс времени на шине при 50 kHz. Автоинкремент WRITE не поддерживается, поэтому отдельные записи в регистры (постановка модели CT, класс датчика, фиксация адреса) по-прежнему идут побайтно. Если пакетное чтение не удаётся (NACK на середине, бит возможности не установлен на старой прошивке), компонент переходит к чтению отдельных регистров (4 транзакции на float, до 36 транзакций ≈ 90 мс при 50 kHz). С учётом тройного повтора на байт (до 3 × 5 мс задержки при цикле с большим числом NACK) наихудший путь отката обычно занимает 300–450 мс — именно это и вызывает данное предупреждение.
Ожидание стабилизации снимка (set_timeout("rbamp_period", 50, ...)) — неблокирующее: update() передаёт управление планировщику, пока проходят 50 мс. Предупреждение отражает фактическое время всего блокирующего чтения мгновенных значений, а не голодание Wi-Fi или API.
Действий от пользователя не требуется. Предупреждение косметическое; сенсоры HA обновляются корректно. На исправных модулях v1.3 путь пакетного чтения обычно укладывается в 30 мс, и предупреждение вообще не срабатывает.
Если предупреждение срабатывает на каждом цикле: шина принудительно переходит на чтение по регистрам (прошивка без возможности пакетного чтения или пограничные подтяжки, дающие NACK в середине пакета). Проверьте версию прошивки (Firmware version: 0x04 в журнале загрузки = v1.3) и топологию подтяжек (одна пара 4.7 кОм к чистым 3.3 В).
Не удалось прочитать снимок периода
Что вы видите:
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]
Что это значит: после команды снимка и 50 мс ожидания компонент не смог прочитать регистр средней мощности периода для канала N после трёх повторов. Накопитель энергии этого канала в данном цикле не обновляется.
Наиболее частые причины:
- Провал на время записи во флеш. Модуль записывает модель ТТ (по
ct_model:илиct_models:при загрузке) или сохраняет новый адрес. Окно ~700 мс; если 50-мс ожидание снимка попадёт в него, чтение истечёт по таймауту. - Пропущенный снимок при интенсивном опросе. При интенсивных последовательных опросах I²C сторона модуля может пропустить снимок. Снимок остаётся пустым, но флаг valid будет 0 — компонент пропускает интеграцию с сообщением «Period snapshot not yet valid; keeping previous integration window». Предупреждение срабатывает только тогда, когда флаг valid установлен, но чтение регистра всё равно не удалось.
- Исчерпание переходных NACK. Все три повтора на хотя бы одном из четырёх байтов float не удались. Редко при 50 kHz (< 1% циклов); чаще при 100 kHz.
Что происходит с энергией: при предупреждении last_latch_ms_ не обновляется. При следующем успешном цикле dt_ms охватывает и пропущенное окно, и новое — энергия восстанавливается при условии, что нагрузка примерно стабильна на интервале. Это допустимая небольшая погрешность.
Fix:
- Удалите ключи смены адреса (
new_address:) из YAML после первой успешной загрузки. - Если предупреждение срабатывает чаще раза в час, проверьте скорость шины (рекомендуется
50kHz) и подтягивающие резисторы (4.7 kΩ). - Если предупреждение срабатывает на каждом цикле, проверьте конфликт с другим устройством на шине.
Адрес изменён, но модуль не отвечает
Что вы видите:
[E][rbamp:xxx]: Address change applied but slave not responding at 0x51 —
check wiring and try power-cycling the rbAmp.
[E][component:xxx]: Component rbamp was marked as failed.
Что это значит: процедура смены адреса прошла все шаги (запись нового адреса, сохранение во флеш, мягкий сброс, переключение внутреннего адреса I²C компонента), но при первой проверке модуль не ответил на новом адресе.
Возможные причины:
- Адрес был записан и сохранён, но модуль оказался в плохом состоянии (повреждение параметров во флеше, сбой питания во время окна записи 700 мс).
- На устаревшей прошивке (v1.0-v1.2): модуль не находился в режиме заводского провизионирования в момент попытки. На прошивке v1.3+ эта причина неприменима (двухфазная фиксация пригодна для производства). Если само чтение статуса режима не удалось (NACK), компонент выполняет запись спекулятивно, с предупреждением в логе.
- Проблема с проводкой, существовавшая до смены адреса (проверка старого адреса прошла только случайно на одной из трёх попыток).
Процедура восстановления:
- Модуль на неизвестном адресе. Используйте тестовый YAML с
i2c: scan: trueи перезапуском питания — выясните, на каком адресе отвечает модуль. - Если модуль найден по новому адресу (например, 0x51), обновите YAML на
address: 0x51, удалитеnew_address:и прошейте заново. Следующая загрузка пройдёт чисто. - Если модуль не отвечает ни на одном адресе, запись во флеш могла повредить параметры. Восстановление требует физического вмешательства: обратитесь к документации модуля или к поставщику.
Справка: процесс смены адреса на прошивке v1.3 — двухфазная фиксация: мастер записывает новый адрес в промежуточный регистр, затем выдаёт CMD_COMMIT_ADDR, чтобы сделать его постоянным. Окно записи 700 мс — это стирание и программирование страницы пользовательской конфигурации во флеше. См. 09 · Справочник API.
i2c_master завис — цикл перезагрузки ESP32 или блок RT никогда не публикуется
Что вы видите:
[I][i2c.idf:xxx]: Performing I2C bus reset...
[E][i2c.idf:xxx]: i2c_master_send_buf failed: ESP_ERR_TIMEOUT
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.
В худшем случае тайм-аут сторожевого таймера задач перезагружает ESP32 через несколько минут прогона (под нагрузкой, а не при вводе в эксплуатацию). Это может выглядеть как «модуль работал час, а потом остановился».
Что это значит: у драйвера ESP-IDF v5 i2c_master есть известная проблема: на пограничной шине (медленный фронт, слабая подтяжка, всплеск EMI) внутренняя функция i2c_ll_is_bus_busy зацикливается бесконечно, ожидая условие STOP, которое не приходит. В ESPHome 2025.x это зацикливание может съесть бюджет app-WDT и вызвать перезагрузку. Это каноническая проблема ESP-IDF, а не специфика rbAmp.
Трёхуровневое смягчение (все активны в компоненте по умолчанию, плюс рекомендации по железу):
-
Программная часть: встроенная дисциплина NACK — 50 кГц по умолчанию + 3× повтор на байт с паузой 5 мс + фильтр корректности IP-009
std::isfinite(). Уже в компоненте с v0.2+. Исправление обработчика остановки вошло в прошивку v1.1/v1.3, но 50 кГц по-прежнему рекомендуется на мастерах ESP-IDF, так как взаимодействие драйвера по времени сохраняется. -
Аппаратура: внешняя подтяжка 4.7 kΩ на SDA + SCL (одна внешняя пара подтяжек при вырезанных перемычках в модуле — см. §Шина с несколькими модулями). Внутренние подтяжки ESP32 (~50 kΩ) слабые — на длинной шине или при сомнительном питании их недостаточно. Подтяжки 4.7 kΩ к чистым 3.3 V обязательны для промышленной установки.
-
Аппаратно: не удерживайте отладчик / сброс OTA в активном состоянии во время транзакций I²C. RESET, поданный посреди транзакции, оставляет шину зависшей (ведомый продолжает тянуть SDA) — именно это и вызывает бесконечное зацикливание «шина занята».
Частота зависаний, наблюдавшаяся в 24-часовом тесте на выносливость:
| Слой | Частота зависаний | Примечание |
|---|---|---|
| Только программно (без внешнего подтягивания) | ~1 раз в 10 минут | сторожевой таймер моста срабатывает и восстанавливается перезагрузкой, но Вт·ч теряет одно окно |
| Программно + внешняя подтяжка 4.7kΩ | ~1 раз в 24 часа | Крайний случай всплеска EMI; автовосстановление |
| Программно + внешняя подтяжка + чистый сброс | 0 зависает при 24-часовом тесте | целевая платформа производства |
Серьёзность = время измерения (прогон на полную длительность), а не ввод в эксплуатацию. При вводе дисциплина NACK ловит 99%+ через тройной повтор — реальные зависания начинаются только после часов чистого прогона. Полный справочник дисциплины — в 09 · Справочник API.
: как крайнюю меру настройте wdt: (ядро esphome) с увеличенным app_wdt_timeout_seconds: (по умолчанию 5 с; задайте 10–15 с). Это даёт время на восстановление компонента без перезагрузки.
2. Качество данных
Напряжение скачет — 228 V / 502 V / 1.96 V вперемешку
Что вы видите:
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 1.964 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 228.365 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
В Home Assistant график напряжения — пилообразный между ~228 В, ~2 В и ~503 В. Ток может одновременно показывать 0 А или −2 А.
Что это значит: «призрачные» значения появляются из-за утечки буфера в драйвере ESP-IDF i2c_master при условиях NACK на 100 кГц. Это должно устраняться настройкой по умолчанию текущей версии компонента. Если симптом появился:
- Блок
i2c:имеетfrequency: 100kHz— измените на50kHz. - Версия компонента старше 2026-05-24 — обновите её.
Fix:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # required for reliable operation
scan: true
О механизме дисциплины NACK (50 kHz по умолчанию + повтор по байтам + санитарный фильтр для NaN/Inf) см. 09 · Справочник API.
Совместимость с framework: type: — проблема призрачных значений из-за NACK проявляется только при драйвере ESP-IDF i2c_master. На framework: type: arduino (по умолчанию) используется стек Arduino Wire, который ведёт себя иначе при NACK и этот симптом не воспроизводит. Это означает:
- Если в YAML указано
esp32: framework: type: arduino, теоретически можно оставитьfrequency: 100kHzбез заметных призрачных выбросов, но цикл повторов компонента по байтам всё равно работает поверх Wire, и периодические NACK на 100 kHz сохраняются — пропадают лишь призрачные значения. Для стабильных графиков в HA мы рекомендуем 50 kHz независимо от фреймворка. - Если в YAML указано
esp32: framework: type: esp-idf, тоfrequency: 50kHzобязательна. Именно в этой конфигурации драйверi2c_masterпроявляет призрачный симптом наиболее ярко.
Сам компонент не выбирает фреймворк — он работает поверх обоих. Это чисто решение в вашем YAML.
Ток постоянно 0 A под нагрузкой
Что вы видите:
[D][sensor:xxx]: 'Mains Current': Sending state 0.000 A
Мощность 0 Вт, энергия не растёт, но напряжение читается верно (например, 228 V).
Что это значит: одна из двух типичных причин:
Причина 1 — ct_model: не задан или не совпадает с физической клипсой. На прошивке v1.2+ модуль использует заводские коэффициенты для модели, выбранной в YAML. Если ct_model: не задан или задан, например, SCT_013_050 при реальной SCT-013-005, диапазон измерения во много раз шире физического сигнала, модуль не может его разрешить и выдаёт ноль.
Причина 2 — клипса установлена неверно на проводнике (см. полярность в 03_sensor_selection.md и охват только одного проводника).
Как диагностировать:
- Убедитесь, что клещи физически надеты на токоведущий проводник и что по нему действительно идёт ток (при наличии используйте токовые клещи-амперметр как эталон).
- Откройте YAML и проверьте, что
ct_model:(илиct_models:для UI3) соответствует физической модели клипсы. - Если
ct_model:задан на прошивке v1.2+, аsensor_class:пропущен или задан значением, отличным отSCT_013, модуль отклоняет запись модели. В журнале загрузки появится предупреждение с указанием отсутствующего условия.
Fix:
rbamp:
id: meter1
sensor_class: SCT_013 # default; required on v1.2+ before ct_model
ct_model: SCT_013_005 # match the physical clamp
После загрузки модуль однократно записывает модель во флеш (~700 мс) и загружает заводские коэффициенты. Следующая публикация мгновенных значений уже даёт корректный ток.
Точность измерения малых токов на UI2 / UI3 — схема двойного CT. Если нужно одновременно высокое разрешение на малых нагрузках (освещение, режим ожидания) и широкий диапазон для пиков (чайник, стиральная машина), используйте два токовых канала на одной фазе одновременно с разными клещами:
rbamp:
id: home_meter
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
# CH0 — SCT-013-005 for resolving idle loads (~5..50 W)
# CH1 — SCT-013-030 for the main household load (~50..7000 W)
# CH2 — SCT-013-050 for the peak (EV-charging headroom up to 11.5 kW)
# For peaks above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A) on that channel
Все три клеща охватывают один и тот же проводник фазы L. SCT-013-005 даёт ~10× лучшее разрешение на малых токах, чем SCT-013-030, но насыщается при ~5 А. SCT-013-030 покрывает «середину» полезного диапазона; SCT-013-050 ловит пиковые всплески до ~11.5 кВт без насыщения. На стороне HA шаблонный датчик выбирает «активное» измерение по порогу:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в YAML узла.
# configuration.yaml — select the active channel by range
template:
- sensor:
- name: "Mains Current (active)"
unit_of_measurement: "A"
device_class: current
state_class: measurement
state: >
{% set i0 = states('sensor.rbamp_ch0_current') | float(0) %}
{% set i1 = states('sensor.rbamp_ch1_current') | float(0) %}
{% set i2 = states('sensor.rbamp_ch2_current') | float(0) %}
{% if i2 > 25 %}{{ i2 }}
{% elif i1 > 4 %}{{ i1 }}
{% else %}{{ i0 }}
{% endif %}
Это покрывает диапазон от наименьшего до наибольшего номинала трёх клещей (5 А … 50 А). Компромисс: три токовых клеща на одном проводнике физически громоздки, и каждый занимает один канал модуля (на UI3 — весь модуль). Для большинства установок один клещ с номиналом под нагрузку покрывает 99% сценариев — схема двойного/тройного CT нужна только при необходимости широкого динамического диапазона.
Снимок периода недействителен — энергия не растёт
Калибровка и точность (troubleshooting) · 7.5 Сохранение периода при неудачном снимке (api-reference)
Что вы видите:
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window
Датчик energy в Home Assistant показывает постоянное значение (или остаётся на 0 Вт·ч после загрузки), хотя мощность читается правильно.
Что это значит: флаг валидности снимка периода был 0, когда компонент проверил его через 50 мс после команды снимка. Модуль ещё не зафиксировал действительный снимок периода.
Обычные причины:
- Первый снимок после загрузки. Стартовый снимок в
setup()всегда отбрасывает свой результат — накопитель модуля сбрасывается по первой команде снимка. Второй снимок (через одинupdate_intervalпосле загрузки) — первый, который интегрируется. Энергия начинает накапливаться после первого полногоupdate_intervalот загрузки. - Холодный старт модуля. Модулю нужен как минимум один цикл фиксации ~100 мс, чтобы данные появились в накопителе периода. Если первый снимок происходит раньше, флаг валидности равен 0.
- Пропущенный снимок при интенсивном опросе. При высокой нагрузке I²C сторона модуля может пропустить снимок. Снимок остаётся пустым; следующий снимок должен пройти успешно.
Если запись срабатывает на каждом цикле update() бесконечно (а не только на первые два), модуль может находиться в состоянии, где накопитель периода никогда не фиксируется. Перезапуск питания модуля сбрасывает это состояние.
3. Энергия и сохранение
Счётчик энергии сбрасывается в 0 после перезагрузки
Энергия берётся из собственных счётчиков модуля и дополнительно сохраняется во флеш ESP32 (NVS), поэтому перезагрузка ESP32 или модуля её не сбрасывает, и итоги не откатываются назад. Если датчик STANDARD всё равно стартует с 0, причина — стирание NVS (стирание флеша, изменённая таблица разделов) и одновременный сброс счётчика в модуле. Датчики суммарного итога (energy_total, energy_exported_total, energy_net, reactive_energy*) используют собственный слот NVS, отдельный от слотов energy по каналам, поэтому обновление компонента не очищает значения по каналам.
Что вы видите на панели энергии HA: резкий спад до 0 Вт·ч, затем нормальное накопление с 0. Старая история Вт·ч сохраняется в долгосрочной статистике HA, но «текущее показание счётчика» выглядит сброшенным.
Что это значит: при восстановлении из NVS данных не найдено или загружены некорректные данные. Возможные причины:
- Повышение версии раскладки NVS. Ключ NVS выводится из ID компонента, XOR-ом с константой версии раскладки. Если структура изменилась (при обновлении компонента), ключ слота меняется и старые данные не находятся. Восстановление тихо начинается с 0.
- Фрагментация или повреждение NVS. Раздел NVS на ESP32 использует выравнивание износа флеша. На очень старых установках или после многих прошивок фрагментация может сделать сохранение неудачным. В логе:
[W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle. - Изменение разметки разделов. Прошивка нового
partitions.csv, который меняет размер или расположение разделаnvs, обнуляет все сохранённые значения. - Первая загрузка после сброса к заводским настройкам или полного стирания флеша. Ожидается: NVS пуст, накопитель начинается с 0.
Как диагностировать:
В журнале загрузки ищите:
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh
Если присутствует, восстановление ничего не нашло. Также:
[C][rbamp:xxx]: Restored Wh from NVS: total[0.310, 0.000, 0.000] export[...]
Если восстановленное значение заметно ниже ожидаемого, последнее сохранение NVS за 5 минут могло быть пропущено (наихудшая потеря: ≈ 5 Вт·ч при средней нагрузке 60 Вт).
Fix:
- При обновлении компонента, которое меняет разметку NVS, старые итоги автоматически не восстанавливаются. Долгосрочная статистика HA сохраняет историю, даже если «текущее показание» обнулилось.
- Чтобы сохранить Вт·ч при принудительном стирании NVS, перед стиранием снимите текущие показания датчиков в HA (Developer Tools) и запишите их. Ввести стартовое значение в компонент нельзя.
Энергия в HA не совпадает с эталонным счётчиком
Что вы видите: датчик energy в HA заметно занижен (например, на 10–20%) по сравнению с эталонным умным счётчиком или коммунальным счётчиком за тот же период.
Что это значит: на модулях BASIC компонент интегрирует среднюю мощность периода за время между командами снимка по часам ESP32. На модулях STANDARD он накапливает собственные счётчики энергии модуля.
Если энергия занижена, проверьте следующее:
- Характер нагрузки. Регистр средней мощности за период — действительно усреднённая по времени мощность за закрытый период, а не мгновенное значение. Импульсная нагрузка (мотор, компрессор) с коротким временем включения внутри 60-секундного периода даёт среднее значение ниже своей пиковой мощности.
- Размещение клещей и калибровка нагрузки (burden). Если заводская модель ТТ (
ct_model:) не соответствует реальности, диапазоны коэффициентов будут смещены. Убедитесь, чтоct_model:в YAML соответствует физическим клещам на проводнике. - Уровень прошивки BASIC. На артикуле BASIC выборки P по каждому окну принудительно приводятся к 0 до интеграции. Если нагрузка имеет рекуперативную составляющую (например, насос с обратной ЭДС), BASIC занижает учёт.
4. Интеграция с Home Assistant
HA показывает «Unavailable» для всех датчиков rbamp
Что вы видите в HA: все сущности sensor.rbamp_* показывают «Unavailable».
Причины и исправления:
- ESP32 офлайн. Выполните
esphome logs --device— если не удаётся подключиться, ESP32 офлайн. Проверьте учётные данные WiFi и резервную точку доступа, если она настроена. -
Потеряно соединение API. Нативный API ESPHome (порт 6053) может блокироваться файрволом. Проверьте, что ESP32 доступен по IP:
ShellpingЕсли ping проходит, а HA всё ещё показывает unavailable, интеграцию ESPHome в HA нужно удалить и добавить заново (Настройки → Интеграции → ESPHome → Удалить, затем обнаружить заново).
-
Несовпадение ключа шифрования API. Если в YAML задан
api: encryption: key:, интеграция HA должна знать тот же ключ. Несовпадение заставляет HA считать устройство офлайн. Удалите и заново добавьте интеграцию после обновления ключа. - mDNS не работает в вашей сетевой топологии. Если ESP32 находится в другом VLAN, чем HA, multicast mDNS может не пересечь границу. Добавьте устройство по IP вручную в интеграции ESPHome.
Прошивка OTA не удаётся
Что вы видите:
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed
Частые причины:
- IP-адрес изменился. ESP32 получил новую аренду DHCP. Проверьте таблицу DHCP роутера, найдите устройство по MAC и назначьте статический IP или используйте ключ YAML
wifi: use_address:. -
ESP32 находится в безопасном режиме. После трёх неудачных загрузок подряд ESPHome переходит в безопасный режим (без пользовательских компонентов, только Wi-Fi + OTA). OTA в безопасном режиме работает, но устройство запущено на урезанной прошивке. Маркер в
esphome logs:Text[I][safe_mode:xxx]: Entering safe modeПринудительная чистая загрузка: удерживайте кнопку BOOT при включении или добавьте
safe_mode: num_attempts: 10, чтобы расширить порог. -
Порт 3232 (OTA) заблокирован. Протокол OTA использует TCP 3232. Проверьте, что ни одно правило файрвола не блокирует его между машиной, на которой запущен
esphome run(или хостом HA), и IP-адресом ESP32. - Слишком большая прошивка после добавления rbamp. Первый OTA после добавления внешнего компонента может превысить размер раздела OTA на стандартной разметке ESP32 4 MB. Проверьте вывод
esphome compileна предупреждения о размере бинарника и при необходимости переключитесь на разметку с большим разделом OTA.
OTA сразу после провизионирования new_address: не загружается
Симптом: после успешной первой загрузки с ключом new_address: (лог показывает Address change SUCCESS, new address 0x51) следующий OTA падает с ошибкой сборки или предупреждением времени выполнения address 0x50 NACK.
Что произошло: модуль теперь находится на новом адресе (0x51), но YAML всё ещё указывает на старый (address: 0x50). При следующем update() компонент пробует 0x50, ничего не получает и пишет постоянные NACK. Сам OTA здесь не падает — это сопутствующий симптом: в esphome logs идёт поток ошибок rbamp, и отсюда ложный вывод, что устройство сломано.
Восстановление в 3 шага:
-
Отредактируйте YAML:
YAMLrbamp: id: meter1 address: 0x51 # new address — set instead of 0x50 # new_address: 0x51 # ← REMOVE this line. Do not comment it out, # delete it entirely, otherwise the component # tries to provision again and logs a warning update_interval: 60s ct_model: SCT_013_030 -
Выполните
esphome run(через CLI) или Compile + Upload (через надстройку HA). Узел получает новый бинарник по Wi-Fi через OTA. -
Откройте
esphome logsи убедитесь, что сообщение запускаdump_configпоказывает верный адрес и чтоupdate()выполняется без NACK.
Правило — new_address: — это однократная операция провизионирования. Когда модуль перешёл на новый адрес и сохранил его во флеш, ключ нужно удалить из YAML. Иначе при каждой загрузке компонент будет пытаться провизионировать снова (на v1.2+ модуль игнорирует повторную запись, но предупреждение остаётся в логе и засоряет notify в HA).
Если модуль не отвечает ни на одном адресе после смены, см. «Адрес изменён, но модуль не отвечает» выше.
5. Сборка и инструментарий
Ошибка сборки: 'esphome/core/component.h' file not found
Что вы видите в VS Code / clangd: красные волнистые подчёркивания везде в rbamp.h и rbamp.cpp. Всплывающее окно:
'esphome/core/component.h' file not found
Что это значит: clangd (C++ IntelliSense в VS Code) не имеет доступа к путям включаемых файлов ESPHome + PlatformIO. Система сборки разрешает их корректно при esphome compile; clangd — нет.
Это не ошибка сборки. Если esphome compile example/ui1.yaml проходит без ошибок, код корректен.
Если нужно убрать красные волнистые подчёркивания: создайте файл .clangd в каталоге компонента, указывающий на сгенерированные пути включаемых файлов из вывода сборки ESPHome (.esphome/build/). Это косметика и не обязательно.
PlatformIO падает с 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)
Что вы видите:
Error: Failed to install Python dependencies (exit code: 3221225501)
(0xC0000001D = 3221225501 в десятичной записи)
Что это значит: PlatformIO 6.1.19+ использует бинарный файл uv (Rust) для установки зависимостей Python во внутреннее окружение penv. На некоторых новых процессорах Intel для ноутбуков uv падает с EXCEPTION_ILLEGAL_INSTRUCTION из-за несовместимости набора инструкций. Это затрагивает шаг penv_setup.py install при первой установке PlatformIO.
Обходной путь (предустановите все зависимости через pip, минуя uv):
# Step 1: install the ESP32 platform's Python dependencies directly
& "$env:USERPROFILE\.platformio\penv\Scripts\python.exe" -m pip install `
"littlefs-python>=0.16.0" "fatfs-ng>=0.1.14" "pyyaml>=6.0.2" `
"rich-click>=1.8.6" "zopfli>=0.2.2" "intelhex>=2.3.0" "rich>=14.0.0" `
"cryptography>=45.0.3" "certifi>=2025.8.3" "ecdsa>=0.19.1" `
"bitstring>=4.3.1" "reedsolo>=1.5.3,<1.8" "esp-idf-size>=2.0.0" `
"esp-coredump>=1.14.0" "pyelftools>=0.32"
# Step 2: bootstrap the nested ESP-IDF venv (see the next entry)
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m ensurepip --default-pip
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m pip install -r `
"$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"
После установки этих пакетов get_packages_to_install() в penv_setup.py возвращает пустой список, и pip через uv не вызывается. Последующие esphome compile работают штатно.
Обходной путь нужно применять заново после свежей установки PlatformIO или очистки кэша ~/.platformio.
venv ESP-IDF: модуль idf_component_manager отсутствует
Что вы видите:
ModuleNotFoundError: No module named 'idf_component_manager'
Появляется при первом esphome compile на машине, где PlatformIO загрузил фреймворк ESP-IDF, но не выполнил полную начальную настройку его зависимостей.
Что это значит: фреймворк PlatformIO ESP-IDF установлен во вложенное окружение ~/.platformio/penv/.espidf-5.5.4/ (номер версии может отличаться). Этому окружению нужен requirements.core.txt из пакета фреймворка. Когда применён обходной путь uv выше, шаг 2 загружает pip в окружение и устанавливает требования.
Если ошибка появилась после применения обходного пути uv, но шаг 2 был пропущен:
# Find the IDF venv (the version number may differ):
ls "$env:USERPROFILE\.platformio\penv\" | Where-Object { $_.Name -like ".espidf-*" }
# Bootstrap pip into the IDF venv:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m ensurepip --default-pip
# Install the IDF core requirements:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m pip install -r `
"$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"
Подставьте номер вашей версии IDF вместо 5.5.4 (см. ~/.platformio/penv/).
esphome compile падает: get_object_id_hash не найден
Что вы видите:
error: 'class esphome::rbamp::RbAmpComponent' has no member named 'get_object_id_hash'
Что это значит: старая версия rbamp.cpp вызывала this->get_object_id_hash(), чтобы задать слот NVS. Этот метод удалён из PollingComponent в ESPHome 2025.x.
Исправление: обновите компонент до текущей версии. Современный код использует генерацию хешей, совместимую с ESPHome 2025.x и новее.
ESPHome слишком старый — set_i2c_address не найден
Что вы видите:
error: 'class esphome::i2c::I2CDevice' has no member named 'set_i2c_address'
Что это значит: процедура смены адреса new_address: вызывает i2c::I2CDevice::set_i2c_address(), которого нет в старом ESPHome.
Исправление: обновите до ESPHome 2025.3.0 или новее. Надстройка HA ESPHome Add-on сама следует за текущим релизом — рекомендуемый путь установки.
# If using a local Python venv:
pip install --upgrade esphome
6. Идентификация / возможности / ошибки (v1.3)
Этот раздел объясняет, что означают отдельные значения сущностей идентификации (шаблонный text_sensor через lambda:), битовая карта возможностей и коды REG_ERROR, добавленные в v1.3.
Чтение идентичности возвращает «UNK» / «UNREADABLE»
Что вы видите (template text_sensor):
text_sensor:
- platform: template
name: "Meter variant"
lambda: 'return id(my_meter).get_variant_str();' # → "UNK" in HA
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK
Что это значит:
-
"UNK"— компонент не смог прочитатьREG_HW_VARIANT(0x55) после всех повторов. Причины: модуль на устаревшей прошивке (v1.0–v1.1, до определения варианта) или пограничная шина I²C с исчерпанием NACK на этом регистре. -
"UNREADABLE"— чтение вернуло значение вне диапазона0x55..0x5A, за пределами допустимых кодов варианта. Это указывает на повреждение прошивки или коллизию сырых регистров (например, устаревший буфер).
Fix:
-
Если прошивка ниже v1.2, определение варианта недоступно.
text_sensorвсё равно публикуется; используйте подсказку на стороне YAML черезtopology:или переинициализируйте через шаблон HA. -
Если прошивка v1.3+ и шина пограничная, см. i2c_master hung.
Битовая карта CAPABILITY = 0x0000
Что вы видите:
text_sensor:
- platform: template
name: "Meter capability"
lambda: 'return id(my_meter).get_capability_hex();' # → "0x0000"
Что это значит: регистра возможностей на этой прошивке нет — он читается как 0 (стандартное поведение «регистр не реализован» в прошивке rbAmp). Это устаревшая прошивка v1.0–v1.2.
Поведение компонента: все функции, зависящие от возможностей прошивки (GC по всему парку, двухфазная фиксация адреса, save_user_config, clear_error), автоматически переходят на устаревший путь:
fleet_gc_enable: true→ предупреждение + пропуск (не объявлено прошивкой)new_address:→ однофазный запасной путь, требуется режим заводского провизионированияclear_error()→ откат на опкод вендора (по возможности)
Нулевая регрессия: существующие развёртывания v0.4.0 продолжают работать без изменений YAML или поведения. Это канон C5 — возможности, зависящие от прошивки, никогда не ломают устаревшее.
last_error_str() показывает "ERR_PARAM" после изменения ct_model: или sensor_class:
Что вы видите:
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)
get_last_error_str() → "ERR_PARAM".
Что это значит: прошивка отклонила записанное значение. Самые частые причины:
-
Код вне допустимого набора — для
SCT_013допустимые коды:{1, 2, 3, 4, 5, 6, 7}. -
Модель CT не входит в допустимый набор для класса — например,
WIRED_CT_1приsensor_class: SCT_013. См. таблицу по классам в 03_sensor_selection.md. -
Код 0 (UNSET) — попытка сбросить модель CT значением 0. Не поддерживается; для полного сброса используйте
dev.factoryReset().
Восстановление: вызовите id(my_meter).write_clear_error(); через службу YAML или через lambda: в on_boot:, чтобы сбросить REG_ERROR и бит3 EVENT_FLAGS. После этого можно повторить попытку с корректным значением.
api:
services:
- service: my_meter_clear_error
then:
- lambda: 'id(my_meter).write_clear_error();'
Изменение ct_model: / sensor_class: отклоняется (запись в журнале, без записи)
Что вы видите:
[W][rbamp:xxx]: ct_model refused: module is calibrated with its fitted sensor (class N) — ...
[W][rbamp:xxx]: sensor_class refused: module is calibrated with its fitted sensor (class N); ...
Что это значит: модуль откалиброван парой с собственным встроенным датчиком (WIRED_CT / BUILTIN_CT). Запись общего класса или модели заменит эту индивидуальную калибровку, поэтому компонент отказывает. Это защита записи, а не неисправность. Равное значение также никогда не записывается (для этого на уровне предупреждения ничего не выводится).
Исправление: удалите sensor_class: / ct_model: / ct_models: из YAML для такого модуля. Только если вы осознанно хотите общий пресет, задайте ct_model_force: true вместе с моделью, прошейте один раз и удалите обе строки после этого (схема отклоняет ct_model_force: без ключа модели).
ct_models: не поддерживается этим устройством (модуль STANDARD)
Что вы видите:
[W][rbamp:xxx]: ct_models: (per-channel) not supported by this device — it does not advertise persistent per-channel model storage ... Use the global `ct_model:` key. (Keys ignored.)
Что это значит: модуль не может сохранять модели по каналам при отключении питания, поэтому их запись молча откатилась бы. Компонент отказывает, а не теряет значение.
Исправление: используйте один ключ ct_model: для всех каналов.
Смена ct_model: перезапускает модуль однократно
На модулях SCT с прошивкой до 1.4.19 переключение на другой номинал завершается перезапуском модуля (сохранение, сброс, повторное определение). Лог показывает перезапуск и затем, что ток/мощность/энергия пересчитаны под новый номинал; датчики могут пропустить один update(). Это часть штатного процесса. Прошивка 1.4.20 и новее выполняет переключение на самом модуле, перезапуска не происходит. Если лог сообщает, что применённый коэффициент вне ожидаемого диапазона, компонент не масштабирует; проверьте, что ct_model: соответствует физически установленной клипсе.
Датчики суммарного итога / углов никогда не публикуют значения
Что вы видите (журнал загрузки):
[W][rbamp:xxx]: energy_total/energy_net/reactive_energy sensors need on-device energy counters, which this device does not advertise — they will never publish. Per-channel `energy:` keys still work ...
[W][rbamp:xxx]: voltage_angle_*/phase_sequence sensors need a newer device firmware — they will never publish on this device
Что это значит: подключённый модуль (или его прошивка) не предоставляет эти значения. Ключи проходят валидацию, но ничего не публикуется.
Исправление: используйте датчики по каналам energy: или обновите прошивку модуля.
start_current_ua: игнорируется
[W][rbamp:xxx]: start_current_ua: not supported by this device firmware — key ignored — модуль учитывает энергию при любом токе. Ключ действует только на модулях STANDARD со счётчиками энергии на устройстве. Значения, отличные от 0 или 10..2540 с шагом 10, отклоняются при esphome config.
update_interval отклонён
update_interval меньше 1s отклоняется схемой на этапе esphome config. latch_interval не должен быть короче update_interval.
EVENT_FLAGS bit3 (ERR_LATCH) — поведение повторной фиксации
Что вы видите: после clear_error() через несколько сотен миллисекунд bit3 в EVENT_FLAGS снова установлен (липкая повторная фиксация).
Что это значит: прошивочный канал durable-ошибок повторно фиксирует bit3 после сброса, если исходное условие ошибки не устранено. Так задумано — мастер мог пропустить первый сброс и не должен навсегда считать ошибку устранённой, если параметр всё ещё неверен.
Исправление: полное восстановление требует двух шагов:
- Устраните причину (замените неверный код модели CT, исправьте YAML).
write_clear_error()— этот вызов сбрасывает иREG_ERROR, и бит3EVENT_FLAGSодной операцией.
Если бит3 продолжает срабатывать повторно, параметр всё ещё неверен; перечитайте get_last_error_str(), чтобы точно узнать, что отклоняет прошивка.
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/10_troubleshooting.md (v1.9.1)