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

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

Эта глава построена по наблюдаемым симптомам, а не по внутренней классификации ошибок. Если вы здесь, значит что-то работает неправильно. Найдите ваш симптом в списке ниже, перейдите к нужному разделу и выполните процедуру диагностики.

Большинство проблем на стенде попадает в три категории:

  1. Уровень шины — модуль не отвечает по I²C, чтения возвращают ESP_FAIL или ESP_ERR_INVALID_RESPONSE.

  2. Уровень данных — модуль отвечает, но числа неверны: нули, странные значения, неверный знак.

  3. Уровень приложения — связь нестабильна, счётчик Wh дрейфует, проект зависает.

Кратко для нетерпеливых: в установившемся режиме публичные функции rbamp_* должны возвращать ESP_OK. Если в логах часто видна ESP_FAIL или ESP_ERR_INVALID_RESPONSE, перейдите сразу к разделу «Модуль не отвечает по I²C» ниже.

Дерево решений по устранению неполадок, сгруппированное по симптомам.

Модуль не отвечает по I²C

Что вы видите: rbamp_begin(dev) возвращает ESP_FAIL или ESP_ERR_INVALID_RESPONSE, либо чтения RT регулярно передают ESP_FAIL в ваш код.

Шаг 1 — Сканирование шины

Сначала убедитесь, что модуль вообще присутствует на шине. Для этого именно в ESP-IDF v5.x есть i2c_master_probe():

C
#include "driver/i2c_master.h"
#include "esp_log.h"

static const char *TAG = "i2c_scan";

void bus_scan(i2c_master_bus_handle_t bus) {
    ESP_LOGI(TAG, "Scanning...");
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
            ESP_LOGI(TAG, "Found 0x%02X", addr);
        }
    }
}

Ожидаемый вывод: Found 0x50 (или другой адрес, если вы его меняли).

Если ничего не найдено — проблема в проводке или питании:

  • SDA / SCL не переставлены (см. 04 · Проводка для GPIO по умолчанию для каждого чипа).

  • Обе линии имеют подтяжку к 3.3 В (на плате модуля есть встроенные 4.7 кОм — для одного модуля внешние не нужны).

  • Питающий вывод модуля фактически имеет 5 В (4.5–5.5 В).

  • На тех же линиях не сидит другой мастер (отладочный зонд, второй ESP32).

  • flags.enable_internal_pullup = true в вашем i2c_master_bus_config_t (если внешних подтягивающих резисторов нет).

Если модуль найден, но по неожиданному адресу — кто-то ранее переадресовал его на стенде. Обновите второй аргумент rbamp_new:

C
rbamp_new(bus, 0x52, &dev);   /* address from the bus scan */

Шаг 2 — базовый шаблон NACK для ESP32

Если сканирование шины находит модуль, но rbamp_read_voltage(dev, 0, &v) периодически возвращает ESP_FAIL — это документированный базовый шаблон: драйвер ESP-IDF v5 i2c_master имеет особенности при работе с rbAmp на текущей прошивке (частые NACK на 100 кГц).

Смягчение уже встроено в компонент (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 по умолчанию, 50 кГц через CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), но при сильной нагрузке бюджет повторов может исчерпаться.

Что сделать через idf.py menuconfig → Component config → rbAmp client:

  1. Подтвердите значение 50 кГц по умолчанию:
Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
  1. Увеличьте число повторов при сильной нагрузке:
Text
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
  1. При необходимости — увеличьте таймаут:
Text
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
  1. Включите уровень DEBUG для тега rbamp для диагностики:
Text
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

Можно сделать это и во время работы — esp_log_level_set("rbamp", ESP_LOG_DEBUG).

Примечание

О счётчиках повторов / проверок. Компонент экспортирует публичные геттеры rbamp_retry_exhaustion_count(dev) и rbamp_sanity_reject_count(dev) — они кроссплатформенно совпадают с Arduino dev.retryExhaustionCount() / dev.sanityRejectCount(). Канонический шаблон «снимок + разность» для промышленного мониторинга описан в разделе «Мониторинг счётчиков» ниже.

Парк: модуль оказался в excluded после rbamp_fleet_scan

Что вы видите: rbamp_fleet_scan(fleet, ...) отработал и вернул ESP_OK, но rbamp_fleet_count(fleet) меньше, чем число физически подключённых модулей. rbamp_fleet_excluded_count(fleet)

Примечание

0; перебирайте rbamp_fleet_excluded_addr(fleet, i) — каждый исключённый адрес означает «модуль обнаружен, но НЕ добавлен в парк — подозревается конфликт».

Причина. Детектор конфликтов работает по двум независимым сигналам:

  • согласованность идентичности: HW_VARIANT ↔ битовая карта CAPABILITY не согласованы — признак того, что по одному адресу отвечают два разных физических модуля (ответ частично «склеивается»).
  • живое значение: по одному адресу наблюдаются несовместимые «живые» показания — например, отличающийся LABEL или мерцающий вариант.

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

Безопасность

⚠ Обнаружение — по возможности. Гарантировать, что парк поймает два одинаковых модуля на одном адресе, невозможно — именно поэтому существует дисциплина ввода в эксплуатацию (см. следующий раздел).

