rbAmp
RU
Магазин
Документация

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

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

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

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

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

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

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

Для нетерпеливых: счётчики dev.retryExhaustionCount() и dev.sanityRejectCount() в установившемся режиме должны быть 0. Если нет — переходите сразу к разделу «Модуль не отвечает по I²C» ниже.

Проверьте сначала: U=0 → L/N не подключены или автомат выключен; I=0 → гнездо CT не вставлено до конца (или модель CT не задана, см. ниже).

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

Что вы видите: dev.begin() возвращает false с lastError() == RB_ERR_NACK, либо рабочие чтения регулярно «протекают» RB_ERR_NACK в пользовательский код.

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

Сначала убедитесь, что модуль вообще есть на шине:

C++
#include 

void setup() {
    Serial.begin(115200);
    Wire.begin();
    Serial.println(F("Scanning..."));
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        Wire.beginTransmission(addr);
        if (Wire.endTransmission() == 0) {
            Serial.print(F("Found 0x")); Serial.println(addr, HEX);
        }
    }
}
void loop() {}

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

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

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

  • Напряжение питания модуля фактически 5 В (4.5–5.5 В) — старые ревизии плат не терпят 3.3 В.

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

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

C++
RbAmp dev(Wire, 0x52);   // address from the bus scan

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

Если сканирование шины находит модуль, но dev.readVoltage() периодически возвращает NaN с RB_ERR_NACK, а вы работаете на ESP32, это задокументированный типовой признак: драйвер i2c_master ESP-IDF v5 имеет особенности при работе с rbAmp на прошивке v1.0.

Защита уже встроена в библиотеку (RBAMP_NACK_RETRY_ATTEMPTS=3 по умолчанию на ESP32), но при сильной нагрузке запас повторов может закончиться.

Что делать на ESP32:

  1. Снизьте скорость шины до 50 кГц:
C++
Wire.begin();
Wire.setClock(50000);
  1. Увеличьте число повторных попыток для тяжёлой нагрузки:
C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include 
  1. Следите за счётчиком исчерпания повторов: в установившемся режиме он должен оставаться нулевым:
C++
if (dev.retryExhaustionCount() > 0) {
    Serial.print(F("WARN: retry exhausted: "));
    Serial.println(dev.retryExhaustionCount());
}

Шаг 3 — NACK на платформах, отличных от ESP32

На AVR / STM32duino / ESP8266 / SAMD / RP2040 базового шаблона NACK нет — на этих платформах доля NACK с rbAmp около 0 %. Библиотека по умолчанию задаёт на них RBAMP_NACK_RETRY_ATTEMPTS=1.

Если здесь возникают NACK, проверьте:

  • Высокая ёмкость шины — длинные провода + много устройств. Снизьте скорость до 100 кГц или укоротите кабель.

  • Конкуренция мастеров — библиотека не поддерживает конфигурацию с несколькими мастерами.

  • Плавающий SCL между транзакциями — отсутствует подтяжка.

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

Что вы наблюдаете: dev.readCurrent(0) возвращает 0.000 (или очень малое значение), хотя реальный потребитель включён (чайник, лампа, утюг). dev.readPowerFactor(0) может показывать странное значение (NaN / 0 / ±1) — это следствие; причина в токе.

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

  1. Проверьте, что настроены класс датчика и модель CT:
C++
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
    Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) {   // or your model: see below
    Serial.println(F("model set failed"));
}

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

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

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

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

Если все три шага пройдены, а ток всё равно нулевой

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

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

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

  • Правильно ли вы зажимаете провод — только один проводник, фаза (L); никогда весь кабель целиком.

Показания прыгают или возвращают NaN

Что вы наблюдаете: dev.readVoltage() или dev.readCurrent() периодически возвращают NaN. dev.lastError() показывает либо RB_ERR_NACK, либо RB_ERR_NON_PHYSICAL.

Если lastError() показывает RB_ERR_NACK

См. раздел «Модуль не отвечает по I²C» выше — это тот же класс проблемы с одним отличием: связь частично работает, но запас повторов иногда заканчивается.

