05 · Быстрый старт
Пятиминутный «hello world»: установите библиотеку, подключите модуль, выберите датчик, снимите первое показание RT и первый снимок периода (Wh).
Подробности (распиновка для конкретного хоста, шина с несколькими модулями, выбор SCT-013 по диапазону) изложены в соседних главах:
-
04 · Проводка — детали аппаратной части и разделы по MCU каждого хоста
-
03 · Выбор токового датчика — какую модель SCT-013 выбрать и почему
Что понадобится
- Модуль 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
arduino-cli lib install RbAmp
PlatformIO
[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 · Подключение.
Шаг 3 — Первый скетч (чтение RT)
Минимальный скетч — проверка связи без настройки датчика:
#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)].
Ожидаемый вывод (без калибровки датчика):
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():
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() (модуль помнит). Но и повторный вызов не вредит — повторный вызов с тем же значением перезаписывает тот же байт.
После перезапуска скетча должно появиться правильное значение тока:
Ready.
U=230.4V I=0.523A P=119.8W PF=+0.987
Шаг 5 — Учёт энергии (Wh)
Модуль возвращает только мгновенные величины и среднюю мощность за период. Wh вычисляет сама библиотека по часам мастера:
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
где master_dt_s — число секунд между двумя успешными вызовами readPeriodSnapshot().
Минимальный шаблон периодического учёта (раз в минуту):
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() внутри:
- Отправляет модулю команду снимка периода.
- Ждёт 50 мс, пока модуль готовит снимок.
- Проверяет флаг готовности; читает среднюю/пиковую мощность.
- Обновляет внутренний счётчик Wh:
+= avg_p × master_dt_s / 3600.
begin() уже выполняет первый снимок, который библиотека отбрасывает. Первый readPeriodSnapshot() в вашем скетче поэтому покрывает только время с begin() (несколько секунд, см. dt= в выводе): игнорируйте первую строку и дождитесь полного периода. Со второго вызова каждая строка покрывает один полный период.
Ожидаемый вывод:
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)