Что делать.

  1. Физически отключите все модули, кроме одного.
  2. Подключайте остальные по одному, запуская rbamp_fleet_scan заново после каждого. Модуль, после подключения которого появляется excluded, конфликтует с уже подключённым.

  3. Переназначьте конфликтующий модуль на свободный адрес через rbamp_provision(bus, new_address, ...) (требуется, чтобы он был единственным на 0x50 — см. дисциплину провизионинга ниже).

  4. После переадресации повторите rbamp_fleet_scan — excluded_count должен быть 0.

Парк: rbamp_fleet_scan вернул ESP_ERR_INVALID_STATE + пустой парк

Что вы видите: rbamp_fleet_scan вернул ESP_ERR_INVALID_STATE, rbamp_fleet_count(fleet) равен 0. В парк не добавлено ни одного модуля, хотя физически они подключены.

Причина. Контрольный канал «зависания» уровня 2 — библиотека выполнила проверку шины на наличие ответа по адресу, который не должен отвечать (контрольный адрес). Если контрольный адрес получил ACK, шина не в нормальном состоянии: либо электрические помехи дают ложные ACK, либо все адреса «застряли» из-за зависания, либо есть ошибка топологии (несколько модулей с одинаковым кодом сразу и SDA/SCL удерживаются в низком уровне). В таком состоянии никакому результату сканирования нельзя верить — поэтому флот остаётся пустым; лучше прервать работу, чем заведомо неверно инициализировать.

Что делать.

  1. Перезапустите питание всей шины (снимите питание с модулей на несколько секунд и перезапустите ESP32). Это сбрасывает зависшие состояния.

  2. Подключайте модули строго по одному, запуская rbamp_fleet_scan (ввод в работу одного модуля) после каждого и проверяя возврат:

  3. ESP_OK + count=1 + excluded=0 → шина чистая, модуль в порядке.

  4. ESP_ERR_INVALID_STATE сохраняется → проверьте подтягивающие резисторы (см. раздел i2c-hang выше — внешний резистор 4.7 кОм на SDA/SCL обязателен).

  5. Когда ввод в работу каждого модуля по отдельности пройден, добавьте их все на шину сразу и снова запустите rbamp_fleet_scan. Если снова получаете INVALID_STATE, проблема в электрике шины (длина, помехи, отсутствующая подтяжка), а не в отдельных модулях.

Флот: rbamp_provision вернул ошибку

Что вы видите: вызов rbamp_provision(bus, desired_address, save_config, &out) не завершился с ESP_OK. В зависимости от возвращённого кода:

esp_err_t Что произошло Что делать
ESP_ERR_NOT_FOUND По 0x50 никто не ответил (заводской адрес по умолчанию) Убедитесь, что новый модуль физически подключён и запитан (VCC); проверьте проводку I²C (см. «Модуль не отвечает по I²C»).
ESP_ERR_INVALID_STATE Обнаружен конфликт по адресу 0x50 или нужный адрес уже занят На шине больше одного чистого модуля или нужный адрес уже занят другим модулем. Отключите все «лишние» модули (см. ниже).
ESP_ERR_TIMEOUT Команда фиксации адреса прошла, но модуль не появился по новому адресу в пределах окна загрузки Выключите и включите питание модуля и повторите. Если повторяется — вероятно, незавершённая операция с flash (питание пропало во время CMD_SAVE_USER_CONFIG или CMD_COMMIT_ADDR, поэтому блок flash может быть записан частично). На следующей загрузке модуль возвращает REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), загружает заводские значения и появляется на 0x50. Проведите провизионинг заново; если и это не помогает — отправьте в сервис.
ESP_ERR_INVALID_ARG desired_addr вне допустимого диапазона 0x08..0x77 Используйте допустимый адрес.
Безопасность

⚠ Дисциплина provisioning — ТОЛЬКО один девственный модуль за раз.

Самый частый источник INVALID_STATE при вводе в эксплуатацию — более одного модуля на шине с заводским адресом 0x50. Различить их по I²C физически невозможно (открытый сток с монтажным И — оба модуля отвечают ACK одинаково, а обратное чтение данных приходит «склеенным»).

Поэтому правило строгое (нормативное ТРЕБОВАНИЕ, а не рекомендация): в момент вызова rbamp_provision должен быть ровно один модуль на 0x50 (новый или возвращённый к заводским значениям отдельным стендовым инструментом). Вариант «я уверен, что эти два модуля разные — разведу их прямо сейчас» не работает: коллизия проявится позже, когда вы уже будете считать парк чистым.

Путь восстановления при подозрении на нарушение дисциплины: 1. Перезапустите питание всех модулей. 2. Физически отключите все модули, кроме одного «нового» (того, который вы хотите переадресовать). 3. Вызовите rbamp_provision на шине с одним модулем. 4. Добавляйте остальные модули по одному, подготавливая каждый отдельно.

Ток читается нулём на работающей нагрузке

Что вы видите: rbamp_read_current(dev, 0, &i) возвращает ESP_OK, но i = 0.000 (или очень малое значение), хотя реальный потребитель включён (чайник, лампа, утюг). rbamp_read_power_factor(dev, 0, &pf) может показывать странное значение (nan / 0 / ±1) — это следствие; причина в токе.

