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

02 · Линейки модулей

Линейки модулей BASIC и STANDARD (STD) и то, что предоставляет каждая.

Что такое линейка модуля

Модули 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 учитывает только потребление на модуле, а экспорт обрабатывается на мастере; STD хранит накопительные счётчики на устройстве.

Если на BASIC нужно отдельно учитывать экспорт в сеть, делайте это на стороне мастера. Показание RT dev.power[0] имеет знак (или эквивалентный метод dev.read_power(0)), поэтому:

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

Как определить линейку модуля во время работы

Как определить во время работы, модуль BASIC или STANDARD (STD) подключён.

В текущей прошивке нет явного регистра «линейки модуля». Косвенные признаки доступны через свойства дескриптора:

Python
# 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; для продукта источником истины служит артикул на корпусе модуля.

Где в документации отмечены места, зависящие от линейки модуля

В тексте пакета и каноничной документации функции, зависящие от линейки модуля, отмечены явно, например:

Только STD

— этот вызов недоступен на модуле BASIC.

Или, наоборот, поведение, специфичное для BASIC:

BASIC

: счётчик dev.energy.wh(ch) монотонный — экспорт в сеть не учитывается. Для двунаправленного учёта см. сценарий «Двунаправленный учёт на стороне мастера» в 06_examples.md или используйте модуль STANDARD, где энергия за период нетто, а dev.read_std_energy() даёт раздельные счётчики импорта и экспорта.

Что дальше


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