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

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

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

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

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

  1. Уровень шины — модуль не отвечает по I²C; чтения выбрасывают RbAmpIOError.

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

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

Краткий путь для нетерпеливых: в установившемся режиме публичные методы должны возвращать значения / выдавать снимки без исключений. Если в логах часто RbAmpIOError или RbAmpStaleError, сразу перейдите к разделу «Модуль не отвечает по I²C» ниже.

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

Что вы видите: dev.begin() (или вход в контекстный менеджер with RbAmp(bus, 0x50) as dev:) возбуждает RbAmpIOError или RbAmpVersionError, либо чтения RT регулярно возбуждают RbAmpIOError.

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

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

CPython (Linux SBC)

Внешний инструмент:

Shell
i2cdetect -y 1     # bus 1 — the standard one on the RPi 40-pin header

Или Python:

Python
from smbus2 import SMBus

with SMBus(1) as bus:
    print("Scanning...")
    for addr in range(0x08, 0x78):
        try:
            bus.write_quick(addr)
            print(f"Found 0x{addr:02X}")
        except OSError:
            pass

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

MicroPython

Python
from machine import I2C, Pin

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
print("Found:", [hex(a) for a in i2c.scan()])

Ожидаемый вывод: Found: ['0x50'] (или ваш адрес).

Что делать, если ничего не найдено

Проблема в проводке или питании:

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

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

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

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

  • На MicroPython проверьте, что freq=50_000 (не 100k и не 400k — на ESP32 с прошивкой v1 базовый паттерн NACK съест бюджет повторов).

  • На CPython проверьте, включён ли драйвер ядра I²C — lsmod | grep i2c_bcm на RPi.

Что делать, если модуль появился на неожиданном адресе

Кто-то переназначил его ранее на стенде. Обновите второй аргумент RbAmp:

Python
dev = RbAmp(bus, 0x52)   # address from the bus scan

Шаг 2 — шаблон NACK-базовой линии MicroPython + ESP32

Если сканирование шины находит модуль, но dev.read_voltage() периодически возбуждает RbAmpIOError, и вы работаете на MicroPython + ESP32 — это задокументированный базовый паттерн: стек I²C порта MicroPython на ESP32 унаследовал особенности драйвера ESP-IDF v5, который при обмене с rbAmp на текущей прошивке даёт частые NACK на 100 кГц.

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

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

  1. Снизьте скорость шины до 50 кГц:
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Увеличьте число повторов для тяжёлой нагрузки — для этого нужен расширенный API с явным созданием бэкенда:
Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5, retry_gap_ms=5)
dev = RbAmp(backend, 0x50)   # the address goes to RbAmp, not to the backend
  1. Следите за счётчиком исчерпания повторов: в установившемся режиме он должен оставаться нулевым:
Python
if backend.retry_exhaustion_count > 0:
    print("WARN: retry exhausted:", backend.retry_exhaustion_count)

Шаг 3 — платформы, отличные от ESP32 (RP2040 / STM32 / CPython)

На RP2040 / STM32 / Pyboard (через MicroPython) базового паттерна NACK нет — на этих платформах доля NACK с rbAmp около 0 %. MachineI2CBackend автоматически определяет порт и понижает значение повторов по умолчанию до 1 попытки.

На CPython (через smbus2) слоя повторов вообще нет — драйвер ядра Linux I²C не подвержен паттерну NACK; единичный OSError от smbus2 переводится в RbAmpIOError без повтора.

Если на этих платформах всё же возникают NACK, ищите:

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

  • Конкуренция мастеров — пакет не поддерживает multi-master.

  • Плавающий SCL между транзакциями — отсутствует подтяжка.
  • На RPi: проверьте dtparam=i2c_arm_baudrate в /boot/config.txt — рекомендуется 100000.

PermissionError: [Errno 13] на /dev/i2c-1 (Linux)

Что вы видите: SMBus(1) возбуждает PermissionError, а sudo python работает. Вашему пользователю не разрешено открывать I²C-устройство. Исправление:

Shell
sudo usermod -aG i2c $USER   # then log out and in again

Также убедитесь, что I²C включён (sudo raspi-config → Interface Options → I2C) и что ls /dev/i2c-* показывает шину; sudo apt install i2c-tools даёт i2cdetect -y 1.

Ток нулевой при работающей нагрузке

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

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

  1. Проверьте, что настроены класс датчика и модель CT:
Python
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass, RbAmpModeError

try:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
except RbAmpError as e:
    print("set_sensor_class failed:", e)

try:
    dev.set_ct_model(3)   # or your model — see the table in 03
except RbAmpModeError:
    print("Class must be set first!")
except ValueError:
    print("Code not in per-class accept-set (SCT_013: {1,2,3,4,5,6,7})")

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

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

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

  1. Проверьте ориентацию клещей. Стрелка на корпусе клещей должна указывать в направлении тока к нагрузке. Если клещи установлены «задом наперёд», dev.read_current() даст правильное значение по модулю, но dev.read_power() даст отрицательное значение на потребляющей нагрузке. Подтверждение — dev.read_power_factor() покажет ровно −1.0 на активной нагрузке (вместо +1.0). Исправление: либо физически переустановите клещи (расстегните, поверните стрелку правильно, защёлкните обратно), либо инвертируйте знак на стороне приложения (p = -p; pf = -pf;, если вы знаете, что нагрузка — не инвертор ФЭС).

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

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

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

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

  • Охватываете ли вы правильный провод — только один проводник, живой провод (L), а не весь кабель (если захватить L и N, получится ~0).

Показания скачут или возникает RbAmpIOError

Что вы видите: dev.voltage / dev.read_current(...) периодически возбуждает RbAmpIOError. Значение свойства не получено — нужен повтор на стороне приложения или обёртка try/except.

RbAmpIOError из пакета охватывает два класса проблем:

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

Различайте их по диагностическим счётчикам (доступны на MicroPython):

Python
from rbamp._io_micropython import MachineI2CBackend

# Build the backend yourself, then pass IT (not the raw I2C object) to RbAmp.
# This is where `backend` comes from; the address belongs to RbAmp.
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)

# After a period of operation:
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)
Счётчик Что это означает
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 Шина исправна; пакет незаметно восстанавливается после редких NACK. Это нормально.
retry_count_total ↑, retry_exhaustion_count ↑ Плато NACK — увеличьте retry_attempts (см. Шаг 2 выше).
retry_count_total низкий, sanity_reject_count растёт Фильтр достоверности отлавливает мусор после неудачных повторов. Увеличьте retry_attempts=5+.

На CPython (SMBusBackend) слоя повторов нет — RbAmpIOError выбрасывается при первом же сбое. Симптомы редки (ядро Linux обычно надёжно), но если они появляются, проверьте проводку, подтяжки и скорость шины.

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