Процедура диагностики

  1. Проверьте, что класс датчика и модель CT заданы:
C
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3);   /* or your model */
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}

Без этих двух вызовов коэффициенты калибровки не загружаются, и ток всегда читается как ноль. Этот шаг выполняется один раз при первой установке — выбор сохраняется во flash модуля.

Примечание

Ловушка с RBAMP_SENSOR_UNSET. Если вы случайно вызовете rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET) — функция вернёт ESP_OK, но фактически сбросит конфигурацию класса. Последующий rbamp_set_ct_model*() начнёт возвращать ESP_ERR_INVALID_STATE. Исправление — снова вызвать rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013), затем снова rbamp_set_ct_model().

  1. Проверьте, что модель CT соответствует нагрузке. Большая клипса CT (например, SCT-013-100, 100 А) на малой нагрузке (лампа 50 Вт ≈ 0.2 А) даёт сигнал на грани шумового порога, и показания будут нулевыми. Выбирайте наименьшую модель CT, которая покрывает ваш максимальный ожидаемый ток. Полная таблица — в 03 · Выбор токового датчика.

Если у вас модуль с несколькими каналами (UI2 / UI3 / UI5 / UI7) и вы хотите видеть и малые нагрузки, и пиковые всплески, рассмотрите шаблон двойного CT: малые клещи (например, SCT-013-005) на отдельном канале для низкого диапазона и большие (SCT-013-030/100) на другом канале для высокого диапазона; мастер выбирает значение по порогу. Шаблон описан в 03 · Выбор датчика тока, раздел «Топология двойного CT».

  1. Проверьте ориентацию клипсы. Стрелка на корпусе клипсы должна указывать в направлении тока к нагрузке. Если клипса «задом наперёд», rbamp_read_current() даёт верное значение по модулю, но rbamp_read_power() даёт отрицательное значение на потребительской нагрузке. Подтверждение: rbamp_read_power_factor() покажет ровно −1.0 на активной нагрузке (вместо +1.0). Исправление: либо физически переустановить клипсу (раскрыть, повернуть стрелку правильно, защёлкнуть), либо инвертировать знак на стороне мастера.

Если все три шага прошли, но ток всё равно ноль

Тогда сигнал на входе модуля действительно ниже шумового порога. Проверьте:

  • Течёт ли ток на самом деле — измерьте мультиметром (клещи постоянного / переменного тока) на том же проводе.

  • Клипса целая — на разъёме клипсы должно быть переменное напряжение, пропорциональное току (несколько милливольт для бытовых нагрузок).

  • Правильный ли провод вы охватываете — линейный (фазный) проводник и только его (никогда не весь кабель).

Показания скачут или возвращают ESP_FAIL

Что вы видите: rbamp_read_voltage(dev, ...) или rbamp_read_current(dev, ...) периодически возвращают ESP_FAIL. Значение в *out после ошибки не определено.

ESP_FAIL от компонента охватывает два класса проблем:

  • NACK после исчерпания повторов — связь нестабильна.
  • Фильтр адекватности отклонил значение — число с плавающей точкой NaN / Inf / |x| > 10000 пришло по шине (явно нефизическое значение).

ESP-IDF API не различает их разными кодами esp_err_t (в отличие от RB_ERR_NACK / RB_ERR_NON_PHYSICAL в Arduino) — оба возвращают ESP_FAIL. Различить их можно по диагностическим счётчикам (см. раздел «Контроль счётчиков» ниже). Оба симптома обрабатываются одинаково:

  1. Подтвердите значение 50 кГц по умолчанию и повысьте число повторов до 5 через Kconfig — см. предыдущий раздел.

  2. Снизьте плотность нагрузки на шину — если ваш цикл делает много однобайтовых чтений, попробуйте rbamp_read_all() (одна транзакция I²C вместо ~13).

  3. Проверьте CONFIG_RBAMP_I2C_TIMEOUT_MS — если устройство отвечает медленнее обычного (длинный кабель, плохой контакт), увеличьте таймаут.

  4. Включите журнал DEBUG через CONFIG_RBAMP_LOG_LEVEL_DEBUG=y или esp_log_level_set("rbamp", ESP_LOG_DEBUG) — компонент будет выводить подробности цикла повторов и отклонённых по здравому смыслу значений под тегом "rbamp".

Контроль счётчиков

Компонент экспортирует два публичных монотонных счётчика для промышленного мониторинга состояния шины:

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);

retry_exhaustion_count увеличивается, когда однобайтовая транзакция исчерпала бюджет CONFIG_RBAMP_NACK_RETRY_ATTEMPTS и вернула ESP_FAIL. sanity_reject_count увеличивается, когда фильтр адекватности отбрасывает значение с плавающей точкой (!isfinite(x) || |x| > 10000).

Каноничный шаблон — снимок + разность раз в 60 секунд, чтобы получить «частоту событий в минуту»:

C
uint32_t prev_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta  = now_retry  - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
    ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
             retry_delta, sanity_delta);
}

