10 · Устранение неполадок
Эта глава организована по наблюдаемому симптому, а не по внутренней классификации ошибок. Если вы попали сюда, значит, что-то работает не так. Найдите свой симптом в списке ниже, перейдите к соответствующему разделу и пройдите процедуру диагностики.
Большинство проблем на стенде попадает в три категории:
-
Уровень шины — модуль не отвечает по I²C; чтения выбрасывают
RbAmpIOError. -
Уровень данных — модуль отвечает, но числа неверны: нули, странные значения, неверный знак.
-
Прикладной уровень — связь нестабильна, счётчик Wh дрейфует, скрипт зависает или падает по таймауту.
Краткий путь для нетерпеливых: в установившемся режиме публичные методы должны возвращать значения / выдавать снимки без исключений. Если в логах часто RbAmpIOError или RbAmpStaleError, сразу перейдите к разделу «Модуль не отвечает по I²C» ниже.
Модуль не отвечает по I²C
Что вы видите: dev.begin() (или вход в контекстный менеджер with RbAmp(bus, 0x50) as dev:) возбуждает RbAmpIOError или RbAmpVersionError, либо чтения RT регулярно возбуждают RbAmpIOError.
Шаг 1 — Сканирование шины
Сначала убедитесь, что модуль вообще присутствует на шине.
CPython (Linux SBC)
Внешний инструмент:
i2cdetect -y 1 # bus 1 — the standard one on the RPi 40-pin header
Или 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
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:
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:
- Снизьте скорость шины до 50 кГц:
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
- Увеличьте число повторов для тяжёлой нагрузки — для этого нужен расширенный API с явным созданием бэкенда:
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
- Следите за счётчиком исчерпания повторов: в установившемся режиме он должен оставаться нулевым:
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-устройство. Исправление:
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) — это следствие; причина — в токе.
Процедура диагностики
- Проверьте, что настроены класс датчика и модель CT:
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})")
Без этих двух вызовов коэффициенты калибровки не загружаются, и ток всегда показывает ноль. Этот шаг выполняется один раз при первой установке — выбор сохраняется во флеш модуля.
- Проверьте, что модель 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».
- Проверьте ориентацию клещей. Стрелка на корпусе клещей должна указывать в направлении тока к нагрузке. Если клещи установлены «задом наперёд»,
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):
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 с). Недопустимо: подряд идущие устаревшие чтения — это значит, что прошивка не отвечает или мастер опрашивает слишком часто.
Порядок проверки периодичности
-
Проверьте частоту: 60 с между снимками — комфортно; 30 с — на грани; < 10 с гарантируют устаревшие чтения.
-
Проверьте отзывчивость модуля между снимками:
if dev.probe():
print("alive")
- Проверьте флаг напрямую:
if dev.is_period_valid():
# avg_p[] can be read
...
- Проверьте версию прошивки —
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 или аналог).
Сначала исключите очевидное
-
Калибровка датчика тока: убедитесь, что
dev.set_sensor_class()иdev.set_ct_model()вызваны с правильной моделью CT (см. 03 · Current sensor selection). Без этого RMS-ток считается с порогом по умолчанию, и значение мощности будет систематически смещено. -
Потерянные устаревшие снимки: если
dev.energy.wh(0)стабильно ниже эталона, это могут быть пропущенные интервалы. Один устаревший снимок не теряет энергию (следующий хороший покрывает весь интервал), но повторные сбои или неработающий скрипт — теряют. Проверьте частоту опроса (см. выше). -
Дрейф часов мастера:
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 используется эмпирическая проверка):
# 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 перезагрузок) |
Корреляция очевидна — исправление целостности шины полностью устраняет зависание. Логика библиотеки здесь ни при чём.
Трёхуровневое смягчение (примените все три уровня):
-
Внешняя подтяжка (~4.7 кОм) на SDA и SCL к 3.3 В в одной точке шины. Внутренние подтяжки ESP32 (~45 кОм) слабы для шины из нескольких модулей реальной длины, а встроенные в модули подтяжки 4.7 кОм, включённые параллельно, становятся слишком сильными. На такой шине перережьте встроенные на всех модулях, кроме одного. См. 04 · Подключение, раздел «Шина из нескольких модулей — основная топология».
-
Не запускайте продакшн-сборку с подключённым отладчиком NRST. В сеансе отладки линия сброса может удерживать SDA/SCL в неопределённом состоянии при отключении/подключении отладчика и вызвать зависание шины на следующей транзакции.
-
Собственный task-WDT на задаче опроса — защита в глубину. Правильные подтяжки на шине — полевое решение; task-WDT — позиция восстановления.
# 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 повторов достаточно):
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 может потеряться.
Исправление: цикл с обработкой сигналов:
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 с (по умолчанию).
Исправление: ограниченное ожидание с запасным перезапуском:
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 с сообщением:
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first
Причина: set_ct_model[_ch] требует, чтобы перед ним был вызван set_sensor_class(). Это намеренная защита.
Что делать:
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 через множественное наследование).
Возможные причины:
-
Недопустимый код модели — для класса
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). -
Недопустимый индекс канала в поканальной форме
dev.set_ct_model_ch(channel, code)— он должен быть <dev.channels. -
Значение класса датчика вне 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 — разовый захват после операции (итог именно этой операции):
dev.save_user_config()
dev_err = dev.read_reg(0x02) # IMMEDIATELY, before the next write
Шаблон 2 — постоянный мониторинг (канонический для длительной работы):
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. Шина восстанавливается сама, зависания не происходит, и ни один модуль не теряется.
Исправление — повтор на уровне приложения:
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.
Причины и что делать:
-
Модуль — BASIC. Вызовы, доступные только для STD, на BASIC недоступны. Проверьте
dev.is_std; на BASIC используйте общие чтения (voltage,current,power,power_factor,frequency) и API периодов. -
Образ модуля слишком старый для этой возможности. Счётчики энергии в микро-единицах, углы напряжения и стартовый ток требуют достаточно свежего образа модуля; на старом вызов сообщает «not available». Общие читатели продолжают работать.
-
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).
Ссылки
- 05 · Быстрый старт — ваш первый рабочий скрипт
-
09 · Справочник API — полный API и предупреждения к публичным методам с пометкой WARNING
-
03 · Выбор токового датчика — таблица моделей SCT-013, топология двойного CT для широкого динамического диапазона, способы повысить чувствительность при малых токах
Исходники и задачи: rb-amp/rbamp-python · эта страница в репозитории: docs/10_troubleshooting.md (v1.6.1)