rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub (Edit on GitHub)

Примеры

Разбор примеров examples/ и составных сценариев. Большинство пронумерованных примеров ниже имеют код в examples/ — откройте настоящие скетчи в Arduino IDE для полного исходного кода.


Сценарий 1 — Быстрое чтение

Цель: печатать U / I / P / PF / частоту раз в секунду. «Hello world», который вы только что написали в Быстром старте, но с dev.readAll(s) для разового полного блочного чтения RT вместо отдельных вызовов свойств.

C++
#include 
#include 

static RbAmp dev(Wire, 0x50);

void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) {}
    Wire.begin();
    dev.setLogStream(&Serial);
    while (!dev.begin()) {
        Serial.print(F("begin: ")); Serial.println(RbAmp::errorString(dev.lastError()));
        delay(1000);
    }
}

void loop() {
    RbAmpSnapshot s;
    if (!dev.readAll(s)) {
        Serial.print(F("read fail: ")); Serial.println(RbAmp::errorString(dev.lastError()));
        delay(1000); return;
    }
    Serial.print(F("U=")); Serial.print(s.voltage, 1); Serial.print(F("V "));
    Serial.print(F("f=")); Serial.print(s.frequency, 1); Serial.print(F("Hz   "));
    for (uint8_t ch = 0; ch < s.channels; ++ch) {
        Serial.print(F("I")); Serial.print(ch); Serial.print(F("="));
        Serial.print(s.current[ch], 2); Serial.print(F("A "));
        Serial.print(F("P")); Serial.print(ch); Serial.print(F("="));
        Serial.print(s.power[ch], 1); Serial.print(F("W "));
        Serial.print(F("PF")); Serial.print(ch); Serial.print(F("="));
        Serial.print(s.power_factor[ch], 2); Serial.print(F("  "));
    }
    Serial.println();
    delay(1000);
}

Что уходит в шину: readAll() на UI3 выдаёт 53 однобайтовые транзакции (13 float × 4 байта + 1 байт частоты). При 100 кГц с запасом на 3 повтора — ~12–15 мс суммарно. Переходите к чтениям по отдельности (dev.voltage, dev.current[ch]), если нужна только часть.


Сценарий 2 — счётчик на 60 секунд на OLED

Счётчик Wh обновляется раз в минуту на OLED SSD1306 128×64, который делит шину I2C (OLED по адресу 0x3C). Ключевой механизм библиотеки: readPeriodSnapshot() выполняет снимок, установление, проверку валидности, чтение и тик Wh одним вызовом.

C++
#include 
#include 
#include 
#include 

static Adafruit_SSD1306 oled(128, 64, &Wire, -1);
static RbAmp dev(Wire, 0x50);
static uint32_t next_latch_ms = 0;
static uint32_t snapshots_ok = 0, snapshots_bad = 0;

void setup() {
    Serial.begin(115200);
    Wire.begin();
    oled.begin(SSD1306_SWITCHCAPVCC, 0x3C);
    dev.setLogStream(&Serial);
    while (!dev.begin()) { delay(1000); }
    next_latch_ms = millis() + 60000;
}

void loop() {
    if (millis() < next_latch_ms) { delay(50); return; }
    next_latch_ms = millis() + 60000;

    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) { snapshots_bad++; return; }
    snapshots_ok++;

    oled.clearDisplay();
    oled.setTextColor(SSD1306_WHITE);
    oled.setCursor(0, 0);  oled.setTextSize(1); oled.println(F("rbAmp Energy Meter"));
    oled.setCursor(0, 16); oled.setTextSize(2); oled.print(snap.avg_p[0], 1); oled.println(F(" W"));
    oled.setTextSize(1);
    oled.print(F("Wh:")); oled.println(dev.energy().wh(0), 4);
    oled.print(F("ok=")); oled.print(snapshots_ok);
    oled.print(F(" bad=")); oled.println(snapshots_bad);
    oled.display();
}

Полный скетч в 02_PeriodEnergyOLED.ino.

Обработка устаревшего снимка: readPeriodSnapshot() возвращает false с lastError() == RB_ERR_STALE, если REG_V03_PERIOD_VALID == 0. Библиотека всё равно фиксирует внутренне временную метку часов мастера — это не даёт следующему успешному снимку задвоить Wh за интервал 2× периода.