Пороги тревоги зависят от нагрузки. Для плотного пакета нагрузочного теста (как Arduino SoakMonitor — ~70 байт на цикл раз в 5 минут):

  • retry_delta > 1/hour — безобидный шум, можно игнорировать.
  • retry_delta стабильно > 5/час — стоит разобраться (плохие контакты, ёмкость шины, температурный дрейф подтяжек).

  • sanity_delta > 0 в установившемся режиме — почти всегда признак электромагнитных помех на шине или регрессии прошивки.

Счётчики только растут (никогда не сбрасываются) — чтобы сбросить их, нужно пересоздать дескриптор через rbamp_del(dev) + rbamp_new(...). Так задумано, чтобы не терять историю из-за гонки между «сбросом» и «чтением в регистратор».

Примечание

Эти счётчики на всех платформах соответствуют семантике Arduino dev.retryExhaustionCount() / dev.sanityRejectCount() — те же имена (snake_case вместо camelCase), те же пороги работают так же.

Коэффициент мощности выглядит неверным

Что вы видите: rbamp_read_power_factor(dev, 0, &pf) возвращает ESP_OK, но pf не соответствует типу нагрузки.

Ожидания по нагрузкам:

Нагрузка Ожидаемый PF
Чайник, утюг, лампа накаливания +0.95 .. +1.0 (резистивная)
Холодильник, мотор компрессора +0.6 .. +0.85 (индуктивная)
Светодиодная лампа, телевизор (импульсный блок питания) +0.5 .. +0.95 (нелинейно)
Инвертор PV, отдающий мощность в сеть отрицательный PF

PF = nan или 0 при I = 0

PF определяется как P / (U × I). При нулевом токе I=0 выражение не определено. Конкретное возвращаемое значение зависит от прошивки (это может быть 0 или заглушка около нуля) — это нормально, пока ток действительно нулевой. Как только появится ток, появится и корректный PF. Фильтр адекватности компонента это значение не отклоняет (поэтому эквивалент sanityRejectCount в IDF не увеличивается) — это корректная мера неопределённой величины, а не артефакт связи.

PF строго −1.0 на чисто потребительской нагрузке

Клипса надета «задом наперёд» — стрелка указывает против направления тока, от нагрузки. Исправление: либо правильно переустановите клипсу, либо обработайте знак на стороне мастера (p = -p; pf = -pf;, если известно, что нагрузка не может быть инвертором PV).

PF колеблется от +0.3 до +0.7 на активной нагрузке

  • Возможная причина: клещи CT охватывают провод другой фазы, чем та, к которой подключён вход U модуля. В распределительном щите с несколькими фазами легко по ошибке охватить не ту фазу — сдвиг фаз 120° или 180° между U и I даёт именно такие значения PF. Исправление: установите модуль так, чтобы вход U и CT были на одной фазе.

  • Альтернатива: нагрузка на самом деле не чисто резистивная. Повторите тест с заведомо резистивной нагрузкой (электрочайник на полной мощности).

Снимки периода всегда stale

Что вы видите: rbamp_read_period_snapshot(dev, ...) возвращает ESP_ERR_INVALID_RESPONSE или *out.valid == false. Это значит, что модуль не завершил интегрирование предыдущего периода к моменту следующего чтения.

Компонент защищается от двойного учёта Wh: при устаревшем снимке он записывает мастер-метку времени (esp_timer_get_time()), и следующий успешный снимок покрывает один период, а не два.

Допустимо: редкие устаревания (1–2 в час при интервале 60 с). Недопустимо: подряд идущие устаревания — значит, прошивка не отвечает или мастер опрашивает слишком часто.

Процедура проверки ритма

  1. Проверьте периодичность: 60 с между снимками — комфортно; 30 с — на границе; < 10 с гарантирует устаревшие снимки.

  2. Проверьте отзывчивость модуля между снимками:

C
if (rbamp_probe(dev) == ESP_OK) {
    ESP_LOGI(TAG, "alive");
}
  1. Проверьте флаг напрямую — rbamp_is_period_valid() делает однобайтовое чтение без побочных эффектов:
C
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
    /* avg_p[] can be read */
}
  1. Проверьте версию прошивки — rbamp_firmware_version(dev) >= 0x02 даёт меньше устаревших значений, чем 0x01. Текущая каноническая прошивка — 0x04 (v1.3); 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2.

Особый случай — пробуждение из глубокого сна

Если вы используете шаблон глубокого сна, стандартный вызов rbamp_read_period_snapshot() сразу после rbamp_begin() всегда будет устаревшим (или даст значения, близкие к нулю) — begin() делает приблизительный снимок, который сбрасывает накопитель прошивки. Канонический шаблон использует skip_latch=true + собственную временную метку мастера, сохранённую в RTC, — см. 06 · Примеры, Сценарий 9.

Учёт Wh расходится с эталоном

Что вы видите: rbamp_energy_wh(dev, 0) после нескольких часов / дней работы расходится с показанием счётчика энергоснабжающей организации или эталонного счётчика (Kill-A-Watt и т. п.).

