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

09 · Справочник API

Карта регистров модуля: адресное пространство страницы 0 от 0x00 до 0xFF

Атомарный снимок периода: одна запись закрывает текущий период и открывает следующий

Полный публичный API пакета rbamp. Исходники — __init__.py (повторный экспорт), _rbamp_core.py (основной класс RbAmp), _snapshot.py (структуры POD и иерархия исключений), _energy.py (накопитель Wh), _registers.py (автогенерируемые константы).

Эта глава — справочник: сигнатуры, возвращаемые значения, побочные эффекты, граничные случаи. Рабочие примеры — в 06 · Примеры; для быстрого старта см. 05 · Быстрый старт.

Импорты

Python
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)
)

Минимальный импорт для типичного приложения:

Python
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. Стандартный шаблон Python try / except (а не last_error() + код возврата).

  • Асинхронный генератор для периодической потоковой передачи: async for snap in dev.stream_period(interval_s=...).

Типы

RbAmp

Python
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 для драйверов аппаратного ввода-вывода.

Иерархия исключений пакета rbamp: каждая ошибка наследует RbAmpError, который наследует OSError.

Примечание

: RbAmpParamError наследует RbAmpError и ValueError на CPython (множественное наследование). На MicroPython, где множественное наследование поддерживают не все порты, используется одиночное. С точки зрения пользователя try / except RbAmpParamError работает одинаково. Но try / except ValueError перехватывает только на CPython — на MicroPython этот обработчик пропускает ошибку. Код, который рассчитывает на кроссплатформенное поведение, должен явно перехватывать RbAmpParamError.

Стандартное использование:

Python
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

Python
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). Все поля в единицах СИ.

Python
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(). Примитив учёта энергии.

Python
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 — это диагностический таймер модуля.

Константы топологии

Python
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()

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

Определение линейки модуля (1.6.0). begin() сначала проверяет, является ли модуль модулем STD (16-битная карта регистров). Если да, дескриптор переключается в режим STD (dev.is_std становится True, dev.channels и dev.has_voltage_hw берутся из модуля), и begin() возвращает управление. Если нет, выполняется последовательность BASIC ниже. Для этого нужен бэкенд шины, способный на 16-битные транзакции; иначе модуль считается BASIC.

Последовательность для BASIC:

  1. Читает REG_VERSION — выбрасывает RbAmpIOError при NACK, RbAmpVersionError, если возвращается 0x00 или 0xFF.

  2. Кеширует топологию (на текущей прошивке begin() не выполняет автоопределения; использует подсказку из конструктора).

  3. Читает U_rms, чтобы определить, есть ли датчик напряжения (порог 1.0 В).

  4. Пишет CMD_LATCH_PERIOD (прайм) и ждёт 50 мс. Первый снимок после включения отбрасывается.

  5. Сохраняет time.monotonic() (или time.ticks_ms() на uPy) для последующего интегрирования энергии.

На модуле BASIC с клещами SCT-013 begin() также оценивает коррекцию по номиналу SCT-013.

Идемпотентно: безопасно вызывать повторно.

Контекстный менеджер

Python
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

Опрашивает флаг готовности модуля, пока он не установлен. Полезно после включения питания — модулю может понадобиться до 100 мс на первое окно RT.

Возбуждается: RbAmpTimeoutError, если бит не виден до истечения timeout_ms.

Свойства — состояние дескриптора

Python
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 при недопустимом аргументе.

Окна измерения по 100 мс идут подряд, DRDY импульсом срабатывает раз в окно, и мастер читает атомарный результирующий блок.

Свойства

Python
dev.voltage         -> float   # V — RMS voltage
dev.voltage_peak    -> float   # V — peak voltage
dev.frequency       -> float   # Hz — mains frequency

Индексация по каналам через _ChannelProxy — поддерживает индексацию [ch] и итерацию:

Python
dev.current         # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak    # _ChannelProxy
dev.power           # _ChannelProxy
dev.power_factor    # _ChannelProxy

Usage:

Python
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.

