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

01 · Обзор

Цепочка сигнала rbAmp: датчик → модуль → I²C → мастер → облако / Home Assistant

Что такое rbAmp

rbAmp — компактный аппаратный модуль для прецизионного измерения параметров сетевого переменного тока по интерфейсу I²C. Построен на микроконтроллере с интегрированным изолированным аналоговым входным каскадом и заводской калибровкой, хранимой во флеше.

С точки зрения интегратора модуль ведёт себя как стандартное ведомое устройство I²C: вы создаёте RbAmp(bus, 0x50), вызываете dev.begin() и получаете готовые значения через свойства и методы. Тот же исходный код работает на MicroPython (с machine.I2C) и на CPython (с smbus2) — бэкенд выбирается автоматически по типу объекта шины.

Термины, используемые в этих документах

  • Линейка модуля — BASIC или STANDARD (STD): продуктовая линейка модуля (см. 02).
  • Вариант — UI1, UI2, UI3, I1, I2, I3 (и UI5/UI7): сколько токовых каналов и есть ли вход напряжения.
  • Версия прошивки / версия образа модуля — программа внутри модуля; некоторым вызовам STD нужен достаточно свежий образ.
  • Показание RT — мгновенное значение (напряжение, ток, мощность), обновляемое модулем каждые 100 мс.
  • Период / снимок — снимок замораживает итоги текущего периода и начинает следующий; снимок периода — это замороженный результат (средняя мощность по каналам).
  • Устаревший снимок — модуль не подготовил свежий снимок; библиотека выбрасывает RbAmpStaleError, а следующий хороший снимок покрывает весь интервал.
  • Праймер — первый снимок, который делает begin(); он отбрасывает всё, что накопилось с момента включения питания.
  • GC (General Call) — один широковещательный кадр I²C, заставляющий несколько модулей сделать снимок в один и тот же момент.
  • DRDY — необязательный вывод, импульсом сигнализирующий примерно каждые 100 мс о готовности новых данных RT.

Один модуль или много

Один модуль или много: начните с одного RbAmp; для нескольких используйте RbAmpFleet. Пакет rbamp работает с одним модулем, а также с группой модулей на одной шине I²C. Канонический многомодульный сценарий — один главный модуль на вводе сети плюс N модулей на отдельных нагрузках, все на одной шине, управляемой одним ESP32 / RPi / SBC. Библиотека предоставляет класс RbAmpFleet — один объект, через который вы сканируете шину, опрашиваете все модули одним вызовом, получаете общую мощность и баланс «ввод − Σ(потребители)», ловите ошибки по каждому модулю и при необходимости синхронизируете снимки периодов широковещательной командой.

Многоканальные модули тоже поддерживаются — только ток I2 / I3 (два или три ТТ) и модули с напряжением UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 токовых каналов, с мощностью, PF и Wh по каждому каналу). У каждого канала своя модель датчика. Это типично для субщита, где одна точка установки контролирует несколько фидеров.

Работа с одним модулем — минимальный случай той же библиотеки: класс RbAmp — строительный блок, на котором надстроен RbAmpFleet. Если на шине один модуль, используйте тот же дескриптор напрямую — API флота не нужен.

Сценарий 80% — ввод сети + N субнагрузок

Один модуль на вводе сети и по одному модулю на каждую подключённую нагрузку делят одну шину I²C с мастером, который опрашивает их все одним вызовом флота.

  • 1 модуль на вводе сети — общее потребление и качество сети.
  • N модулей на отдельных нагрузках — поканальный учёт.
  • Многоканальные модули тоже подходят для этого случая: один UI2 / UI3 / UI5 / UI7 (или I2 / I3) может учитывать несколько нагрузок, каждую на своём канале — N модулей не обязательно означают N нагрузок.
  • Один вызов fleet.poll_all() опрашивает всё; баланс mains − Σ(sub_loads) показывает «остальное» (фоновое потребление, неучтённые нагрузки, утечки).

  • Один общий временной отсчёт мастера → корректный учёт Wh без дрейфа между модулями.

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

Важная архитектурная деталь. I-варианты (I1/I2/I3) измеряют только ток — у них нет напряжения, активной мощности и PF. Активная энергия (Wh) и мощность считаются только на UI-вариантах (у них есть входной каскад напряжения). В каноническом развёртывании роль «счётчика сети» (учёт энергии) выполняет один UI1 на вводе сети; роль субсчётчика (детализация тока по нагрузкам) — модули I2/I3 (или UI2 / UI3 / UI5 / UI7, когда нужны мощность и Wh по каждой нагрузке).