Сначала исключите очевидное

  1. Калибровка токового датчика: убедитесь, что rbamp_set_sensor_class() и rbamp_set_ct_model() вызывались с правильной моделью CT (см. 03 · Выбор датчика тока). Без этого среднеквадратичный ток считается с порогом по умолчанию, и значение мощности будет систематически смещено.

  2. Отброшенные устаревшие снимки: если rbamp_energy_wh() стабильно ниже эталона, это могут быть пропущенные интервалы — снимок пришёл устаревшим, компонент защитился от двойного учёта, но измерение интервала было потеряно. Проверьте частоту (см. выше).

  3. Дрейф часов мастера: esp_timer_get_time() надёжен сам по себе. Но если мастер уходит в глубокий сон без сохранения RTC, интервал между предыдущим и следующим снимком теряется. Для сценариев глубокого сна используйте шаблон RTC_DATA_ATTR из сценария 9.

Точность накопителя

Накопитель Wh внутри дескриптора хранится как 64-битный double.

Если вы собрали компонент с CONFIG_RBAMP_DISABLE_ENERGY=y, хранилище энергии и API полностью удаляются из бинарника. В этом случае свой счётчик Wh нужно вести в пользовательском коде.

snap.latch_ms — диагностика, не для энергии

latch_ms — диагностический таймер модуля; не используйте его для энергии — используйте часы мастера.

Проект ESP32 зависает через несколько минут

Что вы видите: проект ESP32 запускается нормально, затем через 1–30 минут уходит в зависание / цикл перезапусков / таймаут WDT.

IDF i2c_master зависает на слабой шине — трёхуровневая защита

Что именно вы видите: проект ESP32 (классический v1.0, IDF v5.4.1, новый драйвер i2c_master) опрашивает rbAmp нормально несколько минут, затем «зависает» посреди вызова rbamp_*_read_* или rbamp_fleet_poll_all. Task-WDT (если включён) ловит зависание; иначе проект просто перестаёт отвечать. Расшифрованный бэктрейс заканчивается на i2c_ll_is_bus_busy (файл i2c_master.c:526, ожидание занятости шины перед отправкой).

Что происходит: на маргинальной шине (слабые подтяжки, длинные дорожки, EMI, помехи от фронтов ZC) SDA/SCL могут на мгновение «залипнуть» в неопределённом состоянии. Перед каждой транзакцией i2c_master из IDF крутится в цикле ожидания i2c_ll_is_bus_busy, ожидая освобождения шины — это ожидание НЕ ограничено параметром xfer_timeout_ms. Если занятость шины длится дольше, чем цикл может крутиться без обслуживания других задач, задача FreeRTOS IDLE не получает процессор, и всё приложение зависает.

Это не «артефакт только для отладчика». Проверено на стенде: на том же аппаратном стенде и нагрузке —

Конфигурация шины Частота зависаний
2 слабые подтяжки модуля + подключённый NRST отладчика ~1 зависание / 2.1 мин
1 слабая подтяжка модуля, без отладчика ~1 зависание / 3.3 мин (≈ 12 зависаний в час)
+ внешняя подтяжка 4.7 кОм на SDA/SCL проверяемого устройства 0 зависаний (прогоны 5 и 25 минут, 0 перезагрузок)

Корреляция ясна — исправление целостности шины полностью устраняет зависание. Логика библиотеки не виновата: механика по модулям (fleet_poll_all, MISS/рассинхронизация, проверки утечек) оставалась чистой во всех прогонах вплоть до зависания.

Трёхуровневое смягчение (примените все три уровня):

  1. Внешняя подтяжка (~4.7 кОм) на SDA и SCL к 3.3 В в одной точке шины. Внутренние подтяжки ESP32 (~45 кОм) слабы для шины с несколькими модулями реальной длины, а встроенные в модули подтяжки 4.7 кОм, включённые параллельно, становятся слишком сильными. На такой шине отключите встроенные на всех модулях, кроме одного (или на всех — тогда опирайтесь только на внешние). См. 04 · Проводка, раздел «Шина с несколькими модулями — основная топология».

  2. Не запускайте производственную сборку с подключённым отладчиком по NRST. В сессии отладки линия сброса может удерживать SDA/SCL в неопределённом состоянии при отключении/подключении, что вызывает зависание шины на следующей транзакции. В полевой сборке (без отладчика) этого фактора нет.

  3. Task-WDT на уровне приложения для задачи опроса — защита в глубину. Если по какой-то причине подтяжки остаются пограничными или возникает иная причина зависания, WDT перезагружает проект, а при наличии супервизора (например, загрузчика с откатом или супервизора в духе systemd) он возвращается в работу. На стендовом испытании длительностью более часа WDT поймал и восстановил все 12 зависаний в конфигурации без внешней подтяжки.

C
#include "esp_task_wdt.h"

