rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub

10 · Устранение неполадок

Дерево решений по неполадкам: симптом → быстрая проверка → действие

Руководство по отладке компонента rbamp в ESPHome по симптомам. Каждая запись имеет одинаковую структуру: что вы видите в журнале, что это значит, как диагностировать и конкретное исправление.

Contents:

  1. I2C / аппаратная часть
  2. Качество данных
  3. Энергия и сохранение
  4. Интеграция с Home Assistant
  5. Сборка и инструментарий
  6. Идентичность / возможности / ошибки (v1.3)

1. I²C / аппаратная часть

Probe failed at 0x50 — нет ответа

Что вы видите в журнале:

Text
[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. Модуль либо отсутствует, либо не запитан, либо находится на другом адресе.

Как диагностировать:

  1. Убедитесь, что scan: true задан в YAML-блоке i2c:. Перезагрузите ESP32 и смотрите на:

    Text
    [I][i2c.arduino:069]: Found i2c device at address 0x50
    

    Если сканирование нашло устройство, ключ address: в вашем блоке rbamp: неверен — обновите его.

  2. Измерьте питание на выводе VCC модуля мультиметром: должно быть 4.5..5.5 В (номинально 5 В, см. 04_hardware.md). Ноль или ниже 4.5 В означает, что питания нет или оно нестабильно.

  3. Проверьте непрерывность SDA и SCL от GPIO ESP32 до разъёма модуля. Отсутствующий или перепутанный провод — самая частая причина в новых сборках.

  4. Проверьте подтягивающие резисторы на SDA и SCL (4.7 кОм к 3.3 В). Без подтяжки шина лежит на низком уровне, и каждая фаза адреса выглядит как NACK.

  5. Если вы недавно меняли адрес (ключ new_address:), модуль может теперь находиться на новом адресе. Добавьте scan: true, найдите устройство, соответственно обновите address: и удалите new_address:.

Исправление: исправьте подключение / питание и обновите address:, если модуль сместился. Если модуль не отвечает после смены адреса, см. ниже раздел «Адрес изменён, но модуль не отвечает».


Блок RT не готов — публикация пропущена

Что вы видите:

Text
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish

Что это значит: регистр состояния сообщил, что модуль не готов. Это происходит, когда модуль ещё не зафиксировал первый блок мгновенных значений после старта, находится в записи во флеш или в мягком сбросе.

Как диагностировать:

  1. Если запись появилась однократно при загрузке (в первые 30 с после включения) и затем пропала, это нормально. Модулю нужен один цикл фиксации (~100 мс), чтобы установить бит READY после включения. Стартовый снимок в setup() тоже даёт один пропущенный цикл.

  2. Если сообщения идут непрерывно после прогрева, модуль может зависнуть. Проверьте повторяющиеся записи ct_model: / ct_models: (например, ключ, оставленный в YAML и записываемый при каждой загрузке, создаёт постоянное окно записи во флеш).

  3. Если сообщение появляется изредка (раз в несколько циклов), это обычная изменчивость, связанная с NACK. Цикл повторов перехватывает большинство сбоев; иногда чтение статуса всё равно не удаётся, и это вызывает запись DEBUG.

Fix:

  • Пропуски при разогреве после загрузки ожидаемы; подождите два полных цикла update_interval.
  • Если ct_model: / ct_models: задан в YAML, оставьте его: при каждой загрузке повторная запись идемпотентна (модуль не пишет, если значение уже во флеше). Если прогрев мешает, закомментируйте ключ после успешного первого запуска.
  • Если модуль остаётся не готовым 60+ с, выключите питание модуля (не ESP32) для чистого холодного старта.

"rbamp took a long time for an operation (XXX ms)"

Что вы видите:

Text
[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 В).


Не удалось прочитать снимок периода

Что вы видите:

Text
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]

Что это значит: после команды снимка и 50 мс ожидания компонент не смог прочитать регистр средней мощности периода для канала N после трёх повторов. Накопитель энергии этого канала в данном цикле не обновляется.

Наиболее частые причины:

  1. Провал на время записи во флеш. Модуль записывает модель ТТ (по ct_model: или ct_models: при загрузке) или сохраняет новый адрес. Окно ~700 мс; если 50-мс ожидание снимка попадёт в него, чтение истечёт по таймауту.
  2. Пропущенный снимок при интенсивном опросе. При интенсивных последовательных опросах I²C сторона модуля может пропустить снимок. Снимок остаётся пустым, но флаг valid будет 0 — компонент пропускает интеграцию с сообщением «Period snapshot not yet valid; keeping previous integration window». Предупреждение срабатывает только тогда, когда флаг valid установлен, но чтение регистра всё равно не удалось.
  3. Исчерпание переходных NACK. Все три повтора на хотя бы одном из четырёх байтов float не удались. Редко при 50 kHz (< 1% циклов); чаще при 100 kHz.