Подробности — в главе 06 · Примеры, сценарий 1 («Ввод + N субнагрузок — канон 80%»). Справочник API — в главе 09 · Справочник API, раздел «Менеджер флота».

Что измеряет rbAmp

Величина Тип Python Диапазон
Действующее напряжение U_rms float, V 0…300 V
Пиковое напряжение U_peak float, V 0…450 V
Действующий ток I_rms float, A зависит от выбранного датчика — см. 03_sensor_selection.md
Пиковый ток I_peak float, A зависит от выбранного датчика
Активная мощность P (знаковая в RT) float, W зависит от выбранного датчика
Коэффициент мощности PF float −1…+1
Частота сети int, Гц 50 / 60 Гц (определяется)
Усреднённая за период P float, W как P
Примечание

Мгновенное значение активной мощности P всегда со знаком на любой линейке модулей (отрицательное значит экспорт в сеть). Поведение усреднённого за период значения (snap.avg_p[ch] в RbAmpPeriodSnapshot) зависит от линейки модуля — см. раздел «Линейки модулей» ниже и 02_tiers.md.

Подключение

Модуль подключается к хосту четырьмя проводами на стороне низкого напряжения; всё, что касается сети, остаётся внутри корпуса.

Провод Цель
VCC +5 В (4.5..5.5 В), ток ~15 мА, пиковый ~25 мА
GND общий с хостом (обязательно)
SDA, SCL I²C, логика 3.3 В, терпит 5 В. Встроенные подтяжки 4.7 кОм
DRDY необязательно, открытый сток LOW ~10 мкс каждые ~100 мс

Адрес по умолчанию — 0x50 (7-битный, диапазон для смены 0x08..0x77). Рекомендуемая скорость для MicroPython на ESP32 — 50 кГц; для CPython через I²C ядра обычно — 100 кГц (паттерн NACK через API ядра Linux не проявляется).

Полные правила (длина шины, рекомендации по подтяжкам на шине с несколькими модулями, схемы подключения для RPi / ESP32 / RP2040 / STM32) — в главе 04 · Wiring.

Линии модулей (краткая шпаргалка)

BASIC и STANDARD (STD) модули выпускаются; STANDARD поддерживается этой библиотекой с 1.6.0.

BASIC — это однонаправленный учёт (только потребление) по логике классического механического счётчика:

Линейка модулей Мгновенная мощность RT dev.power[ch] Накопитель периода snap.avg_p[ch] Накопитель Wh пакета
BASIC со знаком (отрицательное = экспорт в сеть, видно в реальном времени) каждое окно 100 мс средней P ограничивается до max(P, 0), прежде чем добавляется в накопитель периода monotonic — учёт только потребления
STANDARD (STD) знаковое те же вызовы, что и на BASIC; источник — счётчики энергии модуля или latch-банк 0, выбирается в begin(); энергия чистая (экспорт вычитается) dev.energy интегрирует период; собственные итоги модуля: read_std_energy() (см. главу 02)

Подробности — в главе 02 · Линейки модулей. На уровне пакета используется один и тот же класс RbAmp независимо от линейки модуля; различия проявляются в значениях, которые возвращает модуль.

Примечание

Двунаправленный учёт на BASIC: dev.energy.wh(ch) на линейке BASIC даёт только потребление. Если нужно учитывать экспорт отдельно, снимайте мгновенную мощность dev.power[0] (или dev.read_power(0)) примерно с 10 Гц и разделяйте положительные и отрицательные значения по двум своим накопителям. Пример — в 06_examples.md, сценарий «Bidirectional metering on the master side».

Что делает этот пакет

Основная задача — скрыть протокольный обмен и избавить пользовательский код от рутины работы с регистрами, порядком байтов и временем установления после команд. Кроме того, пакет считает энергию (Wh): модуль возвращает только усреднённую по периоду мощность, а интегрирование выполняет мастер по time.monotonic() / time.ticks_us().

Без пакета (прямой доступ к регистрам через smbus2)

Python
import struct
from smbus2 import SMBus, i2c_msg

# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
    buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("

С пакетом

Python
from smbus2 import SMBus
from rbamp import RbAmp

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    u_rms = dev.voltage          # property (one call = one transaction)
    # or: u_rms = dev.read_voltage()

Чтение периода — без пакета

Python
import time, struct

with SMBus(1) as bus:
    # Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
    bus.write_byte_data(0x50, 0x01, 0x27)   # REG_COMMAND, CMD_LATCH_PERIOD
    t_latch = time.monotonic()
    time.sleep(0.050)                        # settle

    bus.write_byte(0x50, 0x07)
    if bus.read_byte(0x50) & 0x01 == 0:
        # snapshot is stale — keep the previous t_prev_latch, so the next
        # good snapshot covers the full interval
        raise SystemExit("stale snapshot")

    # ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
    #   dt_s = time.monotonic() - t_prev_latch
    #   E_Wh += avg_p * dt_s / 3600

Чтение периода — с пакетом

Python
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    snap = dev.read_period_snapshot()        # snapshot + settle + valid + read + Wh tick
    print(snap.avg_p[0], "W")
    print(dev.energy.wh(0), "Wh")

Внутри пакет гарантирует:

  • Пауза 50 мс после CMD_LATCH_PERIOD и корректное чтение снимка.
  • Проверка флага valid перед чтением; при устаревшем снимке выбрасывается RbAmpStaleError.

  • Сохраняем предыдущую метку времени при устаревшем снимке, чтобы следующий хороший снимок покрыл весь интервал и Wh оставался точным.

  • Учёт Wh по каналам в двойной точности (CPython — 64-битный float; MicroPython — зависит от сборки, см. 04 · Wiring).

  • Автоматическая загрузка коэффициентов калибровки при выборе датчика тока через dev.set_sensor_class(cls) + dev.set_ct_model(code) — пользователю не нужно знать о внутренних регистрах калибровки.

Когда использовать пакет, а когда прямой доступ к шине

Задача Пакет Прямой доступ через smbus2 / machine.I2C
Чтение U / I / P / PF / частоты ✅ только для отладки на логическом анализаторе
Учёт энергии за период ✅ только если Wh хранятся вне пакета (например, в БД на стороне мастера)
Несколько модулей на одной шине ✅ (через последовательный снимок + общее установление) —
Двунаправленный учёт на BASIC ✅ (через чтения RT — см. 06_examples.md) альтернатива — собственный цикл RT-чтения
Асинхронная потоковая передача через asyncio / uasyncio ✅ (async for snap in dev.stream_period()) сложно — встроенной асинхронной обёртки нет
Перенос на другую платформу n/a ✅ — см. rbamp-docs (карта регистров и протокол)

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

Архитектура

Где находится скрипт Python: скрипт, пакет rbamp, бэкенд I²C и модуль rbAmp, с указанием скорости I²C для каждого хоста.

Text
┌─────────────────────────────────────────────────────┐
│  User code (.py)                                    │
│   from smbus2 import SMBus                          │
│   from rbamp import RbAmp, RbAmpSensorClass         │
│   with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:    │
│       # __enter__ calls dev.begin() itself;         │
│       # explicit begin() shown for transparency     │
│       dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│       dev.set_ct_model(3)                           │
│       snap = dev.read_period_snapshot()             │
│       dev.energy.wh(0)                              │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Public API of the RbAmp class (rbamp/__init__.py)  │
│   ┌─────────────────────────────────────────────┐   │
│   │ Lifecycle:      begin / probe / wait_ready  │   │
│   │ RT properties:  .voltage / .power[ch] /     │   │
│   │                 .current[ch] / .frequency   │   │
│   │ RT methods:     read_voltage / read_power / │   │
│   │                 read_all                    │   │
│   │ Period:         latch_period /              │   │
│   │                 read_period_snapshot        │   │
│   │ Async:          stream_period               │   │
│   │ Configuration:  set_sensor_class /          │   │
│   │                 set_ct_model                │   │
│   │ Diagnostics:    retry_exhaustion_count /    │   │
│   │                 sanity_reject_count         │   │
│   │ Exceptions:     RbAmpError → IOError /      │   │
│   │                 TimeoutError / StaleError / │   │
│   │                 ParamError / ModeError /    │   │
│   │                 VersionError                │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Backend selection (inside __init__):        │   │
│   │  bus.readfrom_mem  → MachineI2CBackend      │   │
│   │  bus.read_byte_data → SMBusBackend          │   │
│   │  duck-typed        → custom (FTDI / mocks)  │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Instance state:                             │   │
│   │  • RbAmpEnergy — Wh accumulator             │   │
│   │  • RbAmpSnapshot / RbAmpPeriodSnapshot      │   │
│   │  • Time of last snapshot (monotonic)           │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Backend — native I²C on the host platform:         │
│   smbus2 (CPython)  /  machine.I2C (MicroPython)    │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  rbAmp module at address 0x50                       │
│   • U / I / P / PF measurement pipeline (~100 ms)   │
│   • Period accumulator (atomic CMD_LATCH_PERIOD)    │
└─────────────────────────────────────────────────────┘

Иерархия исключений

В отличие от Arduino-библиотеки (где ошибки сообщаются через lastError() + код возврата) и компонента ESP-IDF (где через esp_err_t), Python-пакет использует классический шаблон Python — иерархию исключений.

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

Стандартный шаблон Python:

Python
from rbamp import RbAmp, RbAmpStaleError, RbAmpError

try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
    continue
except RbAmpError as e:
    log.warning("rbAmp failure: %s", e)

Диаграммы взаимодействия

Ход dev.begin()

Последовательность транзакций на шине, которые выполняет begin(): чтение версии, определение линейки модуля, отправка прайм-снимка, затем возврат.

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─dev.begin()►                     │                       │
  │             ├─read_u8(REG_VERSION)►                      │
  │             │                    ├──[0x50, 0x03]────────►│
  │             │                    │◄────────────────ACK───┤
  │             │                    ├──[read 1 byte]───────►│
  │             │                    │◄──────────────[0x04]──┤
  │             │◄─────── version_byte ─────┤                  │
  │             │                    │                       │
  │             ├─read_float_le(U_RMS)►(4 single-byte reads) │
  │             │  → 226.3 V         │                       │
  │             │  → has_voltage_hw = True                   │
  │             │                    │                       │
  │             ├─write_cmd(LATCH)──►│                       │
  │             │                    ├──[0x50, 0x01, 0x27]──►│
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │◄────self────┤  (or raises RbAmpIOError on failure)        │

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

Ход dev.read_period_snapshot()

Последовательность read_period_snapshot(): снять снимок периода, прочитать блок снимка, для BASIC — интегрировать энергию на мастере, для STD — читать счётчики, встроенные в устройство.

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─read_period_snapshot()►          │                       │
  │             ├─write_cmd(LATCH)──►│  t_now = time.monotonic()
  │             │                    │                       │
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │             ├─is_period_valid()─►│                       │
  │             │  → True            │                       │
  │             │                    │                       │
  │             ├─read_float_le(AVG_P0)►(4 reads)            │
  │             ├─read_float_le(MAX_P0)►(4 reads)            │
  │             ├─read_u32_le(LATCH_MS)►(4 reads)            │
  │             │                    │                       │
  │             │  dt = t_now − last_latch                    │
  │             │  energy.wh[ch] += avg_p[ch] × dt / 3600    │
  │             │  last_latch = t_now                         │
  │             │                    │                       │
  │◄─snap──────┤                    │                       │

Атомарный снимок на стороне модуля гарантирует, что каждое измерение внутри периода попадает ровно в один снимок — без дублирования и потерь на границе периода.

Соответствие прямому API регистров

Таблица для тех, кто переходит со своей работы с прямым доступом к шине:

Прямой API (smbus2 / machine.I2C) Эквивалент пакета
Ручное 4-байтовое чтение + struct.unpack dev.voltage (свойство) или dev.read_voltage()
Чтение по каналу read_byte × 4 dev.power[ch] (_ChannelProxy) или dev.read_power(ch)
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) dev.latch_period(); time.sleep(0.05) (или напрямую dev.read_period_snapshot())
Проверка read_byte(0x07) & 1 dev.is_period_valid() или поле snap.valid
Ручная формула E_Wh += avg_p × dt / 3600 dev.energy.wh(0) — обновляется автоматически
Ручная настройка токового датчика через прямой API регистров dev.set_sensor_class(cls) + dev.set_ct_model(code) — заводские пресеты загружаются автоматически

Что дальше


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