void app_main(void) {
    /* Layer 3 setup — defense-in-depth. */
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 10000,           /* 10 s with plenty of margin */
        .idle_core_mask = 0,
        .trigger_panic = true,         /* on timeout — panic+reboot */
    };
    ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
    ESP_ERROR_CHECK(esp_task_wdt_add(NULL));   /* this task is under the WDT */

    /* ... bus / fleet init ... */

    while (1) {
        rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
        /* ... processing ... */
        esp_task_wdt_reset();            /* "I'm alive" — every cycle */
        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

Чего НЕ делать: не пытайтесь обойти проблему увеличением xfer_timeout_ms — он не ограничивает предварительное ожидание занятой шины, это другой путь кода в драйвере. Решение — целостность шины (уровень 1) + супервизор (уровень 3).

Таймаут сторожевого таймера при подключении к Wi-Fi

Причина: неограниченный цикл ожидания подключения WiFi внутри обработчика события вызывает срабатывание сторожевого таймера задачи через ~5 с (по умолчанию).

Исправление: используйте событийный шаблон вместо активного ожидания. Драйвер WiFi ESP-IDF выдаёт события WIFI_EVENT_STA_DISCONNECTED и IP_EVENT_STA_GOT_IP — реагируйте на них через esp_event_handler_register(), а не опрашивайте в цикле.

Минимальный шаблон:

C
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT      BIT1

static void wifi_event_handler(void *arg, esp_event_base_t event_base,
                                int32_t event_id, void *event_data) {
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        esp_wifi_connect();   /* auto-reconnect */
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
    wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
    pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
    esp_restart();
}

Брокер MQTT разрывает соединение примерно каждые 15 с

Причина: в большинстве случаев это не keepalive. По умолчанию session.keepalive в esp_mqtt_client_config_t равен 120 с, а disable_keepalive по умолчанию false (то есть keepalive включён). Явная перезапись этих полей теми же значениями ничего не меняет — если соединение рвётся каждые 15 с, настоящая причина в сети (промежуточный NAT/файрвол, сбрасывающий простаивающий TCP) или в падении WiFi.

Исправление: зарегистрируйте MQTT_EVENT_DISCONNECTED и переподключайтесь явно. esp_mqtt_client_start() запускает собственную задачу внутри; отдельно тикать mqtt.loop() не нужно — просто переподключайтесь по событию.

C
static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t event_id, void *event_data) {
    if (event_id == MQTT_EVENT_DISCONNECTED) {
        ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
        /* esp-mqtt reconnects automatically with backoff;
         * this handler is the place to clean up application state
         * (retained flags, discovery payload caches). */
    }
}

const esp_mqtt_client_config_t cfg = {
    .broker.address.uri = "mqtt://192.168.1.10:1883",
    /* leave keepalive at the default — 120 s;
     * for aggressive NATs, lower it to 30 s: */
    /* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
                                mqtt_event_handler, NULL);
esp_mqtt_client_start(client);

Если разрывы совпадают по времени с обрывами Wi-Fi, реальная причина — в Wi-Fi (RSSI, загруженный канал), а не в MQTT. Проверьте полезную нагрузку MQTT_EVENT_ERROR и журналы Wi-Fi, прежде чем трогать keepalive.

Сбой рукопожатия TLS (облачные интеграции)

Причина: кучи ESP32 недостаточно для рукопожатия TLS (требуется ~30 кБ). Часто в сочетании с Wi-Fi + MQTT + буферами, остаётся < 20 кБ.

Fix:

  • Используйте WiFi.mode(WIFI_MODE_STA) (не STA+AP).
  • Отключите BLE, если он не нужен: CONFIG_BT_ENABLED=n в sdkconfig.

  • Уменьшите размеры буферов MQTT в esp_mqtt_client_config_t.

  • Переход на ESP32-S2 (без Bluetooth — дополнительно ~30 кБ кучи).

Если esp_get_free_heap_size() показывает < 25 кБ до esp_mqtt_client_start() или esp_http_client_perform(), рукопожатие TLS, скорее всего, завершится ошибкой.

Обработка ошибок: последняя запись REG_ERROR + устойчивый EVENT_FLAGS.bit3 (v1.3)

Канон v1.3 (подтверждено на оборудовании): REG_ERROR (0x02) — результат последней записи, НЕ липкий. При каждой записи в регистр прошивка выставляет reg_error = ERR_OK; последующая не связанная запись сбрасывает предыдущую ошибку.

Устойчивый сигнал ошибки = EVENT_FLAGS (0x2A) bit3 — липкий (W1C), выставляется сразу при любой отклонённой записи или команде.

Шаблон 1 — разовый захват после операции (если важен результат именно этой операции):

C
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err);   /* IMMEDIATELY, before the next write */

Шаблон 2 — долговременный мониторинг ошибок (канонический для долгоживущих систем):

C
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
    uint8_t last_err;
    rbamp_read_last_error(dev, &last_err);   /* what was the last rejected */
    /* handle the error */
    rbamp_clear_error(dev);                  /* clears REG_ERROR ... */
    rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR);  /* ... then the sticky bit */
}
Безопасность

⚠ ОТМЕНА прежней «липкой» документации (канон v1.3 A3). REG_ERROR — результат последней записи, а не липкий. Долговечность обеспечивается EVENT bit3.

⚠ bit3 — асинхронный канал, он не предназначен для синхронной проверки записи: при отклонённой записи bit3 выставляется с задержкой относительно момента, когда транзакция I²C вернулась. Не опрашивайте bit3 сразу после записи, чтобы проверить её результат, — для результата вашей собственной записи используйте Шаблон 1 (однократный захват REG_ERROR сразу после операции) или код возврата сеттера. bit3 предназначен для долгого мониторинга асинхронных фактов (время работы, путь команд), а не для проверки только что выполненной операции.

