09 · Справочник API
Полный публичный API пакета rbamp. Исходники — __init__.py (повторный экспорт), _rbamp_core.py (основной класс RbAmp), _snapshot.py (структуры POD и иерархия исключений), _energy.py (накопитель Wh), _registers.py (автогенерируемые константы).
Эта глава — справочник: сигнатуры, возвращаемые значения, побочные эффекты, граничные случаи. Рабочие примеры — в 06 · Примеры; для быстрого старта см. 05 · Быстрый старт.
Импорты
from rbamp import (
RbAmp, # main class
RbAmpEnergy, # Wh accumulator (accessed via dev.energy)
RbAmpSnapshot, # RT-block dataclass-style
RbAmpPeriodSnapshot, # period snapshot dataclass-style
RbAmpSensorClass, # sensor-class enum
TOPOLOGY_SINGLE, TOPOLOGY_SPLIT_PHASE, TOPOLOGY_THREE_PHASE,
TOPOLOGY_FIVE_CH, TOPOLOGY_SEVEN_CH,
topology_name, # helper: int → topology name
# STD module line (1.6.0)
RbAmpStdEnergy, RbAmpStdVoltage, RbAmpStdChannel,
RbAmpStdConfig, RbAmpStdHealth, # value objects
std_energy_delta, # energy between two read_std_energy() snapshots
phase_seq_name, # helper: phase-sequence code → name
PHASE_SEQ_NA, PHASE_SEQ_FORWARD, PHASE_SEQ_REVERSE, PHASE_SEQ_ABNORMAL,
# Exception hierarchy
RbAmpError, # base class of all errors
RbAmpIOError,
RbAmpTimeoutError,
RbAmpNotReadyError,
RbAmpStaleError,
RbAmpParamError,
RbAmpModeError,
RbAmpVersionError,
RbAmpNotSupportedError, # call not available on this module / firmware
# Metadata
__version__, # "1.6.0"
__protocol_version__, # 0x04 (RBAMP_PROTOCOL_VERSION)
REGISTERS, COMMANDS, # raw protocol constants (advanced use)
)
Минимальный импорт для типичного приложения:
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError
Общие идиомы
API следует стандартным шаблонам Python:
-
Один класс для всех линеек модулей: один и тот же класс
RbAmpобслуживает модули BASIC и STANDARD (STD). Линейка определяется автоматически вbegin()(см. линейку модулей STD); выбирать её вам не нужно. -
На классах: основной класс
RbAmpвладеет всем — чтения RT, период, конфигурация, диагностика. Дескриптор внутри хранит бэкенд и накопитель энергии. -
Контекстный менеджер:
with RbAmp(bus, addr) as dev:— рекомендуемая идиома.__enter__автоматически вызываетdev.begin(). -
Свойства для показаний RT:
dev.voltage,dev.frequency— одно свойство = одна транзакция I²C. Индексируемые по каналу идут через_ChannelProxy:dev.current[ch],dev.power[ch],dev.power_factor[ch]. -
Методы для чтения по каналу:
dev.read_current(ch),dev.read_power(ch). Полностью эквивалентны форме со свойствами — используйте удобную. -
Исключения для ошибок: каждая ошибка — подкласс
RbAmpError. Стандартный шаблон Pythontry / except(а неlast_error()+ код возврата). -
Асинхронный генератор для периодической потоковой передачи:
async for snap in dev.stream_period(interval_s=...).
Типы
RbAmp
class RbAmp:
def __init__(self, bus, addr: int = 0x50): ...
Основной класс. Один экземпляр на каждое ведомое устройство. Шина — любой объект с одной из «известных» сигнатур API: smbus2.SMBus, machine.I2C или пользовательский бэкенд (см. 04 · Оборудование).
Бэкенд выбирается автоматически при первом обращении к шине:
| метод объекта шины | Бэкенд |
|---|---|
bus.readfrom_mem, bus.writeto_mem |
MachineI2CBackend (MicroPython) |
bus.read_byte_data, bus.write_byte_data |
SMBusBackend (CPython + smbus2) |
bus.read_byte, bus.register_acks, bus.now_ms |
уже обёрнутый (тестовые моки, адаптеры FTDI) |
Если ни одна сигнатура не подходит, выбрасывается RbAmpParamError с описанием.
Иерархия исключений
Каждая ошибка пакета — подкласс RbAmpError, который сам наследует OSError (а не голый Exception). Это значит: существующий код с обработчиками except OSError: продолжает ловить ошибки rbAmp без переписывания — стандартное соглашение Python для драйверов аппаратного ввода-вывода.
: RbAmpParamError наследует RbAmpError и ValueError на CPython (множественное наследование). На MicroPython, где множественное наследование поддерживают не все порты, используется одиночное. С точки зрения пользователя try / except RbAmpParamError работает одинаково. Но try / except ValueError перехватывает только на CPython — на MicroPython этот обработчик пропускает ошибку. Код, который рассчитывает на кроссплатформенное поведение, должен явно перехватывать RbAmpParamError.
Стандартное использование:
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
# period not ready yet — the master timestamp was committed by the package
continue
except RbAmpIOError as e:
log.warning("bus failure: %s", e)
except RbAmpError as e:
log.error("unexpected: %s", e)
RbAmpSensorClass
class RbAmpSensorClass(IntEnum):
UNSET = 0 # factory value after reset
SCT_013 = 1 # SCT-013 series (shipping default)
WIRED_CT = 2 # factory-fitted wired CT (module ships paired)
BUILTIN_CT = 3 # factory-fitted built-in CT (module ships paired)
: на CPython используется IntEnum из стандартной библиотеки enum. На портах MicroPython без модуля enum используется запасной обычный класс с теми же значениями членов. С точки зрения пользователя обе формы идентичны: dev.set_sensor_class(RbAmpSensorClass.SCT_013) или dev.set_sensor_class(1) — работают оба.
SCT_013 — класс, который выбирается для модуля с установленными пользователем токовыми клещами SCT-013. WIRED_CT и BUILTIN_CT описывают модули, поставляемые с заводской парой датчика: set_sensor_class() и set_ct_model*() отказываются менять такой модуль (RbAmpModeError, см. защиту «сначала чтение, потом запись»). Значения вне 0..3 выбрасывают RbAmpParamError.
RbAmpSnapshot
Возвращается dev.read_all(). Обычный класс Python (не @dataclass, для совместимости с MicroPython). Все поля в единицах СИ.
class RbAmpSnapshot:
voltage: float # V — RMS voltage
voltage_peak: float # V — peak voltage
current: list # [ch0, ch1, ...] — RMS current per channel, A
current_peak: list # [ch0, ch1, ...] — peak current, A
power: list # [ch0, ch1, ...] — active power (signed), W
power_factor: list # [ch0, ch1, ...] — dimensionless, −1..+1
frequency: float # Hz
topology: int # TOPOLOGY_* constant
channels: int # number of valid channels (1..3, or 5 / 7 on UI5 / UI7)
has_voltage_hw: bool # True if a voltage sensor is present
Неиспользуемые каналы (сверх channels) заполняются нулями.
RbAmpPeriodSnapshot
Возвращается dev.read_period_snapshot(). Примитив учёта энергии.
class RbAmpPeriodSnapshot:
avg_p: list # [ch0, ch1, ...] — average P over the period, W (all channels)
max_p: float # peak instantaneous power on channel 0
latch_ms: int # period duration (device's view)
master_dt_ms: int # master wall-clock dt since the last snapshot
valid: bool # True if the snapshot-ready flag was set
avg_p_total: float # STD: total average P over the period, W (0.0 on BASIC)
wh_net: float # STD: net energy over the period, Wh (0.0 on BASIC)
module_restarted: bool # STD counter source: the module restarted during the period
Для интегрирования энергии используйте master_dt_ms, а не latch_ms — latch_ms — это диагностический таймер модуля.
Константы топологии
TOPOLOGY_SINGLE = 1 # 1 current channel (UI1 / I1)
TOPOLOGY_SPLIT_PHASE = 2 # 2 current channels (UI2 / I2)
TOPOLOGY_THREE_PHASE = 3 # 3 current channels (UI3 / I3)
TOPOLOGY_FIVE_CH = 5 # 5 current channels + voltage (UI5)
TOPOLOGY_SEVEN_CH = 7 # 7 current channels + voltage (UI7)
topology_name(topology: int) -> str # 1 → "SINGLE", 2 → "SPLIT_PHASE", ...
Жизненный цикл
RbAmp(bus, addr=0x50)
Конструктор. Выбор бэкенда происходит в __init__. Никакого трафика I²C до begin().
| Параметр | Описание |
|---|---|
bus |
Объект шины I²C (smbus2.SMBus, machine.I2C или обёртка) |
addr |
7-битный адрес ведомого. Диапазон 0x08..0x77, по умолчанию 0x50 |
Возбуждается: RbAmpParamError, если объект шины не распознан или addr вне диапазона.
dev.begin()
02 · Инициализация и запуск (initialization) · BASIC или STD? (initialization) · Непрерывный цикл опроса (рекомендуется) (period-metering)
Опрашивает устройство, определяет линейку модуля, кэширует топологию и подготавливает команду прайм-снимка.
Определение линейки модуля (1.6.0). begin() сначала проверяет, является ли модуль модулем STD (16-битная карта регистров). Если да, дескриптор переключается в режим STD (dev.is_std становится True, dev.channels и dev.has_voltage_hw берутся из модуля), и begin() возвращает управление. Если нет, выполняется последовательность BASIC ниже. Для этого нужен бэкенд шины, способный на 16-битные транзакции; иначе модуль считается BASIC.
Последовательность для BASIC:
-
Читает
REG_VERSION— выбрасываетRbAmpIOErrorпри NACK,RbAmpVersionError, если возвращается0x00или0xFF. -
Кеширует топологию (на текущей прошивке
begin()не выполняет автоопределения; использует подсказку из конструктора). -
Читает
U_rms, чтобы определить, есть ли датчик напряжения (порог 1.0 В). -
Пишет
CMD_LATCH_PERIOD(прайм) и ждёт 50 мс. Первый снимок после включения отбрасывается. -
Сохраняет
time.monotonic()(илиtime.ticks_ms()на uPy) для последующего интегрирования энергии.
На модуле BASIC с клещами SCT-013 begin() также оценивает коррекцию по номиналу SCT-013.
Идемпотентно: безопасно вызывать повторно.
Контекстный менеджер
with RbAmp(bus, 0x50) as dev:
# dev.begin() has already been called in __enter__
...
# __exit__ — no-op (bus closing is the caller's responsibility)
Рекомендуемая идиома. __exit__ пакета НЕ закрывает шину — управление объектом шины остаётся за вызывающим кодом (типичный шаблон — вложенный with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:).
dev.probe() -> bool
Лёгкая проверка живости. Одно чтение REG_VERSION без побочных эффектов.
Возвращает: True, если ведомый ответил ACK и сообщил поддерживаемую версию; иначе False. Не возбуждает исключений — для сценариев опроса.
dev.wait_ready(timeout_ms=1000) -> None
02 · Инициализация и запуск (initialization) · 3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · 4 · Карта регистров (production v1.3) (api-reference)
Опрашивает флаг готовности модуля, пока он не установлен. Полезно после включения питания — модулю может понадобиться до 100 мс на первое окно RT.
Возбуждается: RbAmpTimeoutError, если бит не виден до истечения timeout_ms.
Свойства — состояние дескриптора
BASIC или STD? (initialization) · Ток по нескольким каналам (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
dev.firmware_version: int # REG_VERSION — opaque byte
dev.topology: int # TOPOLOGY_* constant
dev.topology_name: str # "SINGLE" / "SPLIT_PHASE" / "THREE_PHASE"
dev.channels: int # 1..3 (BASIC), 5 / 7 on UI5 / UI7, or the STD module's channel count
dev.is_std: bool # True if begin() detected an STD module
dev.has_voltage_hw: bool # True if begin() detected U_rms > 1.0
dev.address: int # 7-bit I²C address (updated after commit_address_change)
firmware_version — живое свойство: каждое чтение обращается к шине (одно однобайтовое чтение REG_VERSION). Если вы опрашиваете его в горячем цикле, кешируйте на стороне приложения: fw = dev.firmware_version один раз после begin(). Если begin() ещё не вызывался, firmware_version выбрасывает RbAmpIOError (модуль может отвечать NACK, пока дескриптор «холодный»).
Остальные свойства (topology, channels, has_voltage_hw, address) кешируются в дескрипторе и возвращают значения, сохранённые после begin(), без обращения к шине.
Показания в реальном времени (блок RT, обновление 100 мс)
Все методы выбрасывают RbAmpIOError при сбое связи (NACK после повторов или отказ фильтра достоверности) или RbAmpParamError при недопустимом аргументе.
Свойства
Многоканальный ток (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Окно доступа к каналам (0x32 + 0x3C..0x3F) (api-reference)
dev.voltage -> float # V — RMS voltage
dev.voltage_peak -> float # V — peak voltage
dev.frequency -> float # Hz — mains frequency
Индексация по каналам через _ChannelProxy — поддерживает индексацию [ch] и итерацию:
dev.current # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak # _ChannelProxy
dev.power # _ChannelProxy
dev.power_factor # _ChannelProxy
Usage:
i0 = dev.current[0] # a single channel
for i in dev.current: # iterate over all valid channels
print(i)
total = sum(p for p in dev.power) # sum of all channels
len(dev.current) равно dev.channels.
Методы (полностью эквивалентны форме со свойствами)
Справочник регистров RT (realtime-polling) · Двунаправленный учёт (period-metering)
dev.read_voltage(phase=0) -> float
dev.read_voltage_peak(phase=0) -> float
dev.read_current(ch=0) -> float
dev.read_current_peak(ch=0) -> float
dev.read_power(ch=0) -> float # signed
dev.read_power_factor(ch=0) -> float
dev.read_frequency() -> float
Однократное чтение всего блока RT
Справочник регистров RT (realtime-polling) · Опрос — один модуль (realtime-polling) · 4.10 Блок реального времени V03 (0x86..0xBD) (api-reference)
dev.read_all() -> RbAmpSnapshot
Эквивалентно последовательным read_voltage + read_voltage_peak + read_current(0..N) + read_current_peak(0..N) + read_power(0..N) + read_power_factor(0..N) + read_frequency. Неиспользуемые каналы (сверх channels) заполняются нулями.
Возбуждается: RbAmpIOError, если какое-либо вложенное чтение не удалось.
Общие чтения — voltage, voltage_peak, current, current_peak, power, power_factor, frequency и их формы read_* — работают на всех линейках модулей. На модуле STD phase в read_voltage() / read_voltage_peak() выбирает вход напряжения (0..n_voltage-1); на модуле BASIC допустимо только phase=0.
Линейка STD-модулей (1.6.0)
⚠️ Статус проверки. Учёт энергии на устройстве, угол напряжения и пусковой ток проверены на CPython (smbus2). Те же вызовы реализованы для MicroPython (machine.I2C), но путь MicroPython для 16-битных регистров ещё не проверен на оборудовании — для этих функций на устройстве предпочтителен CPython, пока заметка о выпуске не скажет иное. Обычные показания (dev.voltage, dev.current[ch], dev.power[ch], снимки периодов) работают на любом поддерживаемом хосте.
Один класс RbAmp обслуживает обе линейки модулей. begin() определяет линейку автоматически; dev.is_std равно True на модуле STD. Используются та же проводка I²C и тот же адрес (см. 04 · Оборудование).
-
Общие читатели (
voltage,current,power,power_factor,frequency) работают на любом модуле. -
Вызовы в этом разделе — только для STD. На модуле BASIC они выбрасывают
RbAmpNotSupportedError. -
Некоторым вызовам STD также нужен достаточно новый образ модуля (энергия на устройстве, микроединичные счётчики, углы напряжений, пусковой ток). Если модуль их не предоставляет, вызов выбрасывает
RbAmpNotSupportedError(«not available»). -
Вызовы периода (
latch_period,read_period_*,stream_period) и накопительdev.energyработают на модуле STD — см. «Period accounting» ниже. Собственные пожизненные итоги модуля —read_std_energy(). -
Вызовы конфигурации датчика (
set_sensor_class,set_ct_model,set_ct_model_ch,set_ct_model_ch_force,read_ct_model_ch,read_sensor_class),reset,factory_reset, пара смены адреса, регистры идентификации (firmware_version,read_variant,read_capability,read_product_id,read_uid,read_label,set_label,read_seq_digest), канал ошибок и событий (read_last_error,read_event_flags,clear_event_flags,has_error,clear_error), помощники флота (read_fleet_config,enable_gc,set_group_id,read_group_id,read_gc_tick),read_period_latch_msиwait_ready— только для BASIC: на модуле STD они возбуждаютRbAmpNotSupportedError, ничего не отправляя на шину.
dev.is_std -> bool # True on an STD module (set by begin())
dev.std -> object # internal STD client (advanced use) or None on BASIC
Чтения
dev.read_std_voltage(phase=0) -> RbAmpStdVoltage # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0) -> (float, bool) # (degrees, valid)
dev.read_phase_sequence() -> int # 0..3
dev.read_std_channel(ch=0) -> RbAmpStdChannel # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0) -> RbAmpStdChannel # totals block k (0 = grand total)
dev.read_reactive(ch=0) -> float # var
dev.read_apparent(ch=0) -> float # VA
dev.read_std_config() -> RbAmpStdConfig
dev.read_std_health() -> RbAmpStdHealth
-
read_voltage_angle(phase)— фазовый угол напряжения относительно фазы 0, возвращается как(degrees, valid).validравноFalseна модуле с одним напряжением или на образе модуля, который углы не сообщает. -
read_phase_sequence()— код порядка фаз:PHASE_SEQ_NA(0, недоступно),PHASE_SEQ_FORWARD(1),PHASE_SEQ_REVERSE(2),PHASE_SEQ_ABNORMAL(3).phase_seq_name(code)возвращает текстовое название. ВыбрасываетRbAmpNotSupportedErrorна модуле BASIC или на образе модуля, который его не сообщает. -
read_reactive(ch)/read_apparent(ch)— реактивная мощность в var и полная мощность в VA для одного канала. Только для модулей STD; на BASIC возбуждаютRbAmpNotSupportedError(на BASIC реактивная мощность этой библиотекой не выводится). -
read_std_totals(k)— блок итоговk;k=0— общий итог. Итоги по фазам зависят от версии карты регистров модуля. -
read_std_config()/read_std_health()— блоки конфигурации и состояния/здоровья.
Объекты-значения
Обычные классы (не @dataclass), все экспортируются из rbamp.
| Класс | Поля |
|---|---|
RbAmpStdVoltage |
u_rms, u_peak, thd_u, angle_deg, angle_valid |
RbAmpStdChannel |
i_rms, i_peak, p, q, s, pf, thd_i, pf1, q1 |
RbAmpStdConfig |
sensor_class, ct_model, tier, i2c_addr, rate_ms, harmonics, start_ua, start_ua_supported |
RbAmpStdHealth |
status, cal_ok, sensor_ok, mains_ok, time_valid, nvm_fault, maint, frame_count, crc_errors, lta_status, lta_src, cal_src, group_status, ring_drop, lost_frames, uptime_s, reset_cause, boot_count |
RbAmpStdEnergy |
см. ниже |
dev.read_std_energy() -> RbAmpStdEnergy
Снимок пожизненной энергии на устройстве. Требует модуль, предоставляющий энергию на устройстве; иначе RbAmpNotSupportedError.
RbAmpStdEnergy содержит:
| Группа | Поля |
|---|---|
| Активная, Wh | act_import_wh, act_export_wh, act_net_wh |
| Активная, mWh | act_import_mwh, act_export_mwh, act_net_mwh |
| Активная, µWh | act_import_uwh, act_export_uwh, act_net_uwh |
| Реактивная | rea_import_varh, rea_export_varh; µvarh: rea_import_uvarh, rea_export_uvarh |
| По каналам | channels (число валидных записей); ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[] |
| Учёт | generation, uptime_s, group_status |
| Флаги происхождения | fine, fine_reactive |
Поля µWh / µvarh всегда заполнены. Если образ модуля не предоставляет более мелкие счётчики, они масштабируются из более крупных, а fine (активный) / fine_reactive равны False — читайте флаг, если нужно знать, откуда значение.
RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)
Энергия, потреблённая между двумя снимками read_std_energy() (статический метод; экспортируется также как std_energy_delta). Устойчива к отключению питания.
module_restartedравноTrue, когдаnow.uptime_s < prev.uptime_s.-
delta—RbAmpStdEnergy, содержащий прирост по каждому полю, илиNone, когда счётчикgenerationизменился (два показания не сравнимы). -
Счётчик, который возвращается чуть ниже предыдущего показания (возобновление после отключения питания), обрезается до 0;
netвсегда равен импорту минус экспорт обрезанных частей. -
Поканальные записи заполняются, только если оба снимка содержат одинаковое число каналов.
prev = dev.read_std_energy()
time.sleep(60)
now = dev.read_std_energy()
delta, restarted = RbAmp.std_energy_delta(prev, now)
if delta is not None:
print(delta.act_import_wh, "Wh imported in this interval")
Пусковой ток и конфигурация
dev.get_start_current() -> int # µA, 0 = off
dev.set_start_current(ua) -> None
dev.save_config() -> None # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch) -> None # set the module's clock
-
get_start_current()— энергетический пусковой ток в µА (0= выключен). -
set_start_current(ua)— ниже этого тока на канале модуль не учитывает энергию в импорт/экспорт; живые показания (I, P, Q) не затрагиваются. Значение применяется сразу; вызовитеsave_config(), чтобы сохранить его после перезапуска. Недопустимое значение возбуждаетRbAmpParamErrorдо записи на шину. Значение должно быть0(выключено) или кратным 10 µA в поддерживаемом диапазоне. -
save_config()— сохраняет записываемую конфигурацию STD. Блокирующий вызов. -
set_time(unix_epoch)— задаёт часы модуля по Unix-эпохе; эпоха раньше 2020 возбуждаетRbAmpParamError. Задавайте время снова после перезапуска модуля (read_std_health().time_validравноFalse, пока часы не заданы). -
get_start_current()/set_start_current()возбуждаютRbAmpNotSupportedErrorна образе модуля, который не предоставляет настройку стартового тока;RbAmpStdConfig.start_ua_supportedпоказывает, предоставляет ли он её.
Банки latch
Модуль STD, который сообщает latch-банки, хранит 8 независимых банков. Банк накапливает, пока его бит установлен в маске взведения; latch снимает значение и сбрасывает банк на следующей границе окна измерения, поэтому период — это интервал между двумя latch одного банка, измеренный по часам мастера. Эти вызовы требуют модуля, сообщающего банки, и иначе возбуждают RbAmpNotSupportedError; номер банка вне 0..7 возбуждает RbAmpParamError.
dev.std_arm_banks(mask) -> None # bit i = bank i accumulates
dev.std_latch(bank) -> None # snapshot + reset; does not wait
dev.std_read_latch(bank) -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
-
std_arm_banks(mask)— задаёт маску взведения. Маска не сохраняется при перезапуске модуля. -
std_latch(bank)— фиксирует один банк. Читайте его не раньше чем через 300 мс. -
std_read_latch(bank)— возвращает снимок банка. Флаг valid модуля говорит лишь о том, что банк был зафиксирован хотя бы раз; это не флаг свежести, поэтому ждите минимум одно окно (безопасная граница — 300 мс) послеstd_latch(). Банк, который ни разу не фиксировался, выбрасываетRbAmpStaleError. Пустой банк, который больше не взведён (модуль перезагрузился), взводится заново и фиксируется один раз для начала нового периода, а вызов выбрасываетRbAmpStaleError: отбросьте этот период и перезапустите собственный отсчёт времени. -
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF)— переводит энергию снимка в Wh заdt_msпо часам мастера.ch— индекс канала, или0xFF(по умолчанию) для общего итога модуля. Возвращает(wh_import, wh_export); экспорт нулевой или отрицательный. ВозбуждаетRbAmpStaleErrorдля снимка без выборок.
class RbAmpStdLatch:
bank: int # 0..7
valid: bool # the bank has been latched at least once
channels: int
p_avg, q_avg, s_avg: float # average P (W), Q (var), S (VA) over the period
max_p, max_i, max_u, min_u: float # peak P (W), peak I (A), peak / minimum U (V)
e_import_mws, e_export_mws: int # energy, mW·samples (export <= 0)
nsamp: int # samples in the period
win_count: int # measurement windows in the period (0 = not armed / nothing elapsed)
p_avg_ch: list # per-channel average P, W
e_import_ch_mws, e_export_ch_mws: list # per-channel energy, mW·samples
Учёт периода
Общая картина — в 01 · Overview, минимальный шаблон — в 05 · Quickstart, шаг 5.
На модуле STD те же вызовы работают. begin() выбирает источник периода по тому, что сообщает модуль:
| Модуль сообщает | Источник периода | Команда latch |
|---|---|---|
| счётчики энергии на устройстве | разность двух показаний счётчика по расписанию мастера | нет |
| только latch-банки | latch-к-latch на банке 0 (не менее 300 мс установления) | CMD_LATCH_PERIOD на банке 0 |
| ни один | — | вызовы периодов выбрасывают RbAmpNotSupportedError |
На источнике-счётчике первый период начинается с begin(); latch_period() ничего не делает; is_period_valid() равно True, когда счётчики привязаны; read_period_max_power() выбрасывает RbAmpNotSupportedError (пика нет); read_period_avg_power(ch) существует только на одноканальном модуле и только после чтения одного периода. Смена поколения счётчиков заново привязывает период и выбрасывает RbAmpStaleError; перезапуск модуля внутри периода отражается в snap.module_restarted (энергия во время перезапуска не учитывается). На источнике-latch пустой снимок выбрасывает RbAmpStaleError; если банк потерял взведение (перезапуск модуля), его сначала взводят заново. Снимок содержит avg_p_total, wh_net и module_restarted. read_period_latch_ms() — только для BASIC.
dev.latch_period() -> None
Записывает CMD_LATCH_PERIOD. Не ждёт — вызывающий должен выдержать 50 мс установления и проверить dev.is_period_valid() перед чтением.
Для большинства задач используйте read_period_snapshot() — он инкапсулирует всю последовательность.
dev.is_period_valid() -> bool
04 · Учёт по периодам и тарифный учёт (period-metering) · Калибровка и точность (troubleshooting)
Читает бит готовности снимка. Возвращает True, если последний снимок свежий.
dev.read_period_avg_power(ch=0) -> float
Регистры снимка периода (period-metering) · 4.11 Блок периода V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + период ch0 (0xD0..0xE3, производственная сборка) (api-reference)
Средняя активная мощность на канале за закрытый период. Вызывать после latch_period() + 50 мс установления + проверки валидности.
Обрабатывает каждый канал модуля (ch = 0..channels-1), включая каналы 3+ на 5- и 7-канальных модулях (UI5 / UI7). Снимок периода и накопитель Wh тоже охватывают все каналы. dev.read_period_avg_p(ch) — синоним с тем же поведением.
dev.read_period_max_power() -> float
Регистры снимка периода (period-metering) · 4.12 V03 Q + период ch0 (0xD0..0xE3, производственная сборка) (api-reference)
Пиковая мгновенная мощность на канале 0 за закрытый период. ch=0 только на прошивке v1.
dev.read_period_latch_ms() -> int
13. Дрейф часов нескольких модулей в долгих тестах (troubleshooting) · 4.13 Диагностический dt на стороне микросхемы (0xEC) (api-reference)
Длительность периода с точки зрения устройства, в мс.
Внутренний таймер модуля точен ограниченно. Для интегрирования энергии используйте master_dt_ms из RbAmpPeriodSnapshot, а не это поле.
dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot
Непрерывный цикл опроса (рекомендуется) (period-metering) · Калибровка и точность (troubleshooting) · 4.11 V03 period block (0xBE..0xCF) (api-reference)
Рекомендуемая точка входа для учёта по периодам. Полная последовательность внутри:
-
Если
skip_latch=True— пропустить запись команды снимка (для шаблона из нескольких модулей после ручной серии команд снимка). -
Иначе — запишите
CMD_LATCH_PERIOD. - Запомните
time.monotonic(), чтобы вычислитьmaster_dt_ms. time.sleep(settle_ms / 1000)— по умолчанию 50 мс.-
Проверьте флаг готовности снимка. Если 0 — возбудите
RbAmpStaleError(предыдущая метка времени сохраняется, поэтому следующий успешный снимок покроет весь интервал и Wh останется точным). -
Прочитайте
avg_p[0..channels-1]+max_p+latch_ms. - Обновите метку времени и вызовите
energy.tick(snap), чтобы проинтегрировать Wh (если накопитель не отключён черезenergy.disable()).
| Параметр | Описание |
|---|---|
settle_ms |
Пауза после команды снимка, в мс. По умолчанию 50. |
skip_latch |
Если True — не отправлять команду снимка, только читать. |
Возбуждается: RbAmpStaleError (снимок устарел); RbAmpIOError (сбой шины).
async dev.stream_period(interval_s=60.0, skip_stale=True)
Асинхронный генератор, который выдаёт RbAmpPeriodSnapshot с интервалом interval_s. Работает на CPython asyncio и MicroPython uasyncio (MicroPython ≥ 1.20 — import asyncio тоже работает; для более ранних версий используйте import uasyncio as asyncio).
async for snap in dev.stream_period(interval_s=60.0):
# snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
print(snap.avg_p[0])
| Параметр | Описание |
|---|---|
interval_s |
Период между снимками (рекомендуется ≥ 30 с) |
skip_stale |
True (по умолчанию) — устаревшие снимки пропускаются автоматически. False — они выдаются с snap.valid=False, и ваш код должен сам проверить if not snap.valid: continue |
⚠ CPython: блокирует цикл событий. Внутри stream_period() вызывает синхронный, блокирующий read_period_snapshot() — с time.sleep(0.05) установления и ~50–100 мс однобайтовых чтений по шине. На CPython это блокирует весь цикл событий asyncio на эти 100 мс — другие корутины (MQTT, HTTP, keepalive Wi-Fi) не получают процессора. Для продуктивных серверов оберните вызов в run_in_executor:
import asyncio
async def stream_period_nonblocking(dev, interval_s=60.0):
loop = asyncio.get_event_loop()
while True:
await asyncio.sleep(interval_s)
snap = await loop.run_in_executor(None, dev.read_period_snapshot)
if snap.valid:
yield snap
На MicroPython проблема меньше — планировщик uasyncio передаёт управление другим задачам реже, а блокирующий I²C в асинхронных шаблонах встраиваемых систем считается приемлемым. Если нужно неблокирующее поведение, используйте отдельный поток через _thread.start_new_thread (на ESP32 µPy).
Учёт энергии (накопитель на стороне мастера)
dev.energy — экземпляр RbAmpEnergy
Алгоритм на стороне мастера (period-metering) · 7 · Семантика (api-reference)
Накопитель Wh по каналам. Доступен через свойство — объект принадлежит пакету:
dev.energy.wh(ch=0) -> float # current Wh total for the channel
dev.energy.reset(ch=0) -> None # zero a single channel
dev.energy.reset_all() -> None # zero all channels
dev.energy.is_enabled -> bool # True while auto-integration is active (default)
dev.energy.disable() -> None # turn off auto-integration
dev.energy.enable() -> None # turn it back on
Накопитель обновляется автоматически при каждом успешном dev.read_period_snapshot(). Он знаковый — отрицательное значение означает чистый экспорт.
Формула интегрирования:
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
dev.energy.disable() полезен в сценариях глубокого сна, когда сам мастер ведёт сохранение Wh в RTC-памяти — см. 06 · Примеры, сценарий 9.
Настройка датчика
Двухшаговая последовательность. Подробный гид по выбору модели — в 03 · Выбор токового датчика.
dev.set_sensor_class(cls) -> None
Настройка класса датчика и модели ТТ (initialization) · 4.3 Система (0x20..0x25) (api-reference) · 6.2 Привязка модели ТТ — чистая подготовка + поканальная команда CMD (api-reference)
Задаёт класс датчика тока и сохраняет его во flash. Блокирует, ~705 ms.
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
| Параметр | Описание |
|---|---|
cls |
Enum RbAmpSensorClass или int 0..3 |
Raises:
RbAmpParamError—clsвне диапазона 0..3-
RbAmpModeError— модуль с заводской парой (текущий классWIRED_CT/BUILTIN_CT), аclsотличается; смена сотрёт калибровку встроенного датчика -
RbAmpIOError— сбой связи
Вызывать до set_ct_model*(). Запись того же класса, который уже хранит модуль, — no-op (без записи на шину), потому что запись класса стирает модели CT по каналам на стороне устройства. См. read-before-write guard.
dev.read_sensor_class() -> int
Читает закреплённый класс датчика: 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (значения RbAmpSensorClass). Возвращает 0 на прошивке, где такого регистра нет.
dev.set_ct_model(code) -> None
Однопараметрическая (устаревшая) форма — задаёт модель токовых клещей только на канале 0.
code |
Модель |
|---|---|
| 1 | SCT-013-005 |
| 2 | SCT-013-010 |
| 3 | SCT-013-030 |
| 4 | SCT-013-050 |
| 5 | SCT-013-100 |
| 6 | SCT-013-020 |
| 7 | SCT-013-060 |
Принимаемый набор для класса SCT_013 — {1, 2, 3, 4, 5, 6, 7}. Полная таблица допустимых наборов по классам — в 03 · Выбор токового датчика.
Raises:
ValueError(а такжеRbAmpParamError) —codeне входит в допустимый для класса набор при текущемREG_SENSOR_CLASS(дляSCT_013это{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— еслиset_sensor_class()не вызывался или модуль имеет заводскую пару (класс 2/3) и код отличается (в сервисном контексте используйтеset_ct_model_ch_force()) -
RbAmpIOError— сбой связи
Установка модели, которую канал уже хранит, — no-op (read-before-write guard).
Сообщение RbAmpModeError (класс не задан):
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first
Эквивалентно dev.set_ct_model_ch(0, code).
dev.set_ct_model_ch(channel, code) -> None
Настройка класса датчика и модели CT (initialization) · 6.2 Привязка модели CT — чистый staging + CMD по каналам (api-reference)
Поканальная форма. Задаёт модель токовых клещей для конкретного канала.
Внутри: записать REG_CT_MODEL (0x05) → команда CMD_SET_CT_MODEL_CH0/1/2 (опкоды 0x28/0x29/0x2A) → 5 мс установления → CMD_SAVE_USER_CONFIG (0x32) → 700 мс. Блокирует, ~705 ms.
✅ v1.3: порядок привязки каналов не важен. На v1.3 запись REG_CT_MODEL (0x05) ставит значение в очередь, но больше не применяет его автоматически к ch0. Применение происходит только через CMD_SET_CT_MODEL_CHn. Каналы можно настраивать в любом порядке.
dev.set_ct_model_ch(0, 1) # any order is OK on v1.3
dev.set_ct_model_ch(1, 3)
dev.set_ct_model_ch(2, 6)
Raises:
RbAmpParamError—channelвне 0..dev.channels-1илиcodeне входит в допустимый для класса набор (дляSCT_013—{1, 2, 3, 4, 5, 6, 7})RbAmpModeError— не вызванset_sensor_class(), либо модуль с заводской парой и код отличается
dev.set_ct_model_ch_force(channel, code) -> None
Сервисный вариант set_ct_model_ch(), который обходит защиту «сначала чтение, потом запись»: он пишет даже тогда, когда модуль с заводской парой или уже содержит этот код. Предназначен для техников, перенастраивающих датчик. Модуль по-прежнему проверяет пару (класс, код), и при неверной паре вызов выбрасывает RbAmpParamError.
Защита «сначала чтение, потом запись»
Запись модели CT заменяет калибровку канала общим пресетом для модели, поэтому начиная с 1.6.0 сеттеры сначала проверяют:
| Вызов | Модуль уже хранит это значение | Заводски спаренный модуль (класс 2/3) | Иначе |
|---|---|---|---|
set_sensor_class(cls) |
нет операции, без записи на шину | RbAmpModeError, если cls отличается |
записи + сохранение |
set_ct_model(code) / set_ct_model_ch(ch, code) |
нет операции, без записи на шину | RbAmpModeError, если код отличается |
записи + сохранение |
set_ct_model_ch_force(ch, code) |
записи | записи | записи |
Зеркала верификации V2 — CT_MODEL_CH0/1/2 (0x51-0x53)
Регистры только для чтения, отражающие пресет CT, фактически применённый на каждом канале. Протокол записи по проводу не меняется — записи используют механизм, описанный выше. 0x51–0x53 служат только для обратного чтения при проверке состояния и в шаблонах «прочитать — сравнить — записать»:
applied_ch0 = dev.read_ct_model_ch(0) # what is actually applied
applied_ch1 = dev.read_ct_model_ch(1)
applied_ch2 = dev.read_ct_model_ch(2)
Коррекция по номиналу SCT-013 при переключении модели
Модули SCT-013 калибруются на заводе с одной эталонной моделью клещей. Когда канал переключают на другую модель, образ модуля, который сам не пересчитывает масштаб, продолжает применять эталонное усиление, и ток с мощностью читались бы в неверном масштабе. Начиная с 1.6.0 библиотека исправляет это автоматически на модулях BASIC с классом датчика SCT_013:
-
Ток, мощность и энергия, выведенная из мощности (
read_current,read_current_peak,read_power,read_period_avg_power, а значит и снимок периода иdev.energy) пересчитываются к выбранной модели относительно усиления, которое модуль реально применяет. -
Напряжение и коэффициент мощности никогда не меняются.
- На прошивке модуля до 1.4.19 смена модели перезапускает модуль один раз (около секунды); с 1.4.20 модуль корректирует себя сам. Коррекция SCT масштабирует ток, мощность и энергию, но никогда не напряжение и коэффициент мощности.
-
Модули, чья прошивка делает это сама, распознаются и не трогаются (scale 1).
-
Заводски спаренные модули (класс 2/3) никогда не масштабируются.
- Коррекция вычисляется в
begin()и снова после перезапуска, который запускает библиотека (reset()), или после обнаруженного перезапуска. В одной ситуации (модель записана в текущем цикле питания) библиотека может выполнить один сброс модуля, чтобы прочитать сохранённое усиление.
dev.set_rating_correction(enabled: bool) -> None # default enabled
dev.rating_correction_enabled -> bool
dev.ct_rating_scale(ch=0) -> float # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0) -> (action, detail) | None
dev.refresh_rating_correction() -> None
-
set_rating_correction(enabled)— выключает коррекцию, чтобы читать сырые, некорректированные значения (или на модуле, прошивка которого уже корректирует). Пересчитывает немедленно. -
ct_rating_scale(ch)— масштаб, применяемый к току, мощности и энергии на канале;1.0, когда коррекция не активна. -
ct_rating_status(ch)—(action, detail)последней оценки для канала илиNone, если канал не оценивался (например, не канал SCT).action— одно из"unity","ok","needs_reset","warn_uncal","warn_gain";detail— текст. Действияwarn_*означают, что библиотека не смогла определить безопасный масштаб и оставила показание без коррекции. -
refresh_rating_correction()— пересчитать после перезапуска, который библиотека не выполняла сама (например, модель сохранена, а модуль сброшен извне).
Это особенность пути SCT-013 во всех библиотеках rbAmp, а не только в Python.
dev.save_gains() -> None
Голая запись CMD_SAVE_GAINS (0x26) — только для завода.
⛔ ЗАБЛОКИРОВАНО в продакшн-прошивке (v1.3 возвращает DEV_ERR_PARAM; устройство отклоняет запись, а последующая перезагрузка откатывает любое изменение в RAM). CMD_SAVE_GAINS зарезервирован для режима заводской подготовки и сохраняет только коэффициенты усиления, NF и фазы. Для пользовательского сохранения sensor_class / ct_model по каналам, адреса и метки используйте dev.save_user_config() (или поканальные вызовы set_ct_model_ch() / set_sensor_class(), которые уже внутри выполняют CMD_SAVE_USER_CONFIG (0x32)).
Возбуждается: RbAmpModeError, если модуль не в режиме заводского провизионирования; RbAmpIOError при сбое связи.
dev.prepare_address_change(new_addr) -> None
Смена адреса (initialization) · 4.5 Адрес (0x30..0x31) (api-reference) · 6.1 Смена адреса — двухфазная фиксация (допустимо в production) (api-reference)
Шаг 1 из 2 смены I²C-адреса модуля. Допустимо в продакшене на текущей прошивке (двухфазный коммит v1.3).
Сценарий: проверка диапазона → запись кандидата в REG_I2C_ADDRESS (0x30) в RAM → запись магического байта 0xA5 в REG_ADDR_COMMIT_MAGIC (0x31) — взведено. Вызывающий код должен вызвать commit_address_change() в течение 5 секунд, иначе взведение устареет.
Raises:
-
RbAmpParamError—new_addrвне 0x08..0x77 или равен текущему адресу -
RbAmpIOError— сбой связи
dev.commit_address_change() -> None
Смена адреса (initialization) · 4.5 Адрес (0x30..0x31) (api-reference) · 6.1 Смена адреса — двухфазная фиксация (допустимо в production) (api-reference)
Шаг 2 из 2. Вызывать в течение 5 секунд после prepare_address_change().
Сценарий: проверить свежесть magic-взведения → CMD_COMMIT_ADDR (opcode 0x30) → сохранить во флеш → CMD_RESET → ~300 мс до отклика после загрузки → обновить внутреннее поле адреса. После перезагрузки REG_I2C_ADDRESS (0x30) (v1.3) показывает новый активный адрес — это каноническая проверка.
⚠ История: до исправлений v1.3 смена адреса ошибочно документировалась как доступная только на заводе. В v1.3 это производственная операция через двухфазную фиксацию.
Дополнительная тонкость:
⚠ Перезапуск и повторное перечисление после фиксации. После успешной фиксации устройство перезагружается и перечисляется заново на НОВОМ адресе. Последующие вызовы этого экземпляра дескриптора прозрачно обращаются к новому адресу, но ЛЮБОЙ ДРУГОЙ мастер на шине (другой скрипт Python, компонент ESP-IDF, отладочный зонд) продолжает считать, что устройство на старом адресе, пока его внутреннее состояние не обновят вручную.
Raises:
RbAmpTimeoutError— окно арминга (5 с) истеклоRbAmpIOError— сбой связи
dev.factory_reset() -> None
Команда CMD_FACTORY_RESET + ожидание 1500 мс.
Разрушающая операция. Стирает ВСЕ параметры флеша (модель CT, класс датчика, коэффициенты калибровки, адрес I²C). Модуль возвращается к заводским настройкам — RbAmpSensorClass становится UNSET, REG_CT_MODEL становится 0. Вся настройка, применённая через set_sensor_class() / set_ct_model*(), теряется. Следующий пользователь ДОЛЖЕН заново применить set_sensor_class() и set_ct_model*(), прежде чем учёт снова заработает. Это не «мягкий перезапуск» — для мягкого перезапуска используйте reset(). factory_reset() предназначен для восстановления из заведомо плохого состояния или для передачи модуля другому пользователю или другой установке.
Возбуждается: RbAmpIOError при сбое связи.
dev.reset() -> None
Команда CMD_RESET + ожидание 100 мс. Мягкий перезапуск устройства без потери параметров флеша.
Возбуждается: RbAmpIOError при сбое связи.
Идентификация и настройка (v1.3)
Эти методы позволяют мастеру точно понять, что именно подключено к шине (вариант, битовая карта возможностей, UID, метка), и подготовить новый или только что прошитый модуль к работе (провизионирование
- сохранение конфигурации во флеш).
dev.read_variant() -> int
Автоопределение варианта модуля (initialization) · Справочник протокола провода rbAmp (v1.3) (api-reference) · 3.6 Канонический алгоритм обнаружения (api-reference)
Читает регистр HW_VARIANT (0x55) модуля (канонический байт SKU v1.3):
| Код | SKU | каналы I | Канал U |
|---|---|---|---|
1 |
UI1 | 1 | да |
4 |
I1 | 1 | нет |
5 |
I2 | 2 | нет |
6 |
I3 | 3 | нет |
Это рекомендуемый путь для автоопределения — путь с зондированием NACK удалён (прошивка никогда не отвечает NACK на чтение; неотображённые адреса → 0x00).
dev.read_capability() -> int
Автоопределение варианта модуля (initialization) · 3.2 CAPABILITY (регистры 0x57/0x58, u16 LE, только чтение) (api-reference) · 8 · Примеры трассировки на линии (api-reference)
Читает 16-битную карту возможностей из регистров CAPABILITY (0x57/0x58), little-endian u16. Карта включает флаг фронтенда напряжения. Используйте её для определения возможностей (а не эвристики по версии).
dev.has_voltage() -> bool
Удобный помощник поверх read_capability() — возвращает True, если у модуля есть канал U. Кешируется в дескрипторе при первом вызове.
dev.read_product_id() -> int
3.5 PRODUCT_ID (0x54, u8, только чтение) (api-reference) · 4.8 Идентичность (0x54..0x6F) (api-reference)
Читает PRODUCT_ID (0x54) — байт-идентификатор семейства (rbAmp = 0x01). Используется сканером флота, чтобы убедиться, что устройство по адресу действительно rbAmp.
dev.read_uid() -> bytes
Считывает 96-битный уникальный идентификатор MCU из UID (0x5C..0x67) одной пакетной операцией (возвращает объект bytes длиной 12). UID уникален для каждого модуля и не меняется при повторной прошивке.
dev.read_label() -> str
Читает 8-байтовую пользовательскую метку из LABEL (0x68..0x6F). ASCII, дополнена нулями; возвращает строку (без NUL). Пустая строка, если метка не задана.
dev.set_label(label: str) -> None
Записывает 8-байтную метку. Строка обрезается до 8 байт или дополняется нулями. Запись побайтная (rbAmp не автоинкрементирует записи; пакет делает цикл по байтам автоматически). После записи нужен dev.save_user_config(), чтобы метка пережила сброс.
Возбуждается: RbAmpIOError при сбое связи.
dev.is_provisioned() -> bool
Проверяет, прошёл ли модуль первоначальную подготовку. Проверяется REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD) — 0xFB выставляется прошивкой, когда блок пользовательской конфигурации пуст или повреждён. Модуль с заводскими настройками возвращает False — после первой настройки модели CT и адреса нужен вызов save_user_config().
На v1.3 этот код нормален для девственного модуля (не фатален). Не прерывайте провизионирование при первом появлении 0xFB.
dev.save_user_config() -> None
6.5 Настройка — первичная прошивка + SAVE (api-reference) · 8.6 Настройка при первичной прошивке (api-reference)
Выполняет CMD_SAVE_USER_CONFIG (opcode 0x32) — сохраняет блок пользовательской конфигурации во флеш: SENSOR_CLASS, CT_MODEL по каналам, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Параметры заводской калибровки он не сохраняет.
Блокирует поток примерно на ~700 мс (цикл стирания и записи flash). Во время вызова не обращайтесь к модулю из других задач.
Выбрасывает: RbAmpIOError / RbAmpTimeoutError.
: подтверждение, что значение записано во флеш, требует перезагрузки и повторного чтения. См. раздел «Модель ошибок v1.3» ниже.
Модель ошибок v1.3 — два независимых канала
У ошибок два независимых канала, работающих по-разному. Понимание разницы важно для правильной интерпретации состояния модуля.
| Канал A — на стороне клиента, синхронно | Канал B — со стороны DUT, долговременно и асинхронно | |
|---|---|---|
| Где это живёт | Проверка внутри пакета (_validate_ct_code и т.д.) |
REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Когда срабатывает | До транзакции I²C (библиотека перехватывает) | После того как прошивка приняла запись и отклонила её |
| Что видит мастер | Сеттер возбуждает RbAmpParamError; REG_ERROR на устройстве остаётся 0x00 |
REG_ERROR = код отказа сразу; bit3 выставляется через несколько сотен миллисекунд после транзакции |
| Липкий | нет (только исключение) | REG_ERROR — результат последней записи; bit3 залипающий, сбрасывается записью единицы (W1C) |
| Типичный путь | Аргумент вне допустимых границ (channel ∉ {0,1,2}, code ∉ набора характеристик, sensor_class вне enum) | Сырая запись в регистр, которую пакет заранее не проверяет (низкоуровневый dev._io.write_reg() с некорректным байтом) |
Канал A — проверка на стороне клиента (сеттеры пакета)
Все сеттеры пакета (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels и т. д.) сначала проверяют аргументы на допустимые значения. Если аргумент вне диапазона, сеттер выбрасывает RbAmpParamError, не выполняя ни одной транзакции I²C. Поэтому REG_ERROR на устройстве не меняется:
from rbamp import RbAmp, RbAmpParamError
try:
dev.set_ct_model_ch(99, 3) # invalid channel
except RbAmpParamError as e:
print(f"client-side guard: {e}")
reg_err = dev.read_last_error()
print(f"REG_ERROR on the device: 0x{reg_err:02X}")
# → 0x00 (the package stopped it before the wire, REG_ERROR untouched)
Это значит: если вы хотите точно знать, почему сеттер не сработал, надёжный источник — само исключение (RbAmpParamError.args / str(e)). REG_ERROR на устройстве в этом сценарии ничего не говорит.
Канал B — отказ на стороне DUT (устойчивый асинхронный)
Если запись прошла через I²C (библиотека её не перехватила, потому что аргумент выглядел корректным), но прошивка отклонила её, вступает второй канал:
-
read_last_error()сразу возвращает код причины (например,0xFE = DEV_ERR_PARAM). Это итог последней записи: любая следующая успешная запись его перезапишет. Читать его нужно сразу после записи, до любой другой транзакции. -
has_error()— липкий индикатор W1C дляEVENT_FLAGS.bit3. Он не срабатывает мгновенно: на стенде замерена задержка в несколько сотен миллисекунд между отклонённой транзакцией и установкой bit3.
⚠ Не используйте has_error(), чтобы проверить только что сделанную запись. Для итога именно этой записи надёжен только read_last_error(), прочитанный сразу после записи, до любой другой транзакции (плюс исключение сеттера). has_error() — асинхронный канал для мониторинга опросом («не было ли сбоя между двумя проверками»), а не для синхронной проверки.
Сброс устойчивой ошибки — сбросьте обе (REG_ERROR и bit3)
bit3 заново вычисляется прошивкой каждые несколько сотен миллисекунд по текущему состоянию REG_ERROR. Поэтому простой clear_event_flags(1 << 3) не сработает — bit3 тут же снова выставляется из ещё не сброшенного REG_ERROR. Правильный порядок:
dev.clear_error() # zero REG_ERROR
dev.clear_event_flags(1 << 3) # reset sticky bit3
Если нужна атомарность, между ними не должно быть ни одной отклонённой записи.
dev.read_last_error() -> int
3. DATA_VALID (0xCE) никогда не становится 1 (troubleshooting) · Коды ошибок (REG_ERROR = 0x02) (troubleshooting) · 4 · Карта регистров (производство v1.3) (api-reference)
Читает регистр устройства REG_ERROR (0x02) напрямую (одно чтение по проводу) — итог последней транзакции, успешно принятой шиной (записи или команды). Не липкий: любая следующая успешная запись перезапишет его собственным итогом. Используется в Channel B (отклонение на стороне DUT) для расширенного кода причины.
dev.has_error() -> bool
Удобный помощник над EVENT_FLAGS.bit3 (ERROR_OCCURRED). Возвращает True, если bit3 установлен. Липкий W1C; не сбрасывается до явного сброса (с оговоркой — см. раздел «Clearing a durable error» выше).
dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None
4.4 Конфигурация флота (0x27..0x2F) (api-reference) · 8.8 Поток событий по порогам — запись порога → срабатывание → сброс W1C (api-reference)
EVENT_FLAGS (0x2A) — байт липких флагов; конкретные биты описаны в спецификации (включая ERROR_OCCURRED bit3). Сброс — write-1-to-clear.
dev.clear_error() -> None
Коды ошибок (REG_ERROR = 0x02) (troubleshooting) · 6.7 Восстановление из состояния ошибки — дерево решений (api-reference)
Выдаёт CMD_CLEAR_ERROR (opcode 0x31) — обнуляет REG_ERROR. Нужна для сброса устойчивой ошибки в паре с clear_event_flags(1 << 3).
Конфигурация нескольких каналов (v1.3)
На многоканальных модулях (I2, I3) у каждого токового канала своя модель CT-датчика. Атомарная утилита для массовой настройки — configure_channels().
dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None
Parameters:
-
cls— класс датчика (RbAmpSensorClass.SCT_013для токовых клещей SCT-013;WIRED_CT/BUILTIN_CTзарезервированы). -
models— последовательность кодов моделей CT (по одному на канал). n— длина (необязательно; по умолчанию =len(models)).
Внутри функция выполняет:
set_sensor_class(cls)один раз.-
Для каждого канала: подготовьте
REG_CT_MODEL = models[k]и выполнитеCMD_SET_CT_MODEL_CHk. -
Один терминальный
CMD_SAVE_USER_CONFIGв конце — то есть один цикл стирания и записи flash на всю конфигурацию.
Ограничение по варианту: если len(models) больше числа каналов варианта, лишние элементы игнорируются.
Raises:
-
RbAmpParamError— недопустимыйclsилиmodels[k](проверка на стороне клиента по классу;REG_ERRORна устройстве остаётся0x00). -
RbAmpIOError— ошибка шины. RbAmpTimeoutError— таймаут записи во флеш.
Допустимые коды по классам: SCT_013 → {1, 2, 3, 4, 5, 6, 7}; код вне набора возбуждает RbAmpParamError до обращения к шине. См. 03 · Sensor selection.
dev.read_ct_model_ch(ch: int) -> int
4.7 Зеркала проверки модели ТТ (0x51..0x53) (api-reference) · 8.10 Обратное чтение зеркала проверки модели ТТ (проверка после привязки) (api-reference)
Читает применённую (verify-mirror) модель CT-датчика на конкретном канале из регистра 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). Это чтение из RAM, а не подтверждение сохранения — для подтверждения записи во flash используйте dev.reset() + повторное чтение зеркала.
RbAmpFleet — управление несколькими модулями
Класс RbAmpFleet — основная высокоуровневая поверхность пакета v1.3. Он управляет набором модулей на общей шине I²C: обнаружение, подготовка, агрегация опросов, агрегация ошибок, синхронные снимки через широковещательный General Call.
Один флот привязан к одной шине (обычно SMBus(1) на CPython или I2C(0, ...) на MicroPython). Мягкий предел числа модулей — RBAMP_FLEET_MAX_MODULES = 16.
Жизненный цикл
RbAmpFleet(bus, max_modules: int = 16)
После del fleet все присоединённые дескрипторы освобождаются.
Обнаружение — scan()
Настройка нескольких модулей (initialization) · Опрос нескольких модулей — три стратегии (realtime-polling) · Проблемы с несколькими модулями (troubleshooting)
fleet.scan(match_product: bool = True) -> int
Опрашивает шину в диапазоне 0x08..0x77. Для каждого адреса, который отвечает ACK:
-
Проверяет идентичность (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Еслиmatch_product = True, требует совпадения с rbAmp PRODUCT_ID. -
Запускает детектор конфликтов. Подозрительные адреса попадают в список
excluded, а не во флот.
Возвращает количество модулей, добавленных во флот.
Возбуждается: RbAmpIOError, если шина заблокирована (Tier-2 wedge-canary).
Доступ к модулю
fleet.count # property: number of modules in the fleet
len(fleet) # equivalent to fleet.count
fleet[index] # a module by index
fleet.find(address) -> RbAmp | None # a module by address
fleet.add(dev: RbAmp) -> None # adopt an existing handle
for dev in fleet: # iteration
...
fleet.excluded -> tuple[int] # addresses that ended up in excluded
Опрос — poll_all()
Настройка нескольких модулей (initialization) · Опрос нескольких модулей — три стратегии (realtime-polling)
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]
Опрашивает все модули флота одним вызовом. Возвращает список кортежей; для каждого модуля:
RbAmpSnapshotилиNone(при ошибке)- POD
RbAmpFleetPollс полямиaddr,ok,channels
Устойчивость к пропускам: один молчащий модуль не отменяет опрос остальных.
Агрегация
fleet.total_power() -> float # W; summed over all channels
fleet.total_energy_wh() -> float # W·h; per-handle accumulators
fleet.poll_errors() -> dict[int, bool] # per-addr bit3 status
total_power суммирует активную мощность по всем каналам всех модулей. На I-вариантах активной мощности нет → они дают 0. В каноне 80% результата ≈ активная мощность модуля сети.
fleet.aligned_snapshot(group=0) -> list[dict]
Согласованный снимок периода по всему флоту по всем каналам каждого члена: рассылает широковещательный снимок General Call, затем читает среднюю мощность снимка по каждому каналу у каждого синхронизированного члена (read_period_avg_p). Возвращает по одному словарю на члена в порядке флота, с ключами addr, in_sync, period_valid, avg_p (список, по одной записи на канал; None, если член пропустил тик или не ответил). Снимок выравнивает только средние периода — живые показания (I, P, PF) между каналами выровнять нельзя.
Адресация и проверка конфликтов
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool # collision detected?
assign_address переназначает существующему модулю флота новый адрес: внутри — двухфазная фиксация + сброс; дескриптор во флоте обновляется автоматически.
check_conflict — проверка без записи, выполняемая по возможности, для конкретного адреса. Чтобы пройти все известные адреса, переберите флот.
Provisioning
6.5 Настройка — первичная прошивка + SAVE (api-reference)
⚠ В текущей сборке rbamp провизионирование выполняется через dev.prepare_address_change() + dev.commit_address_change() на вручную созданном дескрипторе RbAmp(bus, 0x50), затем fleet.add(dev). См. фрагмент в 06 · Examples, Сценарий 2.
ОБЯЗАТЕЛЬНО: ровно один девственный модуль на шине в момент провизионирования. Два модуля на 0x50 одновременно физически неразличимы по I²C — различить их нельзя даже специальным оборудованием.
Синхронизация GC флота — синхронные снимки по всему флоту
General Call (широковещание по адресу 0x00) (initialization) · Несколько модулей — одновременный снимок (period-metering) · 6.3 Широковещательный снимок GC — опциональная синхронизация флота (api-reference)
fleet.enable_gc_all(group: int = 0) -> int
fleet.gc_latch(group: int = 0, tick: int | None = None,
settle_ms: int = 50) -> int
fleet.check_sync(expected_tick: int) -> list[RbAmpFleetSync]
Для точной синхронизации снимков (рассинхронизация меньше 1 мс по всему флоту) используется широковещательный снимок I²C General-Call.
-
enable_gc_all(group)устанавливает флагGC_ENABLEрегистра FLEET_CONFIG иGROUP_IDна всех модулях флота и выполняетCMD_SAVE_USER_CONFIGна каждом (постоянно). Перезагрузка модулей после включения обязательна — выполняется автоматически. Возвращает количество модулей, на которых включение прошло успешно. -
gc_latch(group, tick, settle_ms)отправляет кадр GCA5 27 group tick_lo tick_hiпо адресу0x00. Еслиtick=None, тик автоматически увеличивается внутренним счётчиком. Возвращает широковещательный тик. -
check_sync(expected_tick)читаетGC_TICK (0x59)на каждом модуле. Возвращает список PODRbAmpFleetSyncс полями:
class RbAmpFleetSync:
addr: int # I²C address of the module
gc_tick: int # REG_GC_TICK; 0xFFFF = never received a GC
in_sync: bool # True if gc_tick == expected_tick
reachable: bool # False if the read NACKs / times out
Конфигурация флота по устройствам (v1.3)
Эти методы работают с одним модулем напрямую (без флота).
dev.enable_gc(enable: bool = True) -> None
Общий вызов (широковещание по адресу 0x00) (initialization) · 4.4 Конфигурация флота (0x27..0x2F) (api-reference)
enable_gc(True) записывает 1 во флаг GC_ENABLE регистра FLEET_CONFIG (0x27), сохраняет во флеш и выполняет сброс — после загрузки модуль начнёт принимать снимки GC. enable_gc(False) симметрично сбрасывает бит. Блокирует примерно на 1 секунду (ожидание SAVE_USER_CONFIG и сброса). Идемпотентно: ничего не делает, если текущее состояние уже совпадает с запрошенным.
dev.read_fleet_config() -> int
Читает байт FLEET_CONFIG (0x27). Полезно для подтверждения чтением.
dev.set_group_id(group: int) -> None / dev.read_group_id() -> int
GROUP_ID (0x28) — фильтр кадров GC: модуль реагирует только на кадры GC с совпадающим group_id. По умолчанию 0x00 (широковещательный).
dev.read_gc_tick() -> int
Читает GC_TICK (0x59) — последнее значение тика, полученное из кадра GC. 0xFFFF = модуль с момента загрузки ни разу не получал кадр GC.
RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool
Статический метод. Низкоуровневая отправка кадра GC A5 27 group tick_lo tick_hi напрямую по bus (без флота). Полезно, если флот ещё не создан, или если нужно вручную управлять счётчиком тиков.
RbAmp.broadcast_latch(bus) -> bool
Статический метод. Устаревшая обёртка — эквивалентна broadcast_latch_group(bus, group=0, tick=0). Для нового кода предпочтительна явная форма broadcast_latch_group с собственным tick для верификации свидетелей.
: возможность снимка General-Call (CAP_GC_LATCH, сообщаемая REG_CAPABILITY) должна быть в прошивке и GC должен быть включён на каждом модуле (dev.enable_gc(True) или fleet.enable_gc_all() переключают флаг GC_ENABLE регистра FLEET_CONFIG, по умолчанию ВЫКЛ). Новый модуль с заводскими настройками GC не принимает — это осознанная защита от случайной широковещательной рассылки на шине настройки. Если GC выключен на всём флоте, шина отклоняет кадр GC на уровне NACK; это обнаруживается, а не проходит молча. На устаревшем модуле без CAP_GC_LATCH обёртка переходит к последовательному снимку по каждому устройству.
Диагностика
dev.set_logger(log_callable) -> None
Необязательный приёмник диагностики. log_callable принимает один аргумент str. Если задан, пакет коротко записывает результаты probe(), устаревшие снимки и отказы по режиму.
Типичное использование:
import logging
log = logging.getLogger("rbamp")
log.setLevel(logging.INFO)
log.addHandler(logging.StreamHandler())
dev.set_logger(log.info)
# Or, simplest of all — a plain print:
dev.set_logger(print)
dev.sanity_reject_count: int
Счётчик значений float, отброшенных фильтром достоверности (!isfinite(x) or |x| > 10000). В установившемся режиме — 0. Ненулевое значение после повторов обычно означает редкий артефакт стека I²C, прошедший через слой повторов.
Диагностические счётчики MachineI2CBackend (только MicroPython)
MachineI2CBackend (внутренний бэкенд на MicroPython) предоставляет два счётчика:
-
backend.retry_exhaustion_count— сколько раз цикл повторов исчерпался без успеха (был выброшенRbAmpIOError) -
backend.retry_count_total— сколько раз цикл повторов успешно восстановился тихим повтором
К этим счётчикам обращаются через расширенный API:
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50) # the address is a parameter of RbAmp, not the backend
# ...soak-test for an hour...
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:", dev.sanity_reject_count)
SMBusBackend (CPython) не имеет слоя повторов — драйвер I²C ядра Linux не подвержен шаблону NACK.
dev.read_seq_digest() -> int
Читает байт последовательности дайджеста (0..255). Он меняется при каждом коммите нового набора показаний, поэтому два чтения с одинаковым значением пришли из одного коммита — полезно как проверка согласованности вокруг пакетного опроса. Это только маркер изменения (без контрольной суммы).
dev.reset_counters() -> None
Обнуляет все счётчики (RbAmp и бэкенд, если это MachineI2CBackend). Используйте в начале испытания на выносливость.
Метаданные и константы протокола
rbamp.__version__ # "1.6.0" — PEP 440 version
rbamp.__protocol_version__ # 0x04 — RBAMP_PROTOCOL_VERSION (v1.3)
rbamp.RBAMP_REG_SCHEMA_CRC32 # CRC32 of the schema codegen contract
REGISTERS и COMMANDS — автогенерируемые словари протокольного уровня:
from rbamp import REGISTERS, COMMANDS
REGISTERS["U_RMS"] # 0x86
REGISTERS["PERIOD_VALID"] # 0x07
COMMANDS["LATCH_PERIOD"] # 0x27
COMMANDS["SAVE_USER_CONFIG"] # 0x32 — user-facing persistence path
COMMANDS["SAVE_GAINS"] # 0x26 — factory-only; BLOCKED in production
COMMANDS["FACTORY_RESET"] # 0xAA
Используется внутри пакета. Открыто для продвинутых пользователей, которые выполняют сырую передачу через собственный бэкенд; обычным пользователям к этому не нужно прикасаться.
Подробности протокола на линии
Для портирования и отладки на логическом анализаторе.
Чтение регистров — автоинкремент
Пакетное чтение возвращает N подряд идущих байт, начиная с addr. На CPython — через bus.read_i2c_block_data(addr, start_reg, N), одной транзакцией.
Запись регистров — побайтно (БЕЗ автоинкремента)
⚠ Записи НЕ автоинкрементные. Пакетная ЗАПИСЬ записывает только первый байт.
Многобайтовый регистр записывается побайтно:
# WRONG — data loss
label = b"MyMeter1"
bus.write_i2c_block_data(0x50, 0x68, list(label)) # only 'M' lands
# CORRECT — byte-at-a-time loop
for i, byte in enumerate(label):
bus.write_byte_data(0x50, 0x68 + i, byte)
Касается записываемых многобайтных полей: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, заводское ограничение), NF (u16), THRESH (u16). Чтения пакетом допустимы.
Исключение: широковещательный кадр GC (5 байт на адрес 0x00) — отдельный путь протокола на проводе (приём general-call), отправляется одной транзакцией I²C.
Определение варианта
Авторитетный байт артикула — REG_HW_VARIANT (0x55) (dev.hw_variant):
| значение | SKU |
|---|---|
0x01 |
UI1 |
0x02 |
UI2 |
0x03 |
UI3 |
0x04 |
I1 |
0x05 |
I2 |
0x06 |
I3 |
Широковещательный снимок General-Call
Включается для каждого модуля отдельно флагом GC_ENABLE регистра REG_FLEET_CONFIG. По умолчанию ВЫКЛЮЧЕНО. Включается через CMD_SAVE_USER_CONFIG + CMD_RESET. После сброса модуль слушает широковещательный кадр по адресу 0x00:
addr=0x00 | A5 27
A5— магическое значение;27— опкодCMD_LATCH_PERIOD.—0x00= all-call, иначе должен совпасть сREG_GROUP_ID (0x28).— 16-битный счётчик периода.
Обнаружение отказа на 2 уровнях (C.10, подтверждено на железе):
- NACK адреса GC: если GC отключён по всему флоту,
bus.write_i2c_block_data(0x00, ...)возбуждаетOSError(или эквивалент бэкенда). Это жёсткая ошибка, а не тихий сброс. - Подтверждение по модулям: если NACK не было, прочитайте
REG_PERIOD_VALID (0x07)на каждом модуле.1= снимок успешен;0= на этом модуле GC выключен или период пуст.
Модель ошибок (v1.3)
REG_ERROR (0x02)— итог последней записи, НЕ липкий. Читайте СРАЗУ ПОСЛЕ операции.EVENT_FLAGS (0x2A) bit3— устойчивый сигнал (липкий W1C). Каноническое обнаружение ошибок — через bit3.
# Canonical durable monitoring
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
Ссылки
- 05 · Быстрый старт — ваш первый рабочий скрипт
- 06 · Examples — рабочие сценарии
-
10 · Устранение неполадок — расшифровка ошибок и решение типичных проблем
-
Исходники:
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Исходники и задачи: rb-amp/rbamp-python · эта страница в репозитории: docs/09_api_reference.md (v1.6.1)