Сценарий 3 — Монитор нескольких модулей

Три модуля rbAmp на одной шине по адресам 0x50 / 0x51 / 0x52. Каждый должен иметь уникальный адрес I2C — для назначения адресов при установке используйте сценарий 10.

v1.3 согласованный снимок

каждый модуль, поддерживающий снимок General-Call и включивший его (enableGc(true), сохраняется), захватывает тот же период сети одним кадром all-call — RbAmp::broadcastLatchGroup(Wire, 0x00, tick). Разброс по флоту < 10 мкс, поэтому мощности модулей суммируются согласованно. Каждый модуль помечает свой снимок широковещательным tick; прочитайте его обратно через readGcTick(), чтобы поймать модуль, пропустивший кадр. (На прошивках v1.0/v1.1 снимок General-Call был недоступен, и этот скетч переходил к поочерёдным снимкам по устройствам — оставлено в комментарии истории файла для старых модулей.)

C++
#include 
#include 

static RbAmp T0(Wire, 0x50);
static RbAmp T1(Wire, 0x51);
static RbAmp T2(Wire, 0x52);
static RbAmp* modules[] = { &T0, &T1, &T2 };
static const uint8_t N = sizeof(modules) / sizeof(modules[0]);
static uint16_t g_tick = 0;

void setup() {
    Serial.begin(115200);
    Wire.begin();
    Wire.setClock(50000);   // 50 kHz on ESP32 / 100 kHz on non-ESP32 masters
    for (uint8_t i = 0; i < N; ++i) {
        modules[i]->begin();
        modules[i]->enableGc(true);   // opt into General-Call snapshot (persisted)
    }
}

void loop() {
    g_tick++;
    RbAmp::broadcastLatchGroup(Wire, /*group=*/0x00, g_tick);  // 0x00 = all-call
    delay(50);   // single shared settle for the whole bus

    for (uint8_t i = 0; i < N; ++i) {
        RbAmpPeriodSnapshot snap;
        if (modules[i]->readPeriodSnapshot(snap, /*settle_ms=*/0, /*skip_latch=*/true)) {
            uint16_t tick;
            bool synced = modules[i]->readGcTick(tick) && tick == g_tick;
            Serial.print(F("T")); Serial.print(i);
            Serial.print(F(" P=")); Serial.print(snap.avg_p[0], 0);
            Serial.print(F("W  Wh=")); Serial.print(modules[i]->energy().wh(0), 3);
            Serial.println(synced ? F("  [sync]") : F("  [MISSED FRAME]"));
        }
    }
    delay(60000);
}

Полный скетч (с проверкой шины и выводом ошибок) в 03_MultiModuleBroadcast.ino.


Сценарий 4 — UI3 на каждый прибор + MQTT

Модуль UI3 с тремя токовыми клещами на трёх нагрузках. Независимые счётчики Wh по каждому каналу, публикуются в MQTT раз в минуту. Показывает, что dev.energy().wh(ch) работает на каждом канале независимо — массив total_wh[3] вручную не нужен.

C++
#include 
#include 
#include 
#include 

static RbAmp dev(Wire, 0x50);
static const char* CH_NAMES[3] = {"main", "heatpump", "lights"};
static WiFiClient espClient;
static PubSubClient mqtt(espClient);

void publish_channel(const char* name, float avg_p, double e_wh) {
    char topic[64], payload[96];
    snprintf(topic, sizeof(topic), "rbamp/%s/state", name);
    snprintf(payload, sizeof(payload), "{\"power\":%.1f,\"energy\":%.4f}", avg_p, e_wh);
    mqtt.publish(topic, payload, true);
}

void setup() {
    Serial.begin(115200);
    WiFi.begin("ssid", "pass");
    while (WiFi.status() != WL_CONNECTED) delay(500);
    mqtt.setServer("192.168.1.10", 1883);
    mqtt.setKeepAlive(60);
    mqtt.connect("rbamp-ui3");

    Wire.begin();
    Wire.setClock(50000);    // reduced bus clock on ESP32
    dev.setLogStream(&Serial);
    while (!dev.begin()) { delay(500); }
}