Steps:

  1. На ESP32 — снизьте скорость до 50 кГц и увеличьте RBAMP_NACK_RETRY_ATTEMPTS=5.

  2. На других платформах проверьте ёмкость шины и подтягивающие резисторы.

  3. Следите за dev.retryExhaustionCount(), чтобы видеть тенденцию.

Если lastError() показывает RB_ERR_NON_PHYSICAL

Фильтр корректности библиотеки сработал: с шины пришло значение float, которое является NaN, или Inf, или |x| > 10000 — очевидно не физическая величина. Библиотека отбрасывает такое значение и сообщает RB_ERR_NON_PHYSICAL, вместо того чтобы передавать мусорные данные в приложение.

Это редкий артефакт. Установившееся значение dev.sanityRejectCount() — 0. Если оно не нулевое:

  1. Проверьте dev.retryExhaustionCount(). Если оба счётчика ненулевые, связь нестабильна, а фильтр корректности отсекает мусор после неудачных повторов. Увеличьте бюджет повторов (см. выше).

  2. Если retryExhaustionCount == 0, но sanityRejectCount > 0, значит, артефакт прошёл через слой повторов. Это случается при очень высокой нагрузке на шину. Увеличьте RBAMP_NACK_RETRY_ATTEMPTS=5 и повторите тест.

C++
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F("  sanity rejects: "));
Serial.println(dev.sanityRejectCount());

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

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

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

Нагрузка Ожидаемый 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 выражение не определено. Конкретное значение зависит от прошивки (это может быть NaN, 0 или заполнитель) — это норма, пока ток действительно равен нулю. Как только появится ток, появится и корректный PF.

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

Клещ установлен «задом наперёд» — стрелка не указывает в направлении тока к нагрузке. Исправление: переустановите клещ правильно (физически переверните; не инвертируйте знак программно).

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

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

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

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

Что вы видите: dev.readPeriodSnapshot(snap) возвращает false с lastError() == RB_ERR_STALE. Это значит, что модуль не успел проинтегрировать предыдущий период к моменту следующего чтения.

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

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

Порядок проверки периодичности

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

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

C++
if (dev.probe()) {
    Serial.println(F("alive"));
}
  1. Прямая проверка флага — dev.isPeriodValid() выполняет однобайтовое чтение без побочных эффектов.

  2. Проверьте версию прошивки — dev.firmwareVersion() должна показать 0x04 (v1.3, текущий выпуск); прошивки старше (0x01 v1.0 / 0x02 v1.1 / 0x03 v1.2) дают больше устареваний.

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

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

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

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

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

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

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

Платформа Тип накопителя
ESP32 / ESP8266 / STM32duino / SAMD / RP2040 double 64 бита
Arduino AVR (Uno, Mega, Nano) 32-битный float (тулчейн)

Интеграция на стороне мастера не добавляет собственной погрешности сверх точности модуля по активной мощности.

На AVR при долгих установках периодически сбрасывайте накопитель и сохраняйте долгосрочный итог в собственное постоянное хранилище:

C++
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);

snap.latch_ms отличается от реального периода

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

RB_ERR_STALE на каждом чтении — мастер автоматически удерживает якорь

Что вы наблюдаете: dev.readPeriodSnapshot(snap) периодически возвращает false с lastError() == RB_ERR_STALE. (См. также раздел «Снимки периода всегда устаревшие» выше.)

Канонический порядок обработки dt: при устаревшем чтении библиотека Arduino НЕ обнуляет свой внутренний якорь _last_latch_ms. Следующее корректное чтение получает master_dt, равный полному интервалу с предыдущего успешного снимка, — то есть охватывает и «потерянный» устаревший период, и текущий. Прошивка сохраняет накопитель avg_p через пустой снимок (сохранение на стороне прошивки): при следующем корректном снимке это уже значение, усреднённое по всему интервалу. Интегрирование Wh остаётся точным — ни двойного учёта, ни недоучёта.

