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

05 · Быстрый старт

Пятиминутное «привет, мир»: установите пакет, подключите модуль, выберите датчик и считайте первое значение RT и первый снимок периода (Wh). Руководство охватывает обе среды выполнения параллельно — MicroPython (на ESP32 / RP2040 / STM32 / Pyboard) и CPython (на Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).

Подробности (распиновка для конкретного хоста, многомодульная шина, выбор SCT-013 по диапазону) — в соседних главах:

Что понадобится

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

⚠ Безопасность сети. Сетевое напряжение может убить. Отключите и заблокируйте цепь перед подключением клемм L/N или установкой клещей; подключение к сети и любые работы внутри щитка поручайте квалифицированному специалисту. Охватывайте клещами один проводник (L) — никогда весь кабель (охват L и N даёт показание около 0). Сами клещи бесконтактные.

  • Модуль rbAmp (любая линейка, для простоты UI1)
  • Один из этих хостов:
  • CPython: Raspberry Pi (любая модель) / Orange Pi 5 / Rock Pi 5 / x86 + USB-I²C адаптер

  • MicroPython: ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)

  • Клещи CT SCT-013 с номиналом, рассчитанным на ваш максимальный ток (5А / 10А / 30А / 50А / 100А)

  • Питание модуля 5 В (от USB-5V хоста или внешнего источника)
  • Цепь переменного тока для измерения (лампа, чайник или бытовой прибор)

По какому пути идти?

Проверьте dev.is_std (или метку SKU на модуле — см. 02 · Module lines). Модуль STD: пропустите шаги 4–5 и перейдите к 06 · Examples, Сценарий 11. Модуль BASIC: выполните все шаги. Шаг 3 и шаг 4 одинаковы для обоих.

Путь к первому показанию: подключите модуль, задайте модель клещей, затем прочитайте напряжение, ток и мощность.

Шаг 1 — установка пакета

CPython (на Linux SBC или x86)

Shell
pip install rbamp

(В Debian/Ubuntu можно использовать системный аналог smbus2: sudo apt install python3-smbus, но рекомендуется smbus2 из pip — он поддерживает менеджер контекста with SMBus(...).)

Verify:

Shell
rbamp --version          # rbamp 1.6.0
rbamp --bus 1 scan       # I²C scan, should show 0x50

MicroPython (на ESP32 и других)

Shell
mpremote mip install github:rb-amp/rbamp-python

Или скопируйте пакет вручную:

Shell
mpremote cp -r path/to/rbamp/ :rbamp/

Пакет устанавливается в /lib/rbamp/ на устройстве.

Шаг 2 — Подключение

Четыре провода плюс необязательный DRDY:

Вывод rbAmp Мастер
VCC +5 В (диапазон 4.5..5.5 В)
GND GND
SDA I²C SDA (RPi pin 3, ESP32 GPIO21, RP2040 GPIO0/и т.д.)
SCL I²C SCL (RPi, контакт 5; ESP32 GPIO22; RP2040 GPIO1 и т. д.)

Питание должно быть 5 В. Линии I²C работают на логике 3.3 В, но допускают 5 В. На плате модуля уже есть встроенные подтягивающие резисторы 4.7 kΩ — для одного модуля внешние не нужны.

Полная таблица выводов для каждого хоста — в 04 · Wiring.

Токовые клещи SCT-013 охватывают только проводник линии (L), стрелка на корпусе клещей указывает в направлении тока к нагрузке. Подробнее — в 04 · Подключение.

Клещи надеваются на провод L стрелкой к нагрузке, а опорные клеммы сети — отдельно.

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

⚠ Безопасность сети. Сетевое напряжение может убить. Отключите и заблокируйте цепь перед подключением клемм L/N или установкой клещей; подключение к сети и любые работы внутри щитка поручайте квалифицированному специалисту. Охватывайте клещами один проводник (L) — никогда весь кабель (охват L и N даёт показание около 0). Сами клещи бесконтактные.

Шаг 3 — Первый скрипт (чтение RT)

Минимальный скрипт: сообщите модулю, какие клещи вы используете (один раз), затем читайте U / I / P / PF. Коды моделей перечислены в шаге 4; 3 ниже — это SCT-013-030. Таблица линеек и вариантов модуля — в 02 · Module lines.