void loop() {
    if (!mqtt.connected()) mqtt.connect("rbamp-ui3");
    mqtt.loop();

    static uint32_t last_period = 0;
    if (last_period == 0) last_period = millis();
    if (millis() - last_period < 60000) { delay(50); return; }
    last_period = millis();

    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) return;

    for (uint8_t ch = 0; ch < dev.channels(); ++ch) {
        publish_channel(CH_NAMES[ch], snap.avg_p[ch], dev.energy().wh(ch));
    }
}

Полный скетч в 04_UI3PerChannelMQTT.ino. Для автообнаружения HA MQTT поверх этой основы см. DIY-интеграции.


Сценарий 5 — Двунаправленный учёт на стороне мастера

Разделяет мощность RT со знаком на валовое потребление и валовый экспорт. Для модулей уровня BASIC, где накопитель периода обрезает отрицательные значения — семплируйте dev.readPower(0) с частотой 10 Гц на стороне мастера.

C++
#include 
#include 

static RbAmp dev(Wire, 0x50);
static double consume_wh = 0.0;
static double export_wh  = 0.0;
static uint32_t last_sample_ms = 0;

void setup() {
    Serial.begin(115200);
    Wire.begin();
    dev.setLogStream(&Serial);
    while (!dev.begin()) { delay(500); }
    last_sample_ms = millis();
}

void loop() {
    if (millis() - last_sample_ms < 100) { delay(5); return; }   // 10 Hz — matches RT cadence
    const uint32_t now_ms = millis();
    const uint32_t dt_ms  = now_ms - last_sample_ms;
    last_sample_ms = now_ms;

    const float p_w = dev.readPower(0);
    if (isnan(p_w)) return;

    const double dwh = (double)p_w * dt_ms / 3600000.0;
    if (p_w >= 0.0f) consume_wh += dwh;
    else             export_wh  += -dwh;

    static uint32_t next_print = 0;
    if (millis() >= next_print) {
        next_print = millis() + 200;
        Serial.print(F("P=")); Serial.print(p_w, 1);
        Serial.print(F("W   cons=")); Serial.print(consume_wh, 4);
        Serial.print(F("Wh  exp=")); Serial.print(export_wh, 4);
        Serial.print(F("Wh  net=")); Serial.print(consume_wh - export_wh, 4);
        Serial.println(F("Wh"));
    }
}

Полный скетч в 06_BidirectionalEnergy.ino. На модуле STANDARD (STD) dev.energy().wh(0) уже даёт знаковый чистый баланс; разбиение на стороне мастера нужно только для раздельного отчёта о валовом потреблении и валовом экспорте.


Сценарий 6 — Баланс энергии в доме

Три модуля: сеть (двунаправленный, STANDARD (STD)) + солнечная генерация (только генерация, подходит BASIC)

  • нагрузки (UI3 на BASIC для учёта по приборам). Сводная панель на весь дом публикуется каждые 60 с.
C++
#include 
#include 
#include 
#include 

static RbAmp mains(Wire, 0x50);    // bidirectional
static RbAmp solar(Wire, 0x51);    // generation only
static RbAmp loads(Wire, 0x52);    // UI3
static RbAmp* mods[] = { &mains, &solar, &loads };
static WiFiClient espClient;
static PubSubClient mqtt(espClient);

void setup() {
    Serial.begin(115200);
    WiFi.begin("ssid", "pass");
    while (WiFi.status() != WL_CONNECTED) delay(500);
    mqtt.setServer("192.168.1.10", 1883); mqtt.connect("home-balance");

    Wire.begin();
    Wire.setClock(50000);   // 50 kHz on ESP32 (100 kHz on non-ESP32 masters)
    for (auto m : mods) { while (!m->begin()) delay(500); m->enableGc(true); }
}

