rbAmp
RU
Магазин
Документация

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

Пятиминутный «hello world»: установите библиотеку, подключите модуль, выберите датчик, снимите первое показание RT и первый снимок периода (Wh).

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

Первое чтение в восемь шагов: проводка, питание, поиск 0x50, begin(), необязательная настройка датчика, чтение U, I, P, PF, проверка корректности, затем энергия.

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

  • Модуль rbAmp (любой класс, для простоты UI1)
  • Хост, совместимый с Arduino — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • Клещ SCT-013 с номиналом выше вашего максимального ожидаемого тока (5 А / 10 А / 30 А / 50 А / 100 А) — или ТТ, поставляемый с вашим модулем
  • Питание модуля 5 В (от USB-5V хоста или внешнего источника)
  • Измеряемая цепь переменного тока (лампа, чайник, бытовой прибор)

Шаг 1 — Установка библиотеки

Arduino IDE — менеджер библиотек (Library Manager)

Sketch → Include Library → Manage Libraries… → поиск RbAmp → Install [Sketch → Include Library → Manage Libraries… (Менеджер библиотек); Install (Установить)]. Зависимостей нет. После установки примеры появятся в File → Examples → RbAmp [File → Examples → RbAmp].

Arduino CLI

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

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

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

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

Четыре низковольтных провода плюс опциональный DRDY, затем клеммы сети:

Вывод rbAmp Мастер
VCC +5 В (диапазон 4.5..5.5 В)
GND GND
SDA SDA I²C (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (необязательно) пропустите его для первого скетча; см. 04_hardware.md
Клеммы L, N та же цепь, которая питает измеряемую нагрузку (сторона сети — см. предупреждение выше)
Гнездо CT Вилка SCT-013 вставлена до упора

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

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

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

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

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

Минимальный скетч — проверка связи без настройки датчика:

C++
#include 
#include 

RbAmp dev(Wire, 0x50);  // default address 0x50

void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }

    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz — required for retry discipline
#endif

    while (!dev.begin()) {
        Serial.print(F("rbAmp begin failed: "));
        Serial.println(dev.errorString());
        delay(1000);
    }

    // v1.3: auto-detect the variant via REG_HW_VARIANT — more accurate than
    // the constructor topology hint (which is now a fallback for legacy fw).
    uint8_t variant = static_cast(dev.readVariant());
    Serial.print(F("Module ready, variant="));
    Serial.println(variant);   // 1=UI1, 4=I1, 5=I2, 6=I3
}

void loop() {
    Serial.print(F("U=")); Serial.print(dev.readVoltage(), 1);
    Serial.print(F("V  I=")); Serial.print(dev.readCurrent(0), 3);
    Serial.print(F("A  P=")); Serial.print(dev.readPower(0), 1);
    Serial.print(F("W  PF=")); Serial.println(dev.readPowerFactor(0), 3);
    delay(1000);
}

Загрузите скетч и откройте Serial Monitor на 115200 бод [Монитор порта (Serial Monitor)].

Ожидаемый вывод (без калибровки датчика):

Text
Module ready, variant=1
U=230.4V  I=0.000A  P=0.0W  PF=nan
U=230.4V  I=0.000A  P=0.0W  PF=nan

PF может показывать nan, 0.000 или другой заполнитель, пока ток равен нулю.

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

U показывает примерно сетевое напряжение (220–240 В в сетях 230 В) — значит, модуль подключён верно. I=0.000 A даже при включённой нагрузке на этом этапе нормально: модуль пока не знает, какой токовый клещ используется. При I=0 величина PF математически не определена (это зависит от прошивки — может быть NaN, 0 или заглушка) — точный вид значения не важен, пока ток равен нулю. Следующий шаг это исправит.

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

Если вы установили отдельный клипсовый токовый клещ SCT-013, вы обязаны сообщить модулю класс и модель датчика. Без этого коэффициенты калибровки не загружаются, и показания тока остаются нулевыми. Если модуль поставлен уже с подключённым ТТ, пропустите этот шаг.

Считайте модель с этикетки на клещах (например, SCT-013-030 → код 3, см. таблицу ниже). Выбирайте наименьший клещ с номиналом выше вашего максимального ожидаемого тока. Клещ с слишком малым номиналом даёт обрезанные, занижённые показания на пиках; слишком большой — шумные, неточные показания на малых токах.

