05 · Быстрый старт
Пятиминутный hello-world: добавьте компонент в проект IDF, подключите модуль, выберите датчик, получите первое показание RT и первый снимок энергии за период (Wh).
Подробности (распиновка для конкретного чипа ESP32, шина нескольких модулей, выбор SCT-013 по диапазону) — в соседних главах:
-
04 · Проводка — детали аппаратуры и GPIO по умолчанию для каждого поддерживаемого чипа ESP32
-
03 · Выбор датчика тока — какую модель SCT-013 использовать и почему
Что понадобится
- Модуль rbAmp (любая линия модулей; для простоты — UI1: один вход напряжения плюс один токовый канал; другие варианты перечислены в 03)
-
Любой чип семейства ESP32 (
esp32,esp32s2,esp32s3,esp32c2,esp32c3,esp32c6,esp32h2) -
Установлен ESP-IDF v5.2+ (
. ~/esp/esp-idf/export.shили%IDF_PATH%\export.batв Windows) -
Клещи CT SCT-013 с номиналом, рассчитанным на ваш максимальный ток (5А / 10А / 30А / 50А / 100А)
- Питание 5 В для модуля (от USB-5V DevKitC или внешнего источника)
- Измеряемая цепь переменного тока (лампа, чайник, бытовой прибор)
Шаг 0 — Задайте цель
Если это новый проект ESP-IDF и idf.py set-target ещё не запускался, выполните его до первого idf.py build — иначе сборка завершится с ошибкой «no target specified»:
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Без этого шага сборка завершится с ошибкой.
Шаг 1 — Добавьте компонент в проект
Как git-зависимость (рекомендуется)
В файле main/idf_component.yml вашего проекта (создайте файл, если его нет). ESP-IDF Component Manager загрузит помеченный релиз:
dependencies:
rbamp:
git: https://github.com/rb-amp/rbamp-esp-idf.git
version: v1.7.3
Компонент загружается при следующей команде idf.py build (или idf.py reconfigure).
Вручную (git submodule / clone)
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp
Или добавьте путь к компоненту в CMakeLists.txt корня проекта:
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
Зависимость в main/
# main/CMakeLists.txt
idf_component_register(
SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES rbamp
)
Компонент подтягивает esp_driver_i2c, esp_timer и log — этого достаточно для базового сценария Шага 3. Сценариям с сетью / SPIFFS / OLED нужны дополнительные REQUIRES — см. 06 · Примеры, таблицу CMakeLists в начале главы.
Шаг 2 — Подключение
Четыре провода плюс необязательный DRDY:
| Вывод rbAmp | ESP32 (по умолчанию) | ESP32-S3 (по умолчанию) | ESP32-C3 (по умолчанию) |
|---|---|---|---|
VCC |
+5 В (4.5–5.5 В) | то же | то же |
GND |
GND | GND | GND |
SDA |
GPIO21 | GPIO8 | GPIO5 |
SCL |
GPIO22 | GPIO9 | GPIO6 |
Питание должно быть 5 В. Линии I²C работают на логике 3.3 В — напрямую совместимы с GPIO ESP32. На плате модуля уже есть встроенные подтягивающие резисторы 4.7 кОм — для одного модуля внешние не нужны.
Полная таблица распиновки для каждого чипа ESP32 — в 04 · Подключение.
⚠ Напряжение сети опасно для жизни. Отключите и заблокируйте цепь перед подключением клемм L/N или установкой клипсы; подключение к сети и любые работы внутри щитка поручайте квалифицированному специалисту. Клипсой охватывайте ТОЛЬКО один проводник (L) — никогда весь кабель. Защитите отвод L предохранителем по местным правилам.
Клипса SCT-013 охватывает фазовый проводник (L), стрелка на корпусе клипсы указывает в направлении тока к нагрузке. Модулю UI также нужно подключение напряжения L/N; клипса CT втыкается в 3.5-мм гнездо CT модуля (обозначено I0, I1, … на плате); на стороне сети есть клеммы L и N. См. 04 · Подключение, «Сеть и подключение CT».
Шаг 3 — Первый проект (первое показание)
Минимальный main/main.c: поднимает шину, сообщает модулю, какую клипсу CT вы установили, и раз в секунду печатает U / I / P / PF.
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "app";
void app_main(void) {
const i2c_master_bus_config_t bus_cfg = {
.i2c_port = I2C_NUM_0,
.sda_io_num = GPIO_NUM_21, /* ESP32 — adjust for your chip */
.scl_io_num = GPIO_NUM_22,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = true, /* optional with the module's own pull-ups */
};
i2c_master_bus_handle_t bus;
ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));
rbamp_handle_t dev = NULL;
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev)); /* default address 0x50 */
/* rbamp_begin blocks while it tries to reach the slave;
* it runs a primer-snapshot and a valid-check, ~250 ms. */
while (rbamp_begin(dev) != ESP_OK) {
ESP_LOGE(TAG, "rbAmp not responding — check wiring and power");
vTaskDelay(pdMS_TO_TICKS(1000));
}
ESP_LOGI(TAG, "Module ready.");
/* Sensor configuration (see Step 4): class first, then model.
* Code 3 = SCT-013-030; use the code of the clamp you fitted. */
if (rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) != ESP_OK ||
rbamp_set_ct_model(dev, 3) != ESP_OK) {
ESP_LOGE(TAG, "sensor configuration failed");
return;
}
ESP_LOGI(TAG, "Sensor configured.");
while (1) {
float u = NAN, i = NAN, p = NAN, pf = NAN;
if (rbamp_read_voltage(dev, 0, &u) != ESP_OK) u = NAN;
if (rbamp_read_current(dev, 0, &i) != ESP_OK) i = NAN;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) p = NAN;
if (rbamp_read_power_factor(dev, 0, &pf) != ESP_OK) pf = NAN;
ESP_LOGI(TAG, "U=%.1f V I=%.3f A P=%.1f W PF=%.3f",
(double)u, (double)i, (double)p, (double)pf);
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Соберите, прошейте и откройте монитор:
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
(В Windows — idf.py -p COM3 ....)
Ожидаемый вывод при включённой нагрузке (значения зависят от вашей нагрузки):
I (1234) app: Module ready.
I (2634) app: Sensor configured.
I (3634) app: U=230.4 V I=0.523 A P=119.8 W PF=0.987
U показывает примерно напряжение сети (220–240 В для сетей 230 В) — значит модуль подключён правильно.
Если I остаётся на 0.000 A при включённой нагрузке: модуль не знает, какие клещи CT подключены (шаг настройки датчика пропущен или завершился с ошибкой) — без этого показания тока остаются нулевыми. PF не определён при I=0 и может показывать nan, 0 или заглушку; игнорируйте его, пока ток не ненулевой. См. 10 · Устранение неполадок, «Ток показывает ноль при работающей нагрузке».
Шаг 4 — Что делает настройка датчика
Два вызова на шаге 3 сообщают модулю класс и модель датчика. Без них коэффициенты калибровки не загружаются, и текущие показания остаются нулевыми. Порядок важен: сначала класс, затем модель.
/* Step A: sensor class. The current rbAmp SKU uses SCT-013 clamps. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
/* Step B: model. For example, SCT-013-030 for a household feed up to ~7 kW. */
rbamp_set_ct_model(dev, 3);
Коды моделей:
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 | Водонагреватель, бойлер, крупная бытовая техника |
| 7 | SCT-013-060 | 0..60 A | Промышленный субсчётчик |
Подробнее о выборе (включая другие поддерживаемые коды) — 03 · Выбор датчика тока.
Эти два вызова выполняются один раз при первой установке — выбор сохраняется во flash модуля и переживает сброс. Общее время — около 1.4 секунды (две записи во flash × ~700 мс каждая).
При следующих запусках прошивки можно пропустить rbamp_set_sensor_class() и rbamp_set_ct_model() (модуль помнит). Но вреда не будет — повторный вызов с тем же значением ничего не записывает.
Шаг 5 — учёт энергии (Wh)
Модуль возвращает только мгновенные величины и среднюю мощность за период. Сами Wh вычисляет компонент по esp_timer_get_time():
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
где master_dt_s — число секунд между двумя успешными вызовами rbamp_read_period_snapshot(). Компонент хранит временную метку последнего снимка в дескрипторе и сам вычисляет разность.
Минимальный шаблон для периодического учёта (раз в минуту):
void app_main(void) {
/* ...bus + rbamp_new + rbamp_begin + set_sensor_class + set_ct_model (Step 3)... */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000)); /* 60-second period */
rbamp_period_snapshot_t snap;
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK || !snap.valid) {
ESP_LOGW(TAG, "snapshot error: %s", rbamp_err_to_str(err));
continue;
}
ESP_LOGI(TAG, "avg P over period: %.2f W accumulated: %.4f Wh dt=%u ms",
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
}
}
После Шага 3 вызовы rbamp_set_sensor_class() и rbamp_set_ct_model() уже выполнены один раз и сохранены во флеш модуля; в шаблоне выше они оставлены для повторного запуска прошивки — модуль игнорирует повторный вызов с тем же значением. Обработка ошибок частично опущена для краткости — добавьте проверки if (err != ESP_OK), если хотите ловить редкие сбои связи при старте.
Что делает rbamp_read_period_snapshot() внутри (при skip_latch=false):
- Отправляет модулю команду снимка периода (
CMD_LATCH_PERIOD). - Ждёт
settle_ms(по умолчанию 50 мс), пока модуль готовит снимок. - Проверяет флаг готовности; читает среднюю/пиковую мощность.
- Обновляет внутренний счётчик Wh:
+= avg_p × master_dt_s / 3600(если компонент собран безCONFIG_RBAMP_DISABLE_ENERGY).
rbamp_energy_wh() начинается с 0 после каждого сброса или потери питания ESP32; если нужно, чтобы значение переживало это, сохраняйте его сами (см. 06 · Примеры, Сценарий 13).
Первый вызов после rbamp_begin() — это затравка: модуль возвращает всё, что накопилось с момента включения питания (интервал, непригодный для тарифного учёта). Компонент сам знает, что этот снимок нужно отбросить — пользовательский код его никогда не видит.
Ожидаемый вывод:
I (61234) app: avg P over period: 120.18 W accumulated: 2.0036 Wh dt=60012 ms
I (121234) app: avg P over period: 120.21 W accumulated: 4.0073 Wh dt=60005 ms
...
Шаг 6 — быстрый старт для флота из N модулей
Этот быстрый старт показывает работу с одним модулем. Настоящий каноничный сценарий библиотеки — несколько модулей на одной шине под одним дескриптором флота (сеть + N поднагрузок). Полный пример — в 06 · Примеры, сценарий 1. > Предварительные условия для флота. Все модули поставляются с адресом 0x50, и
rbamp_fleet_scan исключает модули с одинаковым адресом. Сначала дайте каждому модулю собственный адрес, по одному модулю на шине за раз (06 · Примеры, Сценарий 2, rbamp_provision), и задайте класс датчика и модель CT на каждом модуле (03). Иначе парк окажется пустым или с исключениями, а токи будут читаться как 0. Мощность и Wh требуют варианта UI: баланс «сеть минус сумма нагрузок» требует модуль UI на каждой нагрузке.
Минимальный каркас парка:
#include "rbamp_fleet.h"
void app_main(void) {
/* ... bus init as in Step 3 ... */
rbamp_fleet_t fleet;
ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));
size_t added = 0;
esp_err_t scan = rbamp_fleet_scan(fleet, /*match_product=*/true, &added);
if (scan == ESP_ERR_INVALID_STATE) {
ESP_LOGE("app", "bus wedged — see ch.10 \"Fleet: INVALID_STATE\"");
return;
}
ESP_LOGI("app", "fleet: %u modules; excluded: %u",
(unsigned)added,
(unsigned)rbamp_fleet_excluded_count(fleet));
rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];
while (1) {
size_t n_ok = 0;
rbamp_fleet_poll_all(fleet, snaps, status,
RBAMP_FLEET_MAX_MODULES, &n_ok);
float p_total;
rbamp_fleet_total_power(fleet, &p_total);
ESP_LOGI("app", "fleet: %u/%u modules OK, total P = %.1f W",
(unsigned)n_ok, (unsigned)rbamp_fleet_count(fleet), p_total);
vTaskDelay(pdMS_TO_TICKS(200));
}
}
В каноничном сценарии 80% один из модулей — UI1 на вводе сети (он даёт total_power и total_energy_wh), а остальные — I2/I3 — токовые субсчётчики (только ток, без мощности и Wh; где нужны мощность или энергия по нагрузке, используйте модули UI). Подробности и продвинутые сценарии (разложение сеть + поднагрузки, синхронизация GC для точных снимков, процесс провизионинга) — в главе 06.
Что дальше
- 01 · Обзор — что такое rbAmp и что делает компонент
- 02 · Линейки модулей — какая линейка для какой задачи
-
06 · Примеры — рабочие сценарии: сеть + N поднагрузок (канон 80%), процесс провизионинга, смешанный CT по нескольким каналам, синхронизация GC флота, MQTT, глубокий сон
-
07 · Интеграции DIY — Home Assistant / Node-RED / OpenHAB
-
08 · Облачные интеграции — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Справочник API — полный публичный API (включая менеджер парка, конфигурацию парка по устройствам, конфигурацию нескольких каналов, модель ошибок v1.3, идентификацию и подготовку)
-
10 · Устранение неполадок — если что-то не работает (трёхуровневая защита от зависания i2c, режимы отказа при конфликте флота / зависании шины / сбое провизионинга)
Исходники и задачи: rb-amp/rbamp-esp-idf · эта страница в репозитории: docs/05_quickstart.md (v1.7.3)