Что происходит с энергией: при предупреждении last_latch_ms_ не обновляется. При следующем успешном цикле dt_ms охватывает и пропущенное окно, и новое — энергия восстанавливается при условии, что нагрузка примерно стабильна на интервале. Это допустимая небольшая погрешность.

Fix:

  • Удалите ключи смены адреса (new_address:) из YAML после первой успешной загрузки.
  • Если предупреждение срабатывает чаще раза в час, проверьте скорость шины (рекомендуется 50kHz) и подтягивающие резисторы (4.7 kΩ).
  • Если предупреждение срабатывает на каждом цикле, проверьте конфликт с другим устройством на шине.

Адрес изменён, но модуль не отвечает

Что вы видите:

Text
[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 компонента), но при первой проверке модуль не ответил на новом адресе.

Возможные причины:

  1. Адрес был записан и сохранён, но модуль оказался в плохом состоянии (повреждение параметров во флеше, сбой питания во время окна записи 700 мс).
  2. На устаревшей прошивке (v1.0-v1.2): модуль не находился в режиме заводского провизионирования в момент попытки. На прошивке v1.3+ эта причина неприменима (двухфазная фиксация пригодна для производства). Если само чтение статуса режима не удалось (NACK), компонент выполняет запись спекулятивно, с предупреждением в логе.
  3. Проблема с проводкой, существовавшая до смены адреса (проверка старого адреса прошла только случайно на одной из трёх попыток).

Процедура восстановления:

  1. Модуль на неизвестном адресе. Используйте тестовый YAML с i2c: scan: true и перезапуском питания — выясните, на каком адресе отвечает модуль.
  2. Если модуль найден по новому адресу (например, 0x51), обновите YAML на address: 0x51, удалите new_address: и прошейте заново. Следующая загрузка пройдёт чисто.
  3. Если модуль не отвечает ни на одном адресе, запись во флеш могла повредить параметры. Восстановление требует физического вмешательства: обратитесь к документации модуля или к поставщику.

Справка: процесс смены адреса на прошивке v1.3 — двухфазная фиксация: мастер записывает новый адрес в промежуточный регистр, затем выдаёт CMD_COMMIT_ADDR, чтобы сделать его постоянным. Окно записи 700 мс — это стирание и программирование страницы пользовательской конфигурации во флеше. См. 09 · Справочник API.


i2c_master завис — цикл перезагрузки ESP32 или блок RT никогда не публикуется

Что вы видите:

Text
[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.

Трёхуровневое смягчение (все активны в компоненте по умолчанию, плюс рекомендации по железу):

  1. Программная часть: встроенная дисциплина NACK — 50 кГц по умолчанию + 3× повтор на байт с паузой 5 мс + фильтр корректности IP-009 std::isfinite(). Уже в компоненте с v0.2+. Исправление обработчика остановки вошло в прошивку v1.1/v1.3, но 50 кГц по-прежнему рекомендуется на мастерах ESP-IDF, так как взаимодействие драйвера по времени сохраняется.

  2. Аппаратура: внешняя подтяжка 4.7 kΩ на SDA + SCL (одна внешняя пара подтяжек при вырезанных перемычках в модуле — см. §Шина с несколькими модулями). Внутренние подтяжки ESP32 (~50 kΩ) слабые — на длинной шине или при сомнительном питании их недостаточно. Подтяжки 4.7 kΩ к чистым 3.3 V обязательны для промышленной установки.

  3. Аппаратно: не удерживайте отладчик / сброс 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 вперемешку

Что вы видите:

Text
[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:

YAML
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 под нагрузкой

Что вы видите:

Text
[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 и охват только одного проводника).

Как диагностировать:

  1. Убедитесь, что клещи физически надеты на токоведущий проводник и что по нему действительно идёт ток (при наличии используйте токовые клещи-амперметр как эталон).
  2. Откройте YAML и проверьте, что ct_model: (или ct_models: для UI3) соответствует физической модели клипсы.
  3. Если ct_model: задан на прошивке v1.2+, а sensor_class: пропущен или задан значением, отличным от SCT_013, модуль отклоняет запись модели. В журнале загрузки появится предупреждение с указанием отсутствующего условия.

Fix:

YAML
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. Если нужно одновременно высокое разрешение на малых нагрузках (освещение, режим ожидания) и широкий диапазон для пиков (чайник, стиральная машина), используйте два токовых канала на одной фазе одновременно с разными клещами:

YAML
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 узла.

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 нужна только при необходимости широкого динамического диапазона.


Снимок периода недействителен — энергия не растёт

Что вы видите:

Text
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window

Датчик energy в Home Assistant показывает постоянное значение (или остаётся на 0 Вт·ч после загрузки), хотя мощность читается правильно.

Что это значит: флаг валидности снимка периода был 0, когда компонент проверил его через 50 мс после команды снимка. Модуль ещё не зафиксировал действительный снимок периода.

Обычные причины:

  1. Первый снимок после загрузки. Стартовый снимок в setup() всегда отбрасывает свой результат — накопитель модуля сбрасывается по первой команде снимка. Второй снимок (через один update_interval после загрузки) — первый, который интегрируется. Энергия начинает накапливаться после первого полного update_interval от загрузки.
  2. Холодный старт модуля. Модулю нужен как минимум один цикл фиксации ~100 мс, чтобы данные появились в накопителе периода. Если первый снимок происходит раньше, флаг валидности равен 0.
  3. Пропущенный снимок при интенсивном опросе. При высокой нагрузке I²C сторона модуля может пропустить снимок. Снимок остаётся пустым; следующий снимок должен пройти успешно.

Если запись срабатывает на каждом цикле update() бесконечно (а не только на первые два), модуль может находиться в состоянии, где накопитель периода никогда не фиксируется. Перезапуск питания модуля сбрасывает это состояние.


3. Энергия и сохранение

Счётчик энергии сбрасывается в 0 после перезагрузки

модули STANDARD (STD).

Энергия берётся из собственных счётчиков модуля и дополнительно сохраняется во флеш ESP32 (NVS), поэтому перезагрузка ESP32 или модуля её не сбрасывает, и итоги не откатываются назад. Если датчик STANDARD всё равно стартует с 0, причина — стирание NVS (стирание флеша, изменённая таблица разделов) и одновременный сброс счётчика в модуле. Датчики суммарного итога (energy_total, energy_exported_total, energy_net, reactive_energy*) используют собственный слот NVS, отдельный от слотов energy по каналам, поэтому обновление компонента не очищает значения по каналам.

Что вы видите на панели энергии HA: резкий спад до 0 Вт·ч, затем нормальное накопление с 0. Старая история Вт·ч сохраняется в долгосрочной статистике HA, но «текущее показание счётчика» выглядит сброшенным.

Что это значит: при восстановлении из NVS данных не найдено или загружены некорректные данные. Возможные причины:

  1. Повышение версии раскладки NVS. Ключ NVS выводится из ID компонента, XOR-ом с константой версии раскладки. Если структура изменилась (при обновлении компонента), ключ слота меняется и старые данные не находятся. Восстановление тихо начинается с 0.
  2. Фрагментация или повреждение NVS. Раздел NVS на ESP32 использует выравнивание износа флеша. На очень старых установках или после многих прошивок фрагментация может сделать сохранение неудачным. В логе: [W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle.
  3. Изменение разметки разделов. Прошивка нового partitions.csv, который меняет размер или расположение раздела nvs, обнуляет все сохранённые значения.
  4. Первая загрузка после сброса к заводским настройкам или полного стирания флеша. Ожидается: NVS пуст, накопитель начинается с 0.

Как диагностировать:

В журнале загрузки ищите:

Text
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh

Если присутствует, восстановление ничего не нашло. Также:

Text
[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 он накапливает собственные счётчики энергии модуля.

Если энергия занижена, проверьте следующее:

  1. Характер нагрузки. Регистр средней мощности за период — действительно усреднённая по времени мощность за закрытый период, а не мгновенное значение. Импульсная нагрузка (мотор, компрессор) с коротким временем включения внутри 60-секундного периода даёт среднее значение ниже своей пиковой мощности.
  2. Размещение клещей и калибровка нагрузки (burden). Если заводская модель ТТ (ct_model:) не соответствует реальности, диапазоны коэффициентов будут смещены. Убедитесь, что ct_model: в YAML соответствует физическим клещам на проводнике.
  3. Уровень прошивки BASIC. На артикуле BASIC выборки P по каждому окну принудительно приводятся к 0 до интеграции. Если нагрузка имеет рекуперативную составляющую (например, насос с обратной ЭДС), BASIC занижает учёт.

4. Интеграция с Home Assistant

HA показывает «Unavailable» для всех датчиков rbamp

Что вы видите в HA: все сущности sensor.rbamp_* показывают «Unavailable».

Причины и исправления:

  1. ESP32 офлайн. Выполните esphome logs --device — если не удаётся подключиться, ESP32 офлайн. Проверьте учётные данные WiFi и резервную точку доступа, если она настроена.
  2. Потеряно соединение API. Нативный API ESPHome (порт 6053) может блокироваться файрволом. Проверьте, что ESP32 доступен по IP:

    Shell
    ping 
    

    Если ping проходит, а HA всё ещё показывает unavailable, интеграцию ESPHome в HA нужно удалить и добавить заново (Настройки → Интеграции → ESPHome → Удалить, затем обнаружить заново).

  3. Несовпадение ключа шифрования API. Если в YAML задан api: encryption: key:, интеграция HA должна знать тот же ключ. Несовпадение заставляет HA считать устройство офлайн. Удалите и заново добавьте интеграцию после обновления ключа.

  4. mDNS не работает в вашей сетевой топологии. Если ESP32 находится в другом VLAN, чем HA, multicast mDNS может не пересечь границу. Добавьте устройство по IP вручную в интеграции ESPHome.

Прошивка OTA не удаётся

Что вы видите:

Text
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed

Частые причины:

  1. IP-адрес изменился. ESP32 получил новую аренду DHCP. Проверьте таблицу DHCP роутера, найдите устройство по MAC и назначьте статический IP или используйте ключ YAML wifi: use_address:.
  2. ESP32 находится в безопасном режиме. После трёх неудачных загрузок подряд ESPHome переходит в безопасный режим (без пользовательских компонентов, только Wi-Fi + OTA). OTA в безопасном режиме работает, но устройство запущено на урезанной прошивке. Маркер в esphome logs:

    Text
    [I][safe_mode:xxx]: Entering safe mode
    

    Принудительная чистая загрузка: удерживайте кнопку BOOT при включении или добавьте safe_mode: num_attempts: 10, чтобы расширить порог.

  3. Порт 3232 (OTA) заблокирован. Протокол OTA использует TCP 3232. Проверьте, что ни одно правило файрвола не блокирует его между машиной, на которой запущен esphome run (или хостом HA), и IP-адресом ESP32.

  4. Слишком большая прошивка после добавления 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 шага:

  1. Отредактируйте YAML:

    YAML
    rbamp:
      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
    
  2. Выполните esphome run (через CLI) или Compile + Upload (через надстройку HA). Узел получает новый бинарник по Wi-Fi через OTA.

  3. Откройте 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. Всплывающее окно:

Text
'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//src/). Это косметика и не обязательно.


PlatformIO падает с 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)

Что вы видите:

Text
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):

Text
# 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 отсутствует

Что вы видите:

Text
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 был пропущен:

Text
# 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 не найден

Что вы видите:

Text
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 не найден

Что вы видите:

Text
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 сама следует за текущим релизом — рекомендуемый путь установки.

Shell
# 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):

YAML
text_sensor:
  - platform: template
    name: "Meter variant"
    lambda: 'return id(my_meter).get_variant_str();'  # → "UNK" in HA
Text
[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

Что вы видите:

YAML
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:

Что вы видите:

Text
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)

get_last_error_str() → "ERR_PARAM".

Что это значит: прошивка отклонила записанное значение. Самые частые причины:

  1. Код вне допустимого набора — для SCT_013 допустимые коды: {1, 2, 3, 4, 5, 6, 7}.

  2. Модель CT не входит в допустимый набор для класса — например, WIRED_CT_1 при sensor_class: SCT_013. См. таблицу по классам в 03_sensor_selection.md.

  3. Код 0 (UNSET) — попытка сбросить модель CT значением 0. Не поддерживается; для полного сброса используйте dev.factoryReset().

Восстановление: вызовите id(my_meter).write_clear_error(); через службу YAML или через lambda: в on_boot:, чтобы сбросить REG_ERROR и бит3 EVENT_FLAGS. После этого можно повторить попытку с корректным значением.

YAML
api:
  services:
    - service: my_meter_clear_error
      then:
        - lambda: 'id(my_meter).write_clear_error();'

Изменение ct_model: / sensor_class: отклоняется (запись в журнале, без записи)

Что вы видите:

Text
[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)

Что вы видите:

Text
[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: соответствует физически установленной клипсе.

Датчики суммарного итога / углов никогда не публикуют значения

Что вы видите (журнал загрузки):

Text
[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 после сброса, если исходное условие ошибки не устранено. Так задумано — мастер мог пропустить первый сброс и не должен навсегда считать ошибку устранённой, если параметр всё ещё неверен.

Исправление: полное восстановление требует двух шагов:

  1. Устраните причину (замените неверный код модели CT, исправьте YAML).
  2. write_clear_error() — этот вызов сбрасывает и REG_ERROR, и бит3 EVENT_FLAGS одной операцией.

Если бит3 продолжает срабатывать повторно, параметр всё ещё неверен; перечитайте get_last_error_str(), чтобы точно узнать, что отклоняет прошивка.


Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/10_troubleshooting.md (v1.9.1)