Версия CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

with SMBus(1) as bus:
    with RbAmp(bus, 0x50) as dev:
        # the context manager's __enter__ automatically calls dev.begin()
        # the module variant is detected automatically
        variant = dev.read_variant()
        label = dev.read_label() or "(unset)"
        print(f"Module ready: variant={variant}  label={label!r}")
        # variant codes: see the table in 02 · Module lines
        # Once per installation (saved in the module's flash):
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)   # SCT-013-030, see Step 4
        while True:
            try:
                print(f"U={dev.voltage:.1f}V  "
                      f"I={dev.read_current(0):.3f}A  "
                      f"P={dev.read_power(0):.1f}W  "
                      f"PF={dev.read_power_factor(0):.3f}")
            except RbAmpError as e:
                print("read failed:", e)
            time.sleep(1)

Run:

Shell
python quick_read.py

MicroPython, версия

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)   # ESP32 default
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)   # once per installation
    dev.set_ct_model(3)                              # SCT-013-030, see Step 4
    print("Module ready.")
    while True:
        try:
            print("U={:.1f}V  I={:.3f}A  P={:.1f}W  PF={:.3f}".format(
                dev.voltage, dev.read_current(0),
                dev.read_power(0), dev.read_power_factor(0)))
        except RbAmpError as e:
            print("read failed:", e)
        time.sleep(1)

(На MicroPython используется .format() вместо f-строк — ради производительности и совместимости со старыми портами; на новых портах f-строки тоже работают.)

Run:

Shell
mpremote run quick_read.py

Ожидаемый вывод при включённой нагрузке (значения зависят от вашей нагрузки):

Text
Module ready.
U=230.4V  I=0.523A  P=119.8W  PF=0.987
Безопасность

U показывает примерно сетевое напряжение (220–240 В для сетей 230 В). Без нагрузки I около 0, а PF не определён (может выводить nan, 0 или заглушку) — точная форма не важна, пока ток нулевой. Если I остаётся 0.000 A при включённой нагрузке, проверьте клещи (один проводник, правильное направление) и код модели, затем см. 10 · Troubleshooting.

Шаг 4 — Настройка токового датчика

Вы обязаны сообщить модулю класс датчика и модель (делается в скрипте шага 3). Без этого коэффициенты калибровки не загружаются, и показания тока остаются нулевыми. Всегда сначала вызывайте set_sensor_class(), затем set_ct_model(code).

Выберите код, соответствующий вашим клещам:

code Модель Диапазон Типичное применение
1 SCT-013-005 0..5 A Малые нагрузки, одна розетка
2 SCT-013-010 0..10 A Холодильник, стиральная машина
3 SCT-013-030 0..30 A Бытовой ввод до ~7 кВт
4 SCT-013-050 0..50 A Зарядка электромобиля, электрическое отопление
6 SCT-013-020 0..20 A Средний фидер, приборы 3–4 кВт

Подробнее о выборе — 03 · Выбор токового датчика.

Примечание

Эти два вызова выполняются один раз при первой установке — выбор сохраняется во флеш модуля и переживает сброс. Общее время — около 1.4 секунды (две записи во флеш × ~700 мс каждая).

При последующих запусках скрипта не нужно вызывать set_sensor_class() и set_ct_model() (модуль их помнит). Повторный вызов со значением, которое модуль уже хранит, — no-op.

Шаг 5 — учёт энергии (Wh)

Модуль возвращает только мгновенные величины и среднюю мощность за период. Сами Wh вычисляет пакет по часам мастера (time.monotonic() на CPython, time.ticks_ms() на MicroPython):

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

где master_dt_s — секунды между двумя успешными вызовами dev.read_period_snapshot().

Примечание

Подождите один полный период до первого read_period_snapshot(). begin() уже запускает период, поэтому снимок, взятый сразу после него, покрывает доли секунды, и Wh будет ~0. Поэтому циклы ниже сначала спят 60 с.

Счётчик Wh хранится в памяти. Он начинается с 0 после перезапуска скрипта или перезагрузки. Для абсолютного итога сохраняйте dev.energy.wh(0) сами. На модулях BASIC экспорт не учитывается (см. 02 · Module lines). На модуле STD те же вызовы работают, и значение — чистая энергия (экспорт вычитается); begin() выбирает источник — счётчики энергии модуля или latch-банк 0, а первый период стартует в begin(). Собственные пожизненные итоги модуля — в read_std_energy() (Сценарий 11 в 06 · Examples).