В коде мастера специальная обработка устаревания не нужна: библиотека делает всё правильно и автоматически. Просто игнорируйте RB_ERR_STALE, если он редок; если частый — диагностируйте частоту (раздел выше).

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

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

Wire зависает на пограничной шине — трёхуровневая защита

Что именно вы наблюдаете: скетч на ESP32 (ядро Arduino-ESP32) нормально опрашивает rbAmp несколько минут, затем «зависает» посреди вызова dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Если включён task-WDT, он перехватывает зависание; иначе скетч просто перестаёт отвечать. Расшифрованный backtrace заканчивается на функции i2c_ll_is_bus_busy (драйвер IDF i2c_master, файл i2c_master.c:526, ожидание занятости шины перед отправкой).

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

Это не «артефакт, видимый только в отладчике». Проверено на стенде (тот же аппаратный стенд и нагрузка):

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

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

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

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

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

  3. Прикладной WDT задачи на задаче опроса — защита в глубину. Если по какой-то причине подтяжки остались пограничными или возникла другая причина зависания, WDT перезагрузит скетч. Стендовый 12-минутный прогон: WDT поймал и восстановил все 12 зависаний в конфигурации без внешней подтяжки. Нормальные подтяжки шины — полевое исправление; прикладной WDT — позиция восстановления.

C++
#include "esp_task_wdt.h"

void setup() {
    // Layer 3 setup — defense-in-depth.
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 8000,            // 8 s with a large margin
        .idle_core_mask = 0,
        .trigger_panic = true,         // on timeout — panic+reboot
    };
    esp_task_wdt_reconfigure(&wdt_cfg);
    esp_task_wdt_add(NULL);            // this task (loop) under WDT

    // ... rest of the initialization ...
}

void loop() {
    fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
    // ... processing ...
    esp_task_wdt_reset();              // "I'm alive" — every cycle
    delay(200);
}

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

Тайм-аут сторожевого таймера в wifi_connect()

Причина: неограниченный цикл while (WiFi.status() != WL_CONNECTED) delay(500) вызывает task-WDT примерно через 5 с (по умолчанию).

Исправление: ограниченное ожидание с запасным перезапуском:

C++
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    if (millis() - t0 > 30000) { ESP.restart(); }
}

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

Причина: PubSubClient по умолчанию использует keepalive = 15 с, а mqtt.loop() вызывается только в «медленном» пути (раз в 60 с вместе с readPeriodSnapshot()).

Исправление: установите keepalive 60 с и вызывайте mqtt.loop() на каждом проходе loop():

C++
mqtt.setKeepAlive(60);

void loop() {
    if (!mqtt.connected()) mqtt.connect("rbamp-id");
    mqtt.loop();    // every iteration, not once every 60 s
    // ...rest of the logic, slowed down via millis()...
}

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

Причина: heap ESP32 недостаточен для рукопожатия TLS (нужно ~30 kB). Часто это сочетается с WiFi + MQTT + буферами — остаётся < 20 kB.

Fix:

  • Уменьшите setBufferSize() для клиента MQTT до минимума.
  • Используйте WiFi.mode(WIFI_STA) (не WIFI_AP_STA).
  • Отключите BLE: btStop() в setup().

Если ESP.getFreeHeap() показывает < 25 kB до client.connect(), рукопожатие TLS, скорее всего, не пройдёт.

setSensorClass() / setCTModel() возвращает RB_ERR_PARAM

Что вы видите: один из вызовов конфигурации возвращает false, lastError() == RB_ERR_PARAM.

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

  1. setCTModel() вызван раньше setSensorClass(). Сначала класс датчика, затем модель — см. 03 · Выбор токового датчика и 09 · Справочник API § Конфигурация датчика.

  2. Недопустимый код модели — для класса Sct013 допустимый набор {1, 2, 3, 4, 5, 6, 7} (коды 5 и 7 — это SCT-013-100 и SCT-013-060). Для других классов см. таблицу допустимых наборов по классам в 03 · Выбор токового датчика. Коды, не соответствующие классу, возвращают RB_ERR_PARAM (защита на стороне библиотеки до шины) или DEV_ERR_PARAM (на стороне прошивки, если YAML всё же прошёл).

  3. Недопустимый индекс канала в побканальной форме setCTModel(channel, code) — он должен быть < dev.channels(). Канал на или за пределом RBAMP_MAX_CHANNELS (7) никогда не выставляется и тоже возвращает RB_ERR_PARAM.

  4. Модуль отверг код — код, который есть в реестре, но который модуль не принимает, отвергается самим модулем; канал сохраняет предыдущую модель.