Методы (полностью эквивалентны форме со свойствами)

Python
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

Python
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, ничего не отправляя на шину.

Python
dev.is_std        -> bool   # True on an STD module (set by begin())
dev.std           -> object # internal STD client (advanced use) or None on BASIC

Чтения

Python
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 всегда равен импорту минус экспорт обрезанных частей.

  • Поканальные записи заполняются, только если оба снимка содержат одинаковое число каналов.

Python
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")

Пусковой ток и конфигурация

Python
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.

Python
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 для снимка без выборок.

Python
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

Читает бит готовности снимка. Возвращает True, если последний снимок свежий.

dev.read_period_avg_power(ch=0) -> float

Средняя активная мощность на канале за закрытый период. Вызывать после 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

Пиковая мгновенная мощность на канале 0 за закрытый период. ch=0 только на прошивке v1.

dev.read_period_latch_ms() -> int

Длительность периода с точки зрения устройства, в мс.

Диагностическое значение.

Внутренний таймер модуля точен ограниченно. Для интегрирования энергии используйте master_dt_ms из RbAmpPeriodSnapshot, а не это поле.

dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot

Рекомендуемая точка входа для учёта по периодам. Полная последовательность внутри:

  1. Если skip_latch=True — пропустить запись команды снимка (для шаблона из нескольких модулей после ручной серии команд снимка).

  2. Иначе — запишите CMD_LATCH_PERIOD.

  3. Запомните time.monotonic(), чтобы вычислить master_dt_ms.
  4. time.sleep(settle_ms / 1000) — по умолчанию 50 мс.
  5. Проверьте флаг готовности снимка. Если 0 — возбудите RbAmpStaleError (предыдущая метка времени сохраняется, поэтому следующий успешный снимок покроет весь интервал и Wh останется точным).

  6. Прочитайте avg_p[0..channels-1] + max_p + latch_ms.

  7. Обновите метку времени и вызовите 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).

Python
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:

Python
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

Накопитель Wh по каналам. Доступен через свойство — объект принадлежит пакету:

Python
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(). Он знаковый — отрицательное значение означает чистый экспорт.

Формула интегрирования:

Text
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

Задаёт класс датчика тока и сохраняет его во flash. Блокирует, ~705 ms.

Python
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

Нативный протокол

4.3 Система (0x20..0x25) (api-reference)

Читает закреплённый класс датчика: 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 (класс не задан):

Text
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

Поканальная форма. Задаёт модель токовых клещей для конкретного канала.

Внутри: записать 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. Каналы можно настраивать в любом порядке.

Python
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 служат только для обратного чтения при проверке состояния и в шаблонах «прочитать — сравнить — записать»:

Python
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()), или после обнаруженного перезапуска. В одной ситуации (модель записана в текущем цикле питания) библиотека может выполнить один сброс модуля, чтобы прочитать сохранённое усиление.
Python
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

Шаг 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

Шаг 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

Читает регистр 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

Читает 16-битную карту возможностей из регистров CAPABILITY (0x57/0x58), little-endian u16. Карта включает флаг фронтенда напряжения. Используйте её для определения возможностей (а не эвристики по версии).

dev.has_voltage() -> bool

Удобный помощник поверх read_capability() — возвращает True, если у модуля есть канал U. Кешируется в дескрипторе при первом вызове.

dev.read_product_id() -> int

Читает 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

Выполняет 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 на устройстве не меняется:

Python
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. Правильный порядок:

Python
dev.clear_error()                     # zero REG_ERROR
dev.clear_event_flags(1 << 3)         # reset sticky bit3

Если нужна атомарность, между ними не должно быть ни одной отклонённой записи.

dev.read_last_error() -> int

Читает регистр устройства 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

EVENT_FLAGS (0x2A) — байт липких флагов; конкретные биты описаны в спецификации (включая ERROR_OCCURRED bit3). Сброс — write-1-to-clear.

dev.clear_error() -> None

Выдаёт 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)).

