01 · Обзор
Что такое 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 субнагрузок
- 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)
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("
С пакетом
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()
Чтение периода — без пакета
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
Чтение периода — с пакетом
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 (карта регистров и протокол) |
Для всех типичных задач из первых строк пакет — правильный путь.
Архитектура
┌─────────────────────────────────────────────────────┐
│ 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 — иерархию исключений.
Стандартный шаблон 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()
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()
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) — заводские пресеты загружаются автоматически |
Что дальше
- 02 · Линейки модулей — какая линейка для какой задачи
-
04 · Wiring — подтягивающие резисторы, длина шины, проводка по хостам (RPi / ESP32 / RP2040 / STM32)
-
05 · Быстрый старт — первый рабочий скрипт для обоих бэкендов
-
06 · Examples — обзор готовых сценариев
-
09 · Справочник API — каждый публичный класс, метод, свойство и исключение
-
10 · Устранение неполадок — когда что-то не работает
Исходники и задачи: rb-amp/rbamp-python · эта страница в репозитории: docs/01_overview.md (v1.6.1)