Если вызов возвращает false с RB_ERR_MODE, значит модуль заводского парного класса (WiredCT / BuiltinCT) — он поставляется и калибруется вместе со своим датчиком, и сеттеры его не перезаписывают. Переподключение в сервисе — через setCTModelChForce().

Ожидаемое поведение, не неисправность:

  • Установка класса или модели, которые модуль уже держит, — пустая операция (true, без записи в шину, без цикла флеша).

  • Установка модели CT перезапускает модуль на прошивке BASIC до 1.4.19 с классом SCT-013 (около секунды, блокирующе). В это время показания недоступны; библиотека затем заново читает коррекцию номинала.

  • После переключения модели SCT-013 показания тока, мощности и энергии автоматически следуют новому номиналу (коэффициент мощности и напряжение не затрагиваются). dev.sctRating(ch, r) показывает статус по каждому каналу; если он сообщает UnexpectedGain или Unknown, коррекция не применяется (масштаб 1).

Заметки по модулям STD (STANDARD)

Линия STD использует ту же проводку I²C, что и BASIC (см. 04 · Подключение); dev.begin() определяет её, а dev.line() сообщает, какая линия у вас. Особенности STD:

  • RB_ERR_NOT_IMPLEMENTED от вызова std*, readReactivePower() или readApparentPower() — подключён модуль BASIC (проверьте dev.line()). И наоборот, вызовы только для BASIC (factoryReset(), General-Call, помощники меток, readCapability(), readCommitSeq()) возвращают его на модуле STD.

  • Функция показывает «недоступно» — энергия микроразрешения (RbAmpStdEnergy::fine == false), пусковой ток для энергии (RB_ERR_NOT_IMPLEMENTED), фазовые углы напряжения (angle_valid == false) и порядок фаз (NotAvailable) зависят от версии образа модуля: им нужен образ не ниже 0x0001007B. Прочитайте его через dev.stdReadImageVersion(); на более старом образе значение недоступно, а не неверно.

  • Фазовый угол напряжения / порядок фаз остаются «недоступно» на свежем образе — им нужны все входы напряжения под напряжением и измеримые, а для порядка фаз — трёхфазный модуль по напряжению.

  • Чтение снимка периода возвращает пустоту (RB_ERR_STALE) после перезапуска модуля — это ожидаемо: взведение снимка живёт в RAM модуля. Библиотека переводит банк во взведённое состояние и отбрасывает один период; перезапустите собственную привязку dt. Выдерживайте не менее 300 мс между stdLatch() и stdReadLatch().

  • Нет записей истории — модуль записывает историю только при установленных часах. Часы сбрасываются при каждом перезапуске модуля: вызывайте dev.stdSetTime() после begin() и всякий раз, когда stdReadHealth() сообщает time_valid == false.

  • Команда возвращает RB_ERR_PARAM — на STD вердикт каждой команды читается обратно; модуль отверг значение и не изменился.

  • Сохранение возвращает RB_ERR_NOT_READY — модуль ограничивает частоту записи своего хранилища; библиотека уже один раз повторяет попытку через 5 с.

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

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

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

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

C++
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02);   // IMMEDIATELY, before the next write

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

C++
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
    uint8_t last_err = dev.readReg(0x02);
    // handle
    dev.writeReg(0x2A, (1 << 3));        // W1C clear bit3
    // or dev.clearError();
}
Безопасность

⚠ REG_ERROR — исход последней записи, не липкий. Устойчивость обеспечивает EVENT bit3.

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

lastError() против readLastError() — два разных канала, не синонимы