Внутри функция выполняет:

  1. set_sensor_class(cls) один раз.
  2. Для каждого канала: подготовьте REG_CT_MODEL = models[k] и выполните CMD_SET_CT_MODEL_CHk.

  3. Один терминальный 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

Читает применённую (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.

Жизненный цикл

Python
RbAmpFleet(bus, max_modules: int = 16)

После del fleet все присоединённые дескрипторы освобождаются.

Обнаружение — scan()

Python
fleet.scan(match_product: bool = True) -> int

Опрашивает шину в диапазоне 0x08..0x77. Для каждого адреса, который отвечает ACK:

  1. Проверяет идентичность (PRODUCT_ID, HW_VARIANT, CAPABILITY). Если match_product = True, требует совпадения с rbAmp PRODUCT_ID.

  2. Запускает детектор конфликтов. Подозрительные адреса попадают в список excluded, а не во флот.

Возвращает количество модулей, добавленных во флот.

Возбуждается: RbAmpIOError, если шина заблокирована (Tier-2 wedge-canary).

Доступ к модулю

Python
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()

Python
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]

Опрашивает все модули флота одним вызовом. Возвращает список кортежей; для каждого модуля:

  • RbAmpSnapshot или None (при ошибке)
  • POD RbAmpFleetPoll с полями addr, ok, channels

Устойчивость к пропускам: один молчащий модуль не отменяет опрос остальных.

Агрегация

Python
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) между каналами выровнять нельзя.

Адресация и проверка конфликтов

Python
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 флота — синхронные снимки по всему флоту

Python
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.

  1. enable_gc_all(group) устанавливает флаг GC_ENABLE регистра FLEET_CONFIG и GROUP_ID на всех модулях флота и выполняет CMD_SAVE_USER_CONFIG на каждом (постоянно). Перезагрузка модулей после включения обязательна — выполняется автоматически. Возвращает количество модулей, на которых включение прошло успешно.

  2. gc_latch(group, tick, settle_ms) отправляет кадр GC A5 27 group tick_lo tick_hi по адресу 0x00. Если tick=None, тик автоматически увеличивается внутренним счётчиком. Возвращает широковещательный тик.

  3. check_sync(expected_tick) читает GC_TICK (0x59) на каждом модуле. Возвращает список POD RbAmpFleetSync с полями:

Python
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

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(), устаревшие снимки и отказы по режиму.

Типичное использование:

Python
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:

Python
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). Используйте в начале испытания на выносливость.

Метаданные и константы протокола

Python
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 — автогенерируемые словари протокольного уровня:

Python
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 bytes возвращает N подряд идущих байт, начиная с addr. На CPython — через bus.read_i2c_block_data(addr, start_reg, N), одной транзакцией.

Запись регистров — побайтно (БЕЗ автоинкремента)

⚠ Записи НЕ автоинкрементные. Пакетная ЗАПИСЬ + N bytes записывает только первый байт.

Многобайтовый регистр записывается побайтно:

Python
# 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:

Text
addr=0x00 | A5 27   
  • A5 — магическое значение; 27 — опкод CMD_LATCH_PERIOD.
  • — 0x00 = all-call, иначе должен совпасть с REG_GROUP_ID (0x28).
  • — 16-битный счётчик периода.

Обнаружение отказа на 2 уровнях (C.10, подтверждено на железе):

  1. NACK адреса GC: если GC отключён по всему флоту, bus.write_i2c_block_data(0x00, ...) возбуждает OSError (или эквивалент бэкенда). Это жёсткая ошибка, а не тихий сброс.
  2. Подтверждение по модулям: если NACK не было, прочитайте REG_PERIOD_VALID (0x07) на каждом модуле. 1 = снимок успешен; 0 = на этом модуле GC выключен или период пуст.

Модель ошибок (v1.3)

  • REG_ERROR (0x02) — итог последней записи, НЕ липкий. Читайте СРАЗУ ПОСЛЕ операции.
  • EVENT_FLAGS (0x2A) bit3 — устойчивый сигнал (липкий W1C). Каноническое обнаружение ошибок — через bit3.
Python
# 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

Ссылки


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