void loop() {
    delay(60000);

    static uint16_t g_tick = 0;
    RbAmp::broadcastLatchGroup(Wire, /*group=*/0x00, ++g_tick);  // coherent all-call snapshot
    delay(50);

    RbAmpPeriodSnapshot sm, ss, sl;
    mains.readPeriodSnapshot(sm, 0, true);
    solar.readPeriodSnapshot(ss, 0, true);
    loads.readPeriodSnapshot(sl, 0, true);

    char payload[512];
    snprintf(payload, sizeof(payload),
        "{\"mains\":%.3f,\"solar\":%.3f,\"hp\":%.3f,\"ac\":%.3f,\"ev\":%.3f}",
        mains.energy().wh(0),
        solar.energy().wh(0),
        loads.energy().wh(0),
        loads.energy().wh(1),
        loads.energy().wh(2));
    mqtt.publish("home/energy/balance", payload, true);
    mqtt.loop();
}

Для явного разделения потребления и экспорта на сетевом модуле комбинируйте с шаблоном сценария 5 (отдельный цикл 10 Гц на mains.readPower(0)).


Сценарий 7 — Обнаружение событий (EMA)

На каждом 100-мс окне RT сравнивайте P с экспоненциально взвешенным скользящим средним. Фиксируйте значимые отклонения (микроволновка, чайник).

C++
#include 
#include 

static RbAmp dev(Wire, 0x50);
static float p_ema = 0.0f;
static const float EMA_ALPHA = 0.05f;
static const float EVENT_THRESHOLD_W = 200.0f;

void setup() {
    Serial.begin(115200);
    Wire.begin();
    dev.setLogStream(&Serial);
    while (!dev.begin()) { delay(500); }
    p_ema = dev.readPower(0);     // seed EMA so first read isn't a spurious event
    if (isnan(p_ema)) p_ema = 0.0f;
}

void loop() {
    delay(200);
    const float p = dev.readPower(0);
    if (isnan(p)) return;

    const float delta = p - p_ema;
    p_ema = (1.0f - EMA_ALPHA) * p_ema + EMA_ALPHA * p;

    if (fabsf(delta) > EVENT_THRESHOLD_W) {
        Serial.print(millis()); Serial.print(F("  "));
        Serial.print(delta > 0 ? F("TURN_ON ") : F("TURN_OFF "));
        Serial.print(F("delta=")); Serial.print(delta, 0); Serial.print(F("W  "));
        Serial.print(F("P=")); Serial.print(p, 0); Serial.print(F("W  "));
        Serial.print(F("EMA=")); Serial.println(p_ema, 0);
    }
}

Составной сценарий — отдельного файла примера нет. Комбинируйте с публикацией по MQTT из сценария 4 для автоматизации событий на стороне HA или записывайте на SD через Adafruit_SD для автономного журнала событий.


Сценарий 8 — автономный стендовый монитор на 12 часов

Стенд длительной проверки — запускает библиотеку против реального DUT в течение 12–15 часов под плотной нагрузкой на каждом цикле, выводит одну строку CSV каждые 5 минут с полными диагностическими счётчиками. Эталонный рецепт, которым квалифицировали прошивку v1.1 на эталонном мастере библиотеки Arduino.

Ключевые особенности:

  • Переопределение RBAMP_NACK_RETRY_ATTEMPTS=5 — определите ДО подключения заголовка, чтобы настроить повторы для плотной нагрузки (≥10 однобайтовых чтений за цикл). По умолчанию 3 достаточно для опроса ESPHome раз в 60 с; SoakMonitor читает ~45 байт за цикл и нуждается в дополнительном запасе.

  • dev.rawTopology() — прямое чтение REG_TOPOLOGY (0x24) по шине для определения v1.1. Возвращает 1/2/3 на v1.1, 0x00 на v1.0, 0xFF при сбое I2C.

  • dev.retryExhaustionCount() + dev.sanityRejectCount() — оба должны оставаться на 0 для успешного 12-часового прогона.

Скелет одного цикла:

C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include 
#include 

RbAmp dev(Wire, 0x50);