Две функции с похожими именами, но совершенно разной семантикой:

lastError() readLastError(out)
Что он возвращает Закэшированный код RB_ERR_* от предыдущего вызова библиотеки Одно чтение провода регистра устройства REG_ERROR (0x02)
Операция I²C? Нет — просто чтение памяти Да — одна транзакция чтения
Семантика Итог проверки на стороне библиотеки (защита клиента, состояние повторов и т. п.) Результат последней записи на стороне устройства (мнемоника DEV_ERR_*)
Когда обновляется После каждого метода библиотеки После каждой записи, принятой шиной на устройстве
Пример значения RB_ERR_PARAM после защиты на стороне клиента 0xFE (DEV_ERR_PARAM) после отклонённой записи на устройстве
Пример несоответствия lastError() == RB_ERR_PARAM (сеттер заблокировал вызов до шины) readLastError() → 0x00 (ничего не дошло до устройства)

Когда что применять:

  • lastError() — для логики приложения, разбора исходов на стороне библиотеки (повтор, откат, классификация ошибок) без накладных расходов I²C.

  • readLastError() — когда нужен расширенный код причины со стороны устройства (например, DEV_ERR_PARAM (0xFE) против DEV_ERR_NOT_READY против DEV_ERR_FLASH_PARAMS_BAD (0xFB)) на Канале B (отказ на стороне DUT). См. раздел «модель ошибок v1.3 — два независимых канала» в 09 · Справочник API.

Различие особенно важно при отладке канала A (защита на стороне клиента): сеттер возвращает false + lastError() == RB_ERR_PARAM, но readLastError() == 0x00, потому что библиотека заблокировала вызов до операции на линии, и REG_ERROR на устройстве не был затронут.

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

Модуль с новой прошивкой при первом включении показывает 0xFB (NORMAL)

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

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

Исправление: настройте sensor_class + ct_model + (при необходимости) адрес, затем dev.saveUserConfig(). После успешного SAVE → REG_ERROR = 0x00, bit3 сброшен.

commitAddressChange() возвращает RB_ERR_TIMEOUT

Что вы наблюдаете: prepareAddressChange() прошёл, но commitAddressChange() возвращает false, lastError() == RB_ERR_TIMEOUT.

Причина: истекло окно взведённого состояния (5 с после prepareAddressChange). Главный источник истечения окна — WiFi/MQTT или любой блокирующий ввод-вывод между prepare и commit. dev.probe() здесь не поможет (модуль отвечает; проблема в конечном автомате).

Что делать: вызовите prepareAddressChange() снова и сразу, в той же итерации loop(), без сетевых вызовов между ними, вызовите commitAddressChange().

Примечание

✅ REG_I2C_ADDRESS (0x30) теперь читает АКТИВНЫЙ адрес при загрузке (v1.3). После перезагрузки после фиксации чтение 0x30 покажет новый активный адрес. Для наиболее надёжной проверки двухфазной фиксации адреса попробуйте чтение по новому адресу (он должен получить ACK на шине). После записи мастером (подготовка) регистр повторяет подготовленного кандидата до CMD_COMMIT_ADDR и сброса — это поведение по замыслу.

Подробнее о двухфазной фиксации адреса см. 09 · Справочник API и 04 · Подключение.

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

Что вы видите: dev.readVoltage() / dev.readCurrent() периодически возвращают NAN, lastError() == RB_ERR_NACK или RB_ERR_IO — но только во время активного переключения реле или индуктивной нагрузки на той же установке. Чтения в установившемся режиме надёжны.

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

Исправление — повтор на уровне приложения:

C++
float robust_read_voltage(RbAmp& dev) {
    for (int attempt = 0; attempt < 5; attempt++) {
        float v = dev.readVoltage();
        if (!isnan(v)) return v;
        delay(20);   // a short pause before the retry
    }
    return NAN;
}
Безопасность

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

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

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

dev.lastError() возвращает один из этих кодов после каждого публичного вызова API. RbAmp::errorString(code) возвращает читаемую строку.