Что вы видите: dev.power_factor[0] (или dev.read_power_factor(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 на чисто потребляющей нагрузке

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

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

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

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

Снимки периода всегда дают RbAmpStaleError

Что вы видите: dev.read_period_snapshot() выбрасывает RbAmpStaleError при каждом вызове. Это значит, что модуль не завершил интегрирование предыдущего периода ко времени следующего чтения.

При устаревшем чтении пакет сохраняет предыдущую метку времени, поэтому следующий успешный снимок покрывает весь интервал с последнего хорошего и итог Wh остаётся точным (без двойного учёта и без потерь).

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

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

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

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

Python
if dev.probe():
    print("alive")
  1. Проверьте флаг напрямую:
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. Проверьте версию прошивки — dev.firmware_version >= 0x04 (v1.3) даёт меньше всего устаревших чтений; 0x02/0x03 (v1.1/v1.2) поддерживаются, но доля устаревших чтений выше; 0x01 (v1.0) — самая шумная.

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

Если вы используете паттерн deep-sleep на MicroPython, стандартный dev.read_period_snapshot() после входа в контекстный менеджер всегда даст устаревший (или почти нулевой) результат — __enter__ делает прайм-снимок (команда LATCH), который сбрасывает накопитель прошивки. Канонический шаблон использует skip_latch=True + известную длительность сна (аргумент machine.deepsleep(SLEEP_MS)) — см. 06 · Examples, Сценарий 9.

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

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

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

  1. Калибровка датчика тока: убедитесь, что dev.set_sensor_class() и dev.set_ct_model() вызваны с правильной моделью CT (см. 03 · Current sensor selection). Без этого RMS-ток считается с порогом по умолчанию, и значение мощности будет систематически смещено.

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

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

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

⚠ Переполнение ticks_ms() на MicroPython. time.ticks_ms() переполняется при 2**30 мс (~12.4 дня) — наивное вычитание t1 - t0 через границу 12.4 дня даёт отрицательное или огромное число. Внутри пакет использует time.ticks_diff(t1, t0), который безопасен к переполнению. Если вы вычисляете master_dt_ms сами (вне пакета), используйте ticks_diff, а не прямое вычитание.

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

Накопитель Wh внутри дескриптора:

Среда выполнения Тип
CPython 64-битный float (Python float)
MicroPython (сборка с двойной точностью) 64-битный float
MicroPython на портах без double-float 32-битный float

Проверка точности на MicroPython (sys.float_info есть только на CPython; на uPy используется эмпирическая проверка):

Python
# On CPython:
import sys
print(sys.float_info.dig)   # 15 → double; 7 → single

# On MicroPython — empirically:
import sys
print(sys.implementation.name)   # 'micropython'
test = 1.0 + 1e-15
print("double" if test != 1.0 else "single")   # 1.0 + 1e-15 != 1.0 only on double

Для MicroPython-портов с плавающей точкой одинарной точности в длительных прогонах периодически сбрасывайте dev.energy.reset(0) и храните долгосрочный итог в собственном постоянном хранилище (например, через MQTT-сообщение с retain в HA).

Скрипт зависает или падает по таймауту

Что вы видите: скрипт на Python запускается нормально, затем через несколько минут зависает или выдаёт RuntimeError.

MicroPython на ESP32: операция I²C зависает на слабой шине — трёхуровневая защита

Что вы видите конкретно: скрипт на ESP32 (MicroPython machine.I2C) нормально опрашивает rbAmp несколько минут, затем «мёртво» зависает в середине вызова dev.read_period_snapshot() / fleet.poll_all(). WDT (если включён) ловит зависание; иначе скрипт просто перестаёт отвечать. Если у вас есть REPL, он тоже зависает.

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

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

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

Корреляция очевидна — исправление целостности шины полностью устраняет зависание. Логика библиотеки здесь ни при чём.

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

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

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

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

Python
# MicroPython-on-ESP32
from machine import WDT
import time

wdt = WDT(timeout=8000)   # 8 s

while True:
    snap = dev.read_period_snapshot()
    # ... processing ...
    wdt.feed()             # "I'm alive" — every cycle
    time.sleep_ms(200)

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

CPython на Linux SBC: I²C ядра не страдает от этой проблемы

Драйверы ядра Linux (i2c-bcm2835 на Raspberry Pi, i2c-i801 на x86 и т. д.) выполняют проверку занятости шины с таймаутом — на зависшей шине они возвращают IOError(Errno 110: ETIMEDOUT) или EREMOTEIO вместо зависания. Библиотека оборачивает это в RbAmpIOError. Поэтому трёхуровневая защита на CPython не нужна — Linux справляется сам. Внешняя подтяжка ~4.7 кОм всё же желательна для целостности сигнала на длинной шине.

latch_ms не совпадает с настенным периодом

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

Библиотека интегрирует энергию по настенным часам мастера: CPython — time.monotonic(); MicroPython — time.ticks_ms() + time.ticks_diff(). Интегрирование на стороне мастера не добавляет собственной погрешности сверх точности модуля по активной мощности.

Если ваш код опирается на snap.latch_ms для субпериодных вычислений, перейдите на собственные time.monotonic() / time.ticks_diff().

RbAmpStaleError при каждом чтении — библиотека сохраняет якорь автоматически

Что вы видите: dev.read_period_snapshot() периодически возбуждает RbAmpStaleError.

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

Шаблон холодного запуска (prime-until-valid, бюджета примерно на 25 повторов достаточно):

Python
from rbamp import RbAmpStaleError

while True:
    try:
        snap = dev.read_period_snapshot()
        break
    except RbAmpStaleError:
        time.sleep(3.0)

После прогрева просто игнорируйте RbAmpStaleError, если он редкий; если частый — диагностируйте частоту опроса (раздел «Period snapshots are always RbAmpStaleError» выше).

CPython: signal.SIGTERM / KeyboardInterrupt не обрабатываются

Причина: долгий time.sleep(60) блокирует обработчик сигнала. В продуктивном развёртывании (systemd) systemctl stop rbamp ждёт ответа на SIGTERM до таймаута (по умолчанию 90 с), а затем убивает процесс через SIGKILL — Wh может потеряться.

Исправление: цикл с обработкой сигналов:

Python
import signal, time
shutdown = False

def on_sig(sig, frame):
    global shutdown
    shutdown = True

signal.signal(signal.SIGTERM, on_sig)
signal.signal(signal.SIGINT,  on_sig)

while not shutdown:
    snap = dev.read_period_snapshot()
    # ... publish ...
    for _ in range(60):           # wake on signal every second
        if shutdown: break
        time.sleep(1)

Или используйте asyncio с signal_handler — см. раздел ниже.

MicroPython (ESP32): сторожевой таймер срабатывает при подключении к WiFi

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

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

Python
import network, time, machine

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "pass")

t0 = time.ticks_ms()
while not wlan.isconnected():
    time.sleep_ms(100)
    if time.ticks_diff(time.ticks_ms(), t0) > 30_000:
        machine.reset()

Брокер MQTT разрывает соединение

На CPython (paho-mqtt): keepalive по умолчанию 60 с, но mqtt.connect() блокирующий, а mqtt.loop() нужно вызывать в цикле событий. Используйте mqtt.loop_start() (фоновый поток) или асинхронный вариант aiomqtt.

На MicroPython (umqtt.simple): синхронный режим без keepalive — нужно вызывать mqtt.ping() вручную примерно каждые 30 с. Альтернатива — асинхронный пакет mqtt_as со встроенным keepalive.

Сбой рукопожатия TLS (CPython в облако + RPi с малым объёмом RAM)

Редко проблема на Pi с 1+ ГБ ОЗУ, но на Pi Zero / Zero W (512 МБ) рукопожатие TLS с большим хранилищем сертификатов может быть убито OOM-killer.

Fix:

  • Используйте конкретный CA вместо системного ca-certificates — меньше памяти.

  • Уменьшите буферы MQTT.

  • Для промышленного облачного развёртывания перейдите на Pi 3/4/5.

set_sensor_class() / set_ct_model() возбуждает RbAmpModeError

Что вы видите: один из вызовов конфигурации выбрасывает RbAmpModeError с сообщением:

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Причина: set_ct_model[_ch] требует, чтобы перед ним был вызван set_sensor_class(). Это намеренная защита.

Что делать:

Python
from rbamp import RbAmpSensorClass

# Class first — MANDATORY
dev.set_sensor_class(RbAmpSensorClass.SCT_013)

# Then the model
dev.set_ct_model(3)   # or per-channel dev.set_ct_model_ch(ch, code)

Подробнее — 03 · Current sensor selection и 09 · API reference, раздел «Sensor configuration».

Начиная с 1.6.0 эти сеттеры защищены проверкой «сначала чтение, потом запись»:

  • Установка класса или модели, которые модуль уже хранит, — тихий no-op (повторная запись стёрла бы калибровку канала).

  • На модуле с заводской парой (класс WIRED_CT / BUILTIN_CT) другой класс или модель отклоняется с ошибкой RbAmpModeError. В сервисном контексте используйте dev.set_ct_model_ch_force(ch, code).

RbAmpModeError также возникает из dev.factory_reset() и dev.save_gains() (заводские операции требуют заводского режима). Смена адреса на v1.3 допустима в продакшене и не возбуждает RbAmpModeError.

set_sensor_class() / set_ct_model*() вызывает RbAmpParamError или ValueError

Что вы видите: вызов возбуждает RbAmpParamError (на CPython также наследует ValueError через множественное наследование).

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

  1. Недопустимый код модели — для класса SCT_013 допустимый набор — {1, 2, 3, 4, 5, 6, 7} (коды 5 и 7 — это SCT-013-100 и SCT-013-060). Для других классов см. таблицу допустимых наборов по классам в 03 · Choosing an SCT-013 model. Значения вне допустимого набора возбуждают RbAmpParamError(ValueError).

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

  3. Значение класса датчика вне 0..3. (WIRED_CT / BUILTIN_CT — допустимые значения, но заводски спаренный модуль отказывается переконфигурироваться — это возбуждает RbAmpModeError, см. ниже.)

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

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

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

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

Python
dev.save_user_config()
dev_err = dev.read_reg(0x02)   # IMMEDIATELY, before the next write

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

Python
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear bit3
    # or dev.clear_error()
Безопасность

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

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

Важно: DEV_ERR_CLONE (0xF9) не сбрасывается командой CMD_CLEAR_ERROR — это антиклоновый маркер.

Свежепрошитый модуль показывает 0xFB при первом включении (НОРМА)

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

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

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

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

Что вы видите: dev.voltage / dev.current() периодически выбрасывают RbAmpIOError / OSError — но только во время активного переключения реле или индуктивной нагрузки на той же установке. Чтения в установившемся режиме надёжны.

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

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

Python
def robust_read_voltage(dev, attempts=5, gap_s=0.020):
    for _ in range(attempts):
        try:
            return dev.voltage
        except (RbAmpIOError, OSError):
            time.sleep(gap_s)
    raise RbAmpIOError("read failed after retries")
Безопасность

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

commit_address_change() возбуждает RbAmpIOError после сброса шины

Что вы видите: prepare_address_change() прошёл успешно, но после фиксации и сброса модуль не отвечает на новом адресе.

Примечание

✅ v1.3: REG_I2C_ADDRESS (0x30) читает активный адрес при загрузке. После перезагрузки по коммиту чтение 0x30 по новому адресу покажет тот же адрес — это подтверждает, что коммит прошёл. Если модуль не отвечает по новому адресу, выполните скан шины через _io_smbus (покажет, на каком адресе модуль находится на самом деле).

Подробнее о двухфазном коммите — см. 09 · API reference и 04 · Wiring.

commit_address_change() выбрасывает RbAmpTimeoutError

Если prepare прошёл, а commit возбуждает RbAmpTimeoutError, окно «арминга» истекло (5 секунд после prepare). dev.probe() здесь не поможет (модуль отвечает; проблема в его конечном автомате). Исправление: снова вызовите dev.prepare_address_change(new_addr), а затем сразу, в той же функции / той же итерации, без сетевых вызовов между ними, вызовите dev.commit_address_change(). Любой блокирующий ввод-вывод между prepare и commit (WiFi, MQTT, HTTP) — основная причина истечения окна.

wait_ready() выбрасывает RbAmpTimeoutError

Флаг готовности модуля не был выставлен за timeout_ms. Возможные причины:

  • Модуль ещё не закончил холодный старт (~250 мс) — увеличьте timeout_ms или повторите вызов.

  • Модуль не отвечает по I²C — см. раздел «Модуль не отвечает по I²C» выше.

  • Напряжение питания упало ниже 4.5 В — проверьте VCC мультиметром.

Подробнее о публичных, но предупреждаемых методах — см. 09 · API reference, раздел «Sensor configuration» (подраздел про смену адреса находится там же, вместе с save_gains и factory_reset).

RbAmpNotSupportedError (вызовы STD)

Что вы видите: вызов вроде dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() или dev.set_time() возбуждает RbAmpNotSupportedError.

Причины и что делать:

  1. Модуль — BASIC. Вызовы, доступные только для STD, на BASIC недоступны. Проверьте dev.is_std; на BASIC используйте общие чтения (voltage, current, power, power_factor, frequency) и API периодов.

  2. Образ модуля слишком старый для этой возможности. Счётчики энергии в микро-единицах, углы напряжения и стартовый ток требуют достаточно свежего образа модуля; на старом вызов сообщает «not available». Общие читатели продолжают работать.

  3. dev.is_std — False на модуле STD. Библиотека определяет линейку 16-битной транзакцией на шине; объект шины или адаптер, который её не выполняет, считается BASIC. Используйте smbus2 на CPython (проверено) и см. 04 · Оборудование.

Проводка I²C одинакова для обеих линеек модулей. Учтите, что энергия на устройстве, угол и стартовый ток проверены на CPython; путь MicroPython 16 бит пока не проверен на железе.

Сводная таблица исключений

RbAmpError (подкласс OSError) — базовый класс. Существующий обработчик except OSError: в приложении продолжает перехватывать ошибки rbAmp без изменений — стандартное соглашение Python для драйверов аппаратного ввода-вывода.

Исключение Когда Где искать
RbAmpIOError NACK после повторов; отказ фильтра достоверности; сбой на уровне шины раздел «Модуль не отвечает по I²C»
RbAmpTimeoutError wait_ready() истёк; окно commit_address_change (5 с) истекло «commit_address_change возвращает RbAmpTimeoutError» — раздел ниже
RbAmpNotReadyError (зарезервировано; библиотекой не возбуждается, экспортируется для совместимости вперёд) если вы ловите этот тип — воспроизведите и заведите issue
RbAmpStaleError снимок периода устарел раздел «Снимки периода всегда дают RbAmpStaleError»
RbAmpParamError (на CPython также ValueError) некорректный аргумент: dev=None, ch вне диапазона, code не входит в допустимый для класса набор (для SCT_013 — {1, 2, 3, 4, 5, 6, 7}), зарезервированный cls. Также нарушение предусловия: set_ct_model*() без предшествующего set_sensor_class() проверьте аргументы вызова и что был вызван set_sensor_class()
RbAmpModeError работа только в заводском режиме (заводской режим не установлен; смена адреса на v1.3 допустима в производстве); класс датчика не задан; модуль с заводской парой не допускает смены класса/модели проверьте флаг режима; сначала set_sensor_class(); для сервисного использования — set_ct_model_ch_force()
RbAmpNotSupportedError Вызов только для STD на модуле BASIC или функция STD, которой образ модуля не предоставляет раздел «RbAmpNotSupportedError» ниже
RbAmpVersionError REG_VERSION = 0/0xFF при begin() (модуль не отвечает или прошивка повреждена). Per-channel set_ct_model_ch на v1.0/v1.1 может получить NACK (опкода нет) и вызвать RbAmpIOError, а не RbAmpVersionError — проверка версии на стороне клиента НЕ реализована; перед вызовом проверьте dev.firmware_version ≥ 0x03. проверьте dev.firmware_version

У всех исключений есть осмысленное сообщение __str__ — пакет аккуратно формирует сообщения с контекстом.

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

В здоровом длительном прогоне (1-часовой long-soak harness) все они остаются нулевыми:

Счётчик Установившийся режим Сброс Доступность
dev.sanity_reject_count 0 dev.reset_counters() оба рантайма
MachineI2CBackend.retry_exhaustion_count 0 backend.reset_counters() Только MicroPython
MachineI2CBackend.retry_count_total низкий (около 5–20 в час — норма) backend.reset_counters() Только MicroPython
доля устаревших значений в снимках периода < 1 % (накопительно — без сброса) оба рантайма

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

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

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

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

  • Сравните вызовы вашего скрипта (dev.voltage и т. п.) с ожидаемой последовательностью байт — они должны совпадать точно. Чтения допускают пакетный режим (автоинкремент). Записи НЕ автоинкрементные (побайтно для многобайтных регистров).

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

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

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

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

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

  • Среда выполнения и версия: python --version / mpremote eval 'import sys; print(sys.version, sys.implementation)'.

  • Платформа хоста: "RPi 4B Bookworm", "ESP32-S3 N16R8 MicroPython 1.22" и т.д.

  • Версия пакета: rbamp --version (CPython) или python -c "import rbamp; print(rbamp.__version__)".

  • Версия прошивки модуля — dev.firmware_version из логов.

  • Минимальный скрипт (~30 строк кода), воспроизводящий проблему.
  • Трассировка исключения с полным контекстом.
  • Счётчики в момент сбоя: dev.sanity_reject_count, backend.retry_exhaustion_count (только uPy).

  • Подробные логи библиотеки — проще всего их собрать, вызвав dev.set_logger(print) перед операцией, которая падает. Пакет выведет свои внутренние шаги (цикл повторов, таймауты установки, праймер снимка и т. д.) — приложите stdout к обращению.

  • (Если есть) файл записи логического анализатора.

CLI — rbamp scan / rbamp read / rbamp address

rbamp CLI — тонкая обёртка над RbAmp.* для работы на стенде (см. 09 · API reference, раздел «CLI»). Так как он использует тот же класс RbAmp, к нему применимы ВСЕ симптомы выше. Ошибки, специфичные для CLI:

  • rbamp scan ничего не находит — то же, что в шаге 1 раздела «Модуль не отвечает по I²C» выше. Проверьте i2cdetect -y 1 напрямую. Если он находит модуль, это ошибка автоопределения нашего бэкенда; заведите issue с выводом rbamp --verbose scan.

  • rbamp падает с PermissionError: /dev/i2c-1 — пользователь не в группе i2c. См. README § Installation: sudo usermod -aG i2c $USER + повторный вход.

  • rbamp: command not found после pip install — консольная точка входа [project.scripts] не активна. Проверьте, что pip show rbamp показывает место установки; убедитесь, что $HOME/.local/bin есть в $PATH (для pip install --user).


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