rbAmp
RU
Магазин
Документация
Обновлено · Изменить на GitHub

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

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

Подробности (распиновка для конкретного чипа ESP32, шина нескольких модулей, выбор 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»:

Shell
idf.py set-target esp32      # or esp32s3 / esp32c3 / esp32c6 / ...

Без этого шага сборка завершится с ошибкой.

Шаг 1 — Добавьте компонент в проект

В файле main/idf_component.yml вашего проекта (создайте файл, если его нет). ESP-IDF Component Manager загрузит помеченный релиз:

YAML
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)

Shell
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp

Или добавьте путь к компоненту в CMakeLists.txt корня проекта:

CMake
list(APPEND EXTRA_COMPONENT_DIRS
     ${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`

Зависимость в main/

CMake
# 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.

C
#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));
    }
}

Соберите, прошейте и откройте монитор:

Shell
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

(В Windows — idf.py -p COM3 ....)

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

Text
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 сообщают модулю класс и модель датчика. Без них коэффициенты калибровки не загружаются, и текущие показания остаются нулевыми. Порядок важен: сначала класс, затем модель.

C
/* 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():

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

где master_dt_s — число секунд между двумя успешными вызовами rbamp_read_period_snapshot(). Компонент хранит временную метку последнего снимка в дескрипторе и сам вычисляет разность.

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

C
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):

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

rbamp_energy_wh() начинается с 0 после каждого сброса или потери питания ESP32; если нужно, чтобы значение переживало это, сохраняйте его сами (см. 06 · Примеры, Сценарий 13).

Первый вызов после rbamp_begin() — это затравка: модуль возвращает всё, что накопилось с момента включения питания (интервал, непригодный для тарифного учёта). Компонент сам знает, что этот снимок нужно отбросить — пользовательский код его никогда не видит.

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

Text
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 на каждой нагрузке.

Минимальный каркас парка:

C
#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)