Код String Когда Где искать
RB_OK (0) "OK" успех —
RB_ERR_IO (-1) "Сбой транспорта I2C" драйвер шины вернул не OK проводка, питание, подтяжки
RB_ERR_NACK (-2) "NACK — устройство отсутствует или занято" повторы исчерпаны Раздел «Модуль не отвечает по I²C»
RB_ERR_TIMEOUT (-3) "Bus timeout" истекло окно waitReady / waitDataReady / commitAddressChange раздел «commitAddressChange() возвращает RB_ERR_TIMEOUT»
RB_ERR_NOT_READY (-4) «Устройство не готово» модуль не готов / такой записи истории нет / ничего не взведено / по новому адресу никто не отвечает замечания по STD выше
RB_ERR_STALE (-5) "Снимок периода устарел" флаг готовности периода = 0 Раздел «Снимки периода всегда устарелые»
RB_ERR_PARAM (-6) «Неверный параметр» недопустимый индекс канала / недопустимый код модели / недопустимый диапазон адресов раздел «setSensorClass() / setCTModel() возвращает RB_ERR_PARAM»
RB_ERR_MODE (-7) «Не разрешено в текущем режиме модуля (нужен заводской режим / сервисный путь)» операция только на заводе, или сеттер CT на модуле класса WiredCT / BuiltinCT не вызывайте операции только для завода на производственной прошивке; используйте setCTModelChForce() только для сервисной перепривязки
RB_ERR_CHECKSUM (-8) "Проверка значения не пройдена — контрольная сумма / подпись / диапазон" значение проверки модуля не прошло (STD: отклонён образ прошивки, CRC полезной нагрузки, эпоха вне диапазона, пустое кольцо истории) повторно отправьте страницу / проверьте образ
RB_ERR_VERSION (-9) «Неподдерживаемая версия прошивки» REG_VERSION = 0 / 0xFF проверьте подключение модуля
RB_ERR_NOT_IMPLEMENTED (-10) "Не реализовано в этой прошивке" у вызова нет аналога на обнаруженной линии, либо образ модуля не предоставляет эту функцию dev.line(), dev.stdReadImageVersion()
RB_ERR_NON_PHYSICAL (-11) "Непредставимое значение (NaN/Inf/вне границ)" фильтр корректности отверг значение float Раздел «Показания прыгают или приходят как NaN»

Сводная таблица диагностических счётчиков

В здоровом долгом прогоне (12 ч, скетч SoakMonitor) все остаются нулевыми:

Счётчик Установившийся режим Сброс
dev.retryExhaustionCount() 0 dev.resetCounters()
dev.sanityRejectCount() 0 dev.resetCounters()
dev.lastError() после чтения RB_OK (0) автоматически при следующем вызове
доля устаревших значений в снимках периода < 1 % (накопительно — без сброса)

Если любой из этих счётчиков ненулевой в установившемся режиме, вернитесь к соответствующему разделу выше.

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

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

  • Частота дискретизации ≥ 1 MS/s при I²C 100 кГц; ≥ 4 MS/s при 400 кГц.
  • Декодер I²C в Sigrok / Saleae покажет ACK / NACK на каждом байте
  • фаза адреса.
  • Сравните вызовы вашего скетча (dev.readVoltage() и т. п.) с ожидаемой последовательностью байт — они должны совпадать точно. Пакетные чтения (несколько байт одной транзакцией через автоинкремент адреса) поддерживаются. Записи НЕ с автоинкрементом — каждый байт отдельная транзакция.

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

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

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

github.com/rb-amp/rbamp-arduino/issues

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

  • Хост-MCU и версия ядра Arduino (например, ESP32-S3 на Arduino-ESP32 3.0.4).

  • Версия библиотеки (RbAmp из Library Manager).

  • Версия прошивки модуля — dev.firmwareVersion().
  • Минимальный скетч, воспроизводящий проблему (~30 строк кода).
  • dev.lastError() + dev.errorString(dev.lastError()) + dev.retryExhaustionCount() + dev.sanityRejectCount() в момент сбоя.

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


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