02 · Линейки модулей
Что такое линейка модуля
Модули rbAmp выпускаются в двух линейках: BASIC и STANDARD (STD). Линейка модуля — это полная связка ревизии железа и прошивки, а не программный флаг. Переход между линейками требует физической смены SKU, а не обновления прошивки.
Со стороны пакета и пользовательского кода: один класс RbAmp обслуживает все линейки модулей, а общие читатели (voltage, current, power, power_factor, frequency) работают на всех них. Линейка модуля определяется автоматически при begin(). Модули STANDARD (STD) дополнительно открывают вызовы только для STD (учёт энергии на устройстве и т.д., см. ниже); вызов такого метода на модуле BASIC возбуждает RbAmpNotSupportedError.
Текущее состояние
Библиотека поддерживает модули BASIC и STANDARD (STANDARD — начиная с 1.6.0).
| Линейка модулей | Серийная |
|---|---|
| BASIC | ✅ да |
| STANDARD (STD) | ✅ да (поддерживается этой библиотекой с 1.6.0) |
BASIC — линейка модулей учёта потребления начального уровня
Аппаратное обеспечение
Экономичный аналоговый путь для типичных бытовых нагрузок. Модуль включает изолированный аналоговый фронтенд, бортовой стабилизатор питания и заводскую калибровку во флеш-памяти.
Поведение прошивки
Логика классического механического дискового счётчика — счёт идёт только вперёд; экспорт в сеть не вычитается.
Три "слоя" значений активной мощности ведут себя по-разному:
| Сигнал | Значение | Поведение на BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
мгновенная мощность RT, обновление около 100 мс | знаковая — отрицательное значение видно в реальном времени (экспорт) |
snap.avg_p[ch] (из dev.read_period_snapshot()) |
средняя мощность за период | каждое окно средней P по 100 мс ограничивается до max(P, 0) перед добавлением в накопитель периода |
dev.energy.wh(ch) |
накопленные Wh пакетом | монотонно — только потребление; экспорт не учитывается |
Иначе говоря: пользователь видит экспорт в показаниях RT, но на BASIC его нет в счётчике Wh пакета.
Типичные применения
-
Домохозяйства без собственной генерации (без солнечных панелей, ветряков, аккумуляторных систем)
-
Субучёт чисто потребляющих нагрузок (водонагреватели, двигатели, бытовые приборы)
-
Система мониторинга потребления, где двунаправленный учёт не нужен
Двунаправленный учёт на BASIC (со стороны мастера)
Если на BASIC нужно отдельно учитывать экспорт в сеть, делайте это на стороне мастера. Показание RT dev.power[0] имеет знак (или эквивалентный метод dev.read_power(0)), поэтому:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
t_now = time.monotonic()
dt_s = t_now - t_prev
t_prev = t_now
try:
p = dev.read_power(0)
except RbAmpIOError:
continue
dwh = p * dt_s / 3600.0
if p >= 0.0:
consume_wh += dwh
else:
export_wh += -dwh
На MicroPython замените time.monotonic() на time.ticks_ms() / time.ticks_diff() (точнее и экономнее по RAM на встраиваемых платформах), а time.sleep(0.1) — на time.sleep_ms(100). На CPython ничего менять не нужно.
Полный рабочий пример шаблона — в 06_examples.md, сценарий «Двунаправленный учёт со стороны мастера», а также исходники examples_upy/07_bidirectional_energy.py и examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — выпускаемая линейка модулей
Модули STANDARD — это поставляемая линейка модулей, которую библиотека поддерживает начиная с версии 1.6.0. Они используют другую (16-битную) карту регистров по сравнению с BASIC; библиотека скрывает различие — тот же класс RbAmp, та же проводка I²C и адрес, и те же общие чтения.
Что библиотека добавляет на модуле STD:
-
Энергия на устройстве:
dev.read_std_energy()возвращает собственные счётчики модуля за весь срок службы — активный импорт / экспорт / нетто и реактивную энергию в разрешении Wh, mWh и µWh, с данными по каналам.RbAmp.std_energy_delta(prev, now)даёт энергию, израсходованную между двумя показаниями, и устойчив к отключению питания. Для этих счётчиков мощность на мастере интегрировать не нужно. -
Учёт по периодам:
read_period_snapshot()и другие вызовы периода работают так же, как на BASIC.begin()выбирает источник — счётчики энергии модуля (период — разность двух показаний; команда latch не отправляется) или, если на модуле есть только банки latch, банк latch 0. Энергия нетто (экспорт вычитается). -
Latch-банки (модули, которые их сообщают):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Помощники многофазных измерений:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(только STD; на BASIC реактивная мощность этой библиотекой не предоставляется),dev.read_apparent(ch). -
Стартовый ток:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Полные блоки:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Некоторым вызовам STD нужен достаточно свежий образ модуля (счётчики энергии в микро-единицах, углы напряжения, стартовый ток). Если модуль такого не предоставляет, вызов возбуждает
RbAmpNotSupportedError("not available"). -
Используйте
dev.is_std, чтобы ветвить логику прикладного кода. -
Настройка класса датчика и модели CT, сброс и смена адреса, регистры идентификации, канал ошибок и событий, помощники флота и
wait_ready()— только для BASIC; на модуле STD они выбрасываютRbAmpNotSupportedError. -
Учёт энергии на устройстве, угол и стартовый ток проверены на CPython (
smbus2). Путь MicroPython 16 бит реализован, но ещё не проверен на железе — для этих возможностей предпочтителен CPython, пока релиз не скажет иначе.
Полные сигнатуры: 09 · API Reference.
Как определить линейку модуля во время работы
В текущей прошивке нет явного регистра «линейки модуля». Косвенные признаки доступны через свойства дескриптора:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std показывает линейку модуля (STD или BASIC). Остальные признаки (версия прошивки, число каналов, наличие датчика напряжения, вариант) описывают модуль, но не определяют линейку. dev.read_variant() — байт варианта BASIC; для продукта источником истины служит артикул на корпусе модуля.
Где в документации отмечены места, зависящие от линейки модуля
В тексте пакета и каноничной документации функции, зависящие от линейки модуля, отмечены явно, например:
— этот вызов недоступен на модуле BASIC.
Или, наоборот, поведение, специфичное для BASIC:
: счётчик dev.energy.wh(ch) монотонный — экспорт в сеть не учитывается. Для двунаправленного учёта см. сценарий «Двунаправленный учёт на стороне мастера» в 06_examples.md или используйте модуль STANDARD, где энергия за период нетто, а dev.read_std_energy() даёт раздельные счётчики импорта и экспорта.
Что дальше
-
03 · Current Sensor Selection — какой SCT-013 для какой задачи
-
04 · Подключение — особенности оборудования для каждого хоста (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Examples — сценарии для BASIC, включая двунаправленный учёт на стороне мастера
-
09 · API Reference — полный публичный API
Исходники и вопросы: rb-amp/rbamp-python · эта страница в репозитории: docs/02_tiers.md (v1.6.1)