Оговорка: DEV_ERR_CLONE (0xF9) НЕ сбрасывается через CMD_CLEAR_ERROR — это защитный маркер от клонирования (сбрасывается только перезагрузкой или заводским сбросом).

Модуль с новой прошивкой показывает 0xFB при первой загрузке (НОРМА)

Что вы видите: только что прошитый модуль при первой загрузке показывает REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + EVENT bit3.

Причина: страница параметров не инициализирована → загружены заводские значения по умолчанию. Это НОРМАЛЬНО для нового модуля, не фатально.

Решение: задайте sensor_class + ct_model + (при необходимости) address, затем CMD_SAVE_USER_CONFIG. После успешного SAVE → REG_ERROR = 0x00, бит3 сброшен.

rbamp_set_sensor_class / rbamp_set_ct_model* возвращает ESP_ERR_INVALID_STATE

Что вы видите: один из вызовов конфигурации возвращает ESP_ERR_INVALID_STATE.

ESP_ERR_INVALID_STATE из этой группы функций — общий код для трёх разных причин. Различить их можно по строке ESP_LOGW, которую компонент выводит под тегом "rbamp" непосредственно перед возвратом:

Строка журнала (ESP_LOGW, TAG="rbamp") Причина Решение
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) Предусловие: класс датчика должен быть задан до записи модели CT Вызовите rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) перед rbamp_set_ct_model*().
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) Внутренний трекер пакетов компонента рассинхронизирован с состоянием подготовки прошивки В прошивке v1.3 порядок привязки каналов произволен (Fix-A — чистая подготовка, см. 03 · Выбор датчика тока). Вызовите rbamp_set_sensor_class() ещё раз, чтобы сбросить трекер пакета, затем привяжите каналы в любом порядке. Формулировка «требуется убывающий порядок» из старых сообщений журнала относится к поведению до v1.3 и больше не действует.

Есть также случай, когда дескриптор инициализирован, но rbamp_begin() не вызывался — в этом случае возвращается ESP_ERR_INVALID_STATE без строки ESP_LOGW (дескриптор ещё «холодный»). Решение: вызовите rbamp_begin(dev) после rbamp_new() и до любого rbamp_set_*.

Примечание

Шаблон различения по журналу — стандартный приём ESP-IDF: сравните с esp_driver_i2c, который возвращает ESP_ERR_TIMEOUT и для таймаута ACK, и для таймаута занятой шины, различая их по журналу. Если видите ESP_ERR_INVALID_STATE без явной причины, повысьте уровень журнала через esp_log_level_set("rbamp", ESP_LOG_WARN) (или _DEBUG) и повторите вызов: компонент скажет, какой из трёх случаев у вас. rbamp_err_to_str(ESP_ERR_INVALID_STATE) возвращает общее описание: "Wrong call sequence (check log: factory mode / sensor class UNSET / bind batch out of sync)".

rbamp_set_sensor_class / rbamp_set_ct_model* возвращает ESP_ERR_INVALID_ARG

Что вы видите: вызов возвращает ESP_ERR_INVALID_ARG.

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

  1. Недопустимый код модели для класса — допустимые коды зависят от класса датчика: SCT013 принимает {1, 2, 3, 4, 5, 6, 7} (см. таблицу в 03 · Выбор датчика тока); WIRED_CT принимает 1–10 и 12. Код, неизвестный для класса, возвращает ESP_ERR_INVALID_ARG.

  2. Недопустимый индекс канала в поканальной форме rbamp_set_ct_model_ch(dev, channel, code) — должен быть < rbamp_channels(dev).

  3. Недопустимое значение rbamp_sensor_class_t — класс выше 3 возвращает ESP_ERR_INVALID_ARG. Модули, поставляемые откалиброванными вместе с собственным датчиком (RBAMP_SENSOR_WIRED_CT, RBAMP_SENSOR_BUILTIN_CT), не принимают смену класса или модели (ESP_ERR_INVALID_STATE); для накладного клипсового датчика SCT-013 используйте RBAMP_SENSOR_SCT013.

  4. dev == NULL или out == NULL — убедитесь, что rbamp_new() завершился успешно (вернул ESP_OK).

rbamp_commit_address_change возвращает ESP_ERR_TIMEOUT

Если prepare прошёл, а commit возвращает ESP_ERR_TIMEOUT, окно «взведения» истекло (5 секунд после prepare). rbamp_probe() здесь не поможет (модуль отвечает; проблема в конечном автомате). Решение: вызовите rbamp_prepare_address_change() заново и сразу — в той же итерации app_main, без сетевых вызовов между ними — затем rbamp_commit_address_change(). Wi-Fi / MQTT или любой блокирующий ввод-вывод между prepare и commit — главная причина истечения окна.

Подробнее о публичных методах с предупреждением см. 09 · Справочник API, раздел «Конфигурация датчика».

Чтения срываются при переключении релейных нагрузок (помехи EMI)

Что вы видите: rbamp_read_* периодически возвращает ESP_FAIL / ESP_ERR_INVALID_RESPONSE, но только пока на той же установке активно переключается реле или индуктивная нагрузка. В установившемся режиме чтения надёжны.