void emitCycle() {
    const float u = dev.readVoltage();
    float i[3]={NAN,NAN,NAN}, p[3]={NAN,NAN,NAN}, pf[3]={NAN,NAN,NAN};
    for (uint8_t c = 0; c < dev.channels(); c++) {
        i[c]  = dev.readCurrent(c);
        p[c]  = dev.readPower(c);
        pf[c] = dev.readPowerFactor(c);
    }
    const float freq = dev.readFrequency();
    RbAmpPeriodSnapshot snap;
    const bool snap_ok = dev.readPeriodSnapshot(snap, 60);

    /* CSV row (shortened) */
    Serial.printf("%lu,%.3f,%.4f,%.3f,%.4f,%.1f,%.4f,%lu,%lu,%.6f,%lu,%lu,%u\n",
        millis(), u, i[0], p[0], pf[0], freq,
        snap.avg_p[0], snap.latch_ms, snap.master_dt_ms,
        dev.energy().wh(0),
        dev.retryExhaustionCount(),
        dev.sanityRejectCount(),
        snap_ok ? 1 : 0);
}

void setup() {
    Serial.begin(115200);
    Wire.begin(21, 22); Wire.setClock(50000);
    while (!dev.begin()) delay(500);
    dev.resetCounters();
    emitCycle();
}

void loop() {
    static uint32_t next_ms = 5UL * 60UL * 1000UL;
    if (millis() >= next_ms) { emitCycle(); next_ms += 5UL * 60UL * 1000UL; }
    delay(100);
}

Скетч собран из фрагментов этого сценария. Запускайте командой arduino-cli monitor -p COM3 -c baudrate=115200 > soak.csv и оставьте на 12–15 ч без присмотра. Приёмка: retry_exhaust == 0, sanity_reject == 0, period_ok / period_total ≥ 99 %, Wh монотонен.


Сценарий 9 — Регистратор от батареи с глубоким сном

ESP32 просыпается каждые 10 минут, снимает один снимок периода, публикует через WiFi+MQTT и уходит в глубокий сон. Энергия переживает сон благодаря памяти RTC. Накопитель библиотеки отключён — сохранением Wh владеет мастер.

Схема, важная для библиотеки:

C++
#include 
#include 
#include "esp_sleep.h"

RTC_DATA_ATTR uint32_t rtc_magic = 0;
RTC_DATA_ATTR double   rtc_total_wh = 0;
RTC_DATA_ATTR bool     rtc_primer_done = false;

void setup() {
    Serial.begin(115200);
    Wire.begin();
    RbAmp dev(Wire, 0x50);

    if (rtc_magic != 0xCAFEFEED) {
        rtc_magic = 0xCAFEFEED; rtc_total_wh = 0; rtc_primer_done = false;
    }

    dev.begin();
    dev.energy().disable();   // master owns Wh

    if (!rtc_primer_done) {
        dev.latchPeriod();
        rtc_primer_done = true;
        esp_sleep_enable_timer_wakeup(10ULL * 60ULL * 1000000ULL);
        esp_deep_sleep_start();
    }

    RbAmpPeriodSnapshot snap;
    if (dev.readPeriodSnapshot(snap)) {
        // master_dt_ms measures actual wake-to-wake interval
        rtc_total_wh += (double)snap.avg_p[0] * snap.master_dt_ms / 3600000.0;
        publish_via_wifi(snap.avg_p[0], rtc_total_wh, snap.master_dt_ms);
    }

    esp_sleep_enable_timer_wakeup(10ULL * 60ULL * 1000000ULL);
    esp_deep_sleep_start();
}
void loop() {}

Полный скетч (с настройкой WiFi, публикацией MQTT, защитами по магическому маркеру RTC) в 07_DeepSleepLogger.ino.

Бюджет мощности (ESP32-WROOM, интервал пробуждения 10 мин):

  • Время пробуждения: ~3 с (WiFi + MQTT + I2C)
  • Ток при пробуждении: ~80 мА в среднем → ~0.07 мАч за пробуждение
  • Ток покоя: ~10 µA (RTC + сохраняемые домены)
  • ~10 мАч/сутки всего → Li-ion 2000 мАч хватает примерно на 6 месяцев

Сценарий 10 — смена адреса I2C

Переназначьте адрес ведомого rbAmp с 0x50 на 0x51. Выполняется один раз для каждого модуля при создании установки из нескольких модулей. На время операции отключите остальные модули, чтобы избежать коллизий на шине.