Минимальный шаблон периодического учёта (раз в минуту):

CPython, версия (счётчик периода)

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)   # SCT-013-030

    while True:
        time.sleep(60)   # 60-second period

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print(f"avg P over period: {snap.avg_p[0]:.2f} W   "
              f"accumulated: {dev.energy.wh(0):.4f} Wh   "
              f"dt={snap.master_dt_ms} ms")

Версия MicroPython (измеритель периода)

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)

    while True:
        time.sleep_ms(60_000)

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print("avg P over period: {:.2f} W   accumulated: {:.4f} Wh   dt={} ms".format(
            snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Примечание

После Шага 4 вызовы set_sensor_class() и set_ct_model() уже выполнены один раз и сохранены во флеш модуля; в шаблоне выше они нужны для повторных запусков скрипта — модуль игнорирует повторный вызов с тем же значением.

Что делает read_period_snapshot() внутри:

  1. Отправляет модулю команду снимка периода (CMD_LATCH_PERIOD).
  2. Ждёт 50 мс, пока модуль готовит снимок.
  3. Проверяет флаг готовности (snap.valid); читает среднюю и пиковую мощность.

  4. Обновляет внутренний счётчик Wh: dev.energy.wh(ch) += avg_p[ch] × dt / 3600.

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

dev.begin() сам запускает первый период (прайм) и отбрасывает то, что модуль накопил с момента включения, так что пользовательский код никогда не видит эти данные.

Ожидаемый вывод:

Text
avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Асинхронный потоковый вариант (необязательно)

Для приложений на asyncio (CPython) или uasyncio (MicroPython) есть асинхронный генератор dev.stream_period(interval_s=...):

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)

        # Once a minute, with built-in stale handling (skip_stale=True)
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"{snap.avg_p[0]:.2f} W,  {dev.energy.wh(0):.4f} Wh")

asyncio.run(main())

На MicroPython работает так же (import uasyncio as asyncio).

Подробнее об асинхронных сценариях — 06 · Examples, сценарий «Async period streaming».

Шаг 6 — быстрый старт для флота из N модулей

Этот quickstart показывает работу с одним модулем. Реальный канонический сценарий пакета — несколько модулей на одной шине через RbAmpFleet (сеть + N поднагрузок). Полный пример — в главе 06 · Examples, сценарий 1 «Mains + N sub-loads — the 80% canon». Минимальный скелет флота (CPython):

Python
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    added = fleet.scan()
    print(f"fleet: {added} modules; excluded: {fleet.excluded}")

    while True:
        snaps = fleet.poll_all()
        total_w = fleet.total_power()
        n_ok = sum(1 for snap, info in snaps if info.ok)
        print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
        time.sleep(0.2)

Версия для MicroPython идентична — замените SMBus(1) на I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).

В каноническом сценарии 80% один из модулей — UI1 на вводе сети (он даёт total_power() и total_energy_wh()), а остальные, I2/I3, — токовые субсчётчики. Подробности и расширенные сценарии (разложение «сеть + субнагрузки», синхронизация GC для жёстко согласованных снимков, процесс подготовки) — в главе 06.

Что дальше

  • 01 · Overview — что такое rbAmp и что делает пакет
  • 02 · Линейки модулей — какая линейка для какой задачи
  • 06 · Примеры — рабочие сценарии: сеть + N подключённых нагрузок (канон 80%), процесс подготовки, смешанный CT по нескольким каналам, синхронизация GC флота, MQTT, глубокий сон, асинхронная потоковая передача

  • 07 · DIY integrations — Home Assistant / Node-RED / OpenHAB

  • 08 · Облачные интеграции — AWS IoT / Azure / GCP / InfluxDB

  • 09 · Справочник API — полный публичный API (включая RbAmpFleet, несколько каналов, модель ошибок v1.3 и идентификацию с подготовкой)

  • 10 · Troubleshooting — если что-то не работает (MicroPython@ESP32 i2c-hang — трёхуровневая схема, latch_ms — диагностический таймер, RbAmpStaleError master-hold-anchor)


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