Добавьте это в setup() после dev.begin(). Функция loop() остаётся такой же, как на Шаге 3 — меняется только setup():

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif

    while (!dev.begin()) { delay(500); }

    // Step 1: sensor class. SCT-013 = the clip-on clamp you fitted.
    if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
        Serial.print(F("setSensorClass failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    // Step 2: model. For example, SCT-013-030 for a household feed up to ~7 kW.
    if (!dev.setCTModel(RbAmpCTModel::Sct013_030)) {
        Serial.print(F("setCTModel failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    Serial.println(F("Ready."));
}

Коды моделей — допустимый набор {1, 2, 3, 4, 5, 6, 7}:

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 ✅ выбирается Зарядка электромобиля, электрическое отопление
5 SCT-013-100 0..100 A ✅ выбирается Главный ввод в здание, мощные фидеры
6 SCT-013-020 0..20 A ✅ выбирается Средний ввод — бытовые приборы 3–4 кВт
7 SCT-013-060 0..60 A ✅ выбирается Промышленный субсчётчик

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

Примечание

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

При последующих запусках скетча можно пропускать setSensorClass() и setCTModel() (модуль помнит). Но и повторный вызов не вредит — повторный вызов с тем же значением перезаписывает тот же байт.

После перезапуска скетча должно появиться правильное значение тока:

Text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

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

Модуль возвращает только мгновенные величины и среднюю мощность за период. Wh вычисляет сама библиотека по часам мастера:

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

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

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

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif
    while (!dev.begin()) { delay(500); }
    dev.setSensorClass(RbAmpSensorClass::Sct013);
    dev.setCTModel(RbAmpCTModel::Sct013_030);
    Serial.println(F("Period meter started; the first line covers only the time since begin() — ignore it..."));
}

void loop() {
    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) {
        Serial.print(F("snapshot error: "));
        Serial.println(dev.errorString());
        delay(60000);
        return;
    }

    Serial.print(F("avg P for period: ")); Serial.print(snap.avg_p[0], 2);
    Serial.print(F(" W   accumulated: ")); Serial.print(dev.energy().wh(0), 4);
    Serial.print(F(" Wh   dt=")); Serial.print(snap.master_dt_ms);
    Serial.println(F(" ms"));

    delay(60000);  // the 60-second period sits at the END of loop — the first
                   // snapshot is taken right after setup() and covers only the
                   // seconds since begin(); full periods follow
}
Примечание

После Шага 4 setSensorClass() и setCTModel() уже выполнены один раз и сохранены во флеш модуля; в шаблоне выше они нужны для повторных запусков скетча — модуль игнорирует повторный вызов с тем же значением. Обработка ошибок для краткости опущена — добавьте проверки if (!...), если хотите ловить редкие сбои связи при старте.

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

  1. Отправляет модулю команду снимка периода.
  2. Ждёт 50 мс, пока модуль готовит снимок.
  3. Проверяет флаг готовности; читает среднюю/пиковую мощность.
  4. Обновляет внутренний счётчик Wh: += avg_p × master_dt_s / 3600.

begin() уже выполняет первый снимок, который библиотека отбрасывает. Первый readPeriodSnapshot() в вашем скетче поэтому покрывает только время с begin() (несколько секунд, см. dt= в выводе): игнорируйте первую строку и дождитесь полного периода. Со второго вызова каждая строка покрывает один полный период.

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

Text
avg P for period: 119.90 W   accumulated: 0.1332 Wh   dt=4000 ms    <- short first period, ignore
avg P for period: 120.18 W   accumulated: 2.1368 Wh   dt=60012 ms
avg P for period: 120.21 W   accumulated: 4.1405 Wh   dt=60005 ms
...

Несколько модулей

Для нескольких модулей на одной шине (ввод сети + субнагрузки) используйте RbAmpFleet. Полный пример — в 06 · Примеры, сценарий 1; правила подключения многомодульной шины — в 04 · Подключение.

Что дальше

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

  • 07 · DIY-интеграции — Home Assistant / Node-RED / OpenHAB

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

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

  • 10 · Устранение неполадок — когда что-то не работает (трёхуровневое смягчение i2c-hang, конфликт флота / зависание шины / режимы сбоя настройки)


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