В текущей прошивке (v1.3+) смена I²C-адреса модуля не требует специального режима, перемычки или заводских инструментов: вы подготавливаете новый адрес, взводите смену и коммитите её (двухфазная, магически взводимая последовательность, чтобы адрес не менялся случайно), после чего модуль перезагружается уже по новому адресу. Библиотека проводит двухшаговый протокол — prepareAddressChange() взводит, commitAddressChange() записывает в пределах 5-секундного окна.

C++
#include 
#include 

static const uint8_t CURRENT_ADDR = 0x50;
static const uint8_t NEW_ADDR     = 0x51;

static RbAmp dev(Wire, CURRENT_ADDR);

void setup() {
    Serial.begin(115200);
    Wire.begin();
    dev.setLogStream(&Serial);

    if (!dev.begin()) {
        Serial.println(F("device not found")); return;
    }
    Serial.print(F("fw=0x")); Serial.println(dev.firmwareVersion(), HEX);

    // Step 1: arm the change (no special mode needed on firmware v1.3+).
    if (!dev.prepareAddressChange(NEW_ADDR)) {
        Serial.print(F("prepare: ")); Serial.println(RbAmp::errorString(dev.lastError()));
        if (dev.lastError() == rbamp::RB_ERR_MODE) {
            Serial.println(F("Module firmware is older than v1.3 - update to v1.3+ for the no-mode two-phase path."));
        }
        return;
    }
    delay(1000);

    // Step 2: commit — writes 0x30, CMD_SAVE_GAINS (700 ms), CMD_RESET (100 ms).
    if (!dev.commitAddressChange()) {
        Serial.print(F("commit: ")); Serial.println(RbAmp::errorString(dev.lastError()));
        return;
    }
    Serial.print(F("device now at 0x")); Serial.println(dev.address(), HEX);

    if (dev.probe()) Serial.println(F("verified"));
}

void loop() { delay(60000); }

Полный скетч в 05_AddressChange.ino. Если 5-секундное окно взведения истекает до коммита, библиотека возвращает false с lastError() == RB_ERR_TIMEOUT и сбрасывает флаг взведения — нужно снова вызвать prepareAddressChange(). Это защищает от «кирпичей» из-за опечатки: одним неверным вызовом нельзя потерять устройство.


Сценарий 11 — Один скетч, обе линейки модулей

Пример 11_StdLine показывает, что один скетч обслуживает модули BASIC и STANDARD (STD). begin() определяет линейку; общие функции чтения (readVoltage(), readCurrent(), readPower(), readPowerFactor(), readFrequency()) работают на обеих, а дополнительные функции только STD — реактивная и полная мощность, покомпонентное блочное чтение (stdReadChannel()), счётчики состояния (stdReadHealth()) и банки снимков периода — стоят за проверкой line():

C++
if (dev.line() == RbAmpLine::Std) {
    RbAmpStdChannel c;
    if (dev.stdReadChannel(0, c)) {
        Serial.print(F("Q0=")); Serial.print(c.q, 1);
        Serial.print(F(" var  S0=")); Serial.println(c.s, 1);
    }
} else {
    // BASIC: reactive power is not exposed by this library
}

На модуле BASIC вызовы std* возвращают RB_ERR_NOT_IMPLEMENTED. Описание каждого вызова — в 09 · Справочник API, раздел API линии STD.


Таблица сравнения

# LOC Шина I2C Период? DRDY? MQTT? Сохранение
1 ~30 общий нет нет нет нет
2 ~50 общая с OLED да нет нет RAM
3 ~50 общий на 3 модуля да нет нет RAM
4 ~80 выделенный да нет да retained MQTT
5 ~50 выделенный нет (RT) нет нет ОЗУ (принадлежит мастеру)
6 ~70 общий на 3 модуля да нет да retained MQTT
7 ~40 выделенный нет (RT) нет нет RAM
8 ~250 выделенный да нет нет нет (поток CSV)
9 ~150 выделенный да нет да Память RTC + MQTT
10 ~50 выделенный n/a нет нет флеш (на стороне ведомого)
11 ~130 выделенный да нет нет нет

Что дальше


Исходники и задачи: rb-amp/rbamp-arduino · эта страница в репозитории: docs/06_examples.md


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