05 · Быстрый старт
Пятиминутное «привет, мир»: установите пакет, подключите модуль, выберите датчик и считайте первое значение RT и первый снимок периода (Wh). Руководство охватывает обе среды выполнения параллельно — MicroPython (на ESP32 / RP2040 / STM32 / Pyboard) и CPython (на Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).
Подробности (распиновка для конкретного хоста, многомодульная шина, выбор SCT-013 по диапазону) — в соседних главах:
-
04 · Wiring — детали железа и таблицы выводов по хостам
-
03 · Выбор токового датчика — какую модель 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)
pip install rbamp
(В Debian/Ubuntu можно использовать системный аналог smbus2: sudo apt install python3-smbus, но рекомендуется smbus2 из pip — он поддерживает менеджер контекста with SMBus(...).)
Verify:
rbamp --version # rbamp 1.6.0
rbamp --bus 1 scan # I²C scan, should show 0x50
MicroPython (на ESP32 и других)
mpremote mip install github:rb-amp/rbamp-python
Или скопируйте пакет вручную:
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/N или установкой клещей; подключение к сети и любые работы внутри щитка поручайте квалифицированному специалисту. Охватывайте клещами один проводник (L) — никогда весь кабель (охват L и N даёт показание около 0). Сами клещи бесконтактные.
Шаг 3 — Первый скрипт (чтение RT)
Минимальный скрипт: сообщите модулю, какие клещи вы используете (один раз), затем читайте U / I / P / PF. Коды моделей перечислены в шаге 4; 3 ниже — это SCT-013-030. Таблица линеек и вариантов модуля — в 02 · Module lines.
Версия CPython
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:
python quick_read.py
MicroPython, версия
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:
mpremote run quick_read.py
Ожидаемый вывод при включённой нагрузке (значения зависят от вашей нагрузки):
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):
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, версия (счётчик периода)
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 (измеритель периода)
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() внутри:
- Отправляет модулю команду снимка периода (
CMD_LATCH_PERIOD). - Ждёт 50 мс, пока модуль готовит снимок.
-
Проверяет флаг готовности (
snap.valid); читает среднюю и пиковую мощность. -
Обновляет внутренний счётчик Wh:
dev.energy.wh(ch) += avg_p[ch] × dt / 3600. - При устаревшем снимке возбуждает
RbAmpStaleErrorи сохраняет предыдущую метку времени, чтобы следующий успешный снимок покрыл весь интервал и Wh оставался точным.
dev.begin() сам запускает первый период (прайм) и отбрасывает то, что модуль накопил с момента включения, так что пользовательский код никогда не видит эти данные.
Ожидаемый вывод:
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=...):
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):
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)