Причина (аппаратно подтверждено, C.12): во время переключения реле (нагрузка 5 А) помехи EMI срывают ~67% транзакций I²C (~8 из 12 при измерении на стенде). Шина восстанавливается сама, зависания не происходит, модуль не теряется — но текущее чтение не удаётся.

Решение — повтор на уровне приложения:

C
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
    for (int attempt = 0; attempt < 5; attempt++) {
        esp_err_t err = rbamp_read_voltage(dev, 0, v);
        if (err == ESP_OK) return ESP_OK;
        vTaskDelay(pdMS_TO_TICKS(20));   // short pause before retry
    }
    return ESP_FAIL;
}
Безопасность

⚠ Одного сброса шины со стороны мастера bus_reset недостаточно: когда помеха EMI накладывается на окно повторов драйвера, нужен явный повтор на уровне приложения с паузой.

Альтернатива: если мастер видит события переключения реле — задержите чтения примерно на 50–100 мс после коммутации.

Перезагрузка по task-WDT при помехах EMI / тяжёлой нагрузке

Что вы видите: ESP32 неожиданно перезагружается с причиной TASK_WDT. Обычно это происходит во время событий EMI (переключение реле, индуктивные переходные процессы).

Причина: при чтениях, замедленных помехами (циклы NACK-повтора + сброса шины), драйвер ESP-IDF i2c_master может растянуть транзакцию до ~100 мс и более. Если задача выполняет плотный цикл массового чтения без передачи управления — срабатывает таймаут сторожевого таймера задачи.

Решение — уступить управление в цикле массового чтения:

C
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}

// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
    vTaskDelay(1);   // yield + WDT feed
}

Альтернатива: явный вызов esp_task_wdt_reset(), если задача отслеживается сторожевым таймером.

Сводная таблица кодов ошибок

Функции rbamp_* возвращают стандартные значения esp_err_t. rbamp_err_to_str(err) возвращает читаемую строку.

Код Когда Где искать
ESP_OK (0) успех —
ESP_FAIL (-1) NACK после повтора; либо фильтр адекватности отклонил значение Раздел «Модуль не отвечает по I²C»
ESP_ERR_INVALID_ARG (0x102) dev == NULL, channel/phase вне диапазона, нераспознанный cls, значение, которое модуль отклоняет проверьте аргументы вызова
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready истёк (модуль не отвечает) ИЛИ истекло окно 5 с между prepare_address_change и commit_address_change для wait_ready — через rbamp_probe(); для commit — повторное взведение: prepare + commit подряд, без блокирующего ввода-вывода между ними
ESP_ERR_INVALID_STATE (0x103) предусловие: set_ct_model* до set_sensor_class раздел set_* выше
ESP_ERR_NOT_SUPPORTED (0x106) функция недоступна на текущем SKU (например, API напряжения на варианте I*) проверьте rbamp_line(dev) и rbamp_variant(dev)
ESP_ERR_INVALID_RESPONSE (0x108) снимок периода устарел; либо REG_VERSION = 0/0xFF при rbamp_begin Раздел «Снимки периода всегда устарели» / «Модуль не отвечает»
ESP_ERR_NO_MEM (0x101) не удалось выделить память для дескриптора проверьте бюджет кучи (esp_get_free_heap_size())

Отладка на уровне шины логическим анализатором

Для глубокой отладки, когда компонент уже не может сказать, что происходит на линии, снимайте SDA + SCL логическим анализатором (Saleae, DSLogic Plus, совместимый с Sigrok):

  • Частота дискретизации ≥ 1 MS/s при I²C 100 кГц; ≥ 4 MS/s при 400 кГц.
  • Декодер I²C в Sigrok / Saleae покажет ACK / NACK для каждого байта и фазу адреса.

  • Сравните вызовы в вашем коде (rbamp_read_voltage() и т. п.) с ожидаемой последовательностью байтов — они должны совпадать точно. Пакетные чтения (несколько байтов за одну транзакцию через автоинкремент адреса) поддерживаются.

Если поведение компонента расходится с записью захвата, откройте обращение и приложите файл захвата (.sal / .dsl / .csv).

Когда обращаться в поддержку

Если вы прошли соответствующий раздел выше, а проблема сохраняется, создайте обращение:

github.com/rb-amp/rbamp-esp-idf/issues

В обращении укажите:

  • Целевой SoC (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + версия ESP-IDF (вывод idf.py --version).

  • Версия компонента rbamp (например, 1.1.0).

  • Версия прошивки модуля — rbamp_firmware_version(dev) в журнале.

  • Минимальный проект IDF, воспроизводящий проблему (~30 строк кода в main/main.c).

  • Значения esp_err_t + rbamp_err_to_str(err) в момент сбоя, из журнала с тегом rbamp.

  • Соответствующий Kconfig: CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_LOG_LEVEL_*.

  • (Если доступно) файл захвата логическим анализатором с момента сбоя.

  • 05 · Быстрый старт — ваш первый рабочий проект
  • 09 · Справочник API — полный API + предупреждения по публичным методам с ПРЕДУПРЕЖДЕНИЕМ + раздел Kconfig

  • 03 · Выбор датчика тока — таблица моделей SCT-013, топология двойного CT для широкого динамического диапазона, подходы к повышению чувствительности при малых токах


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