rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

Ejemplos

Recorrido por los sketches incluidos en examples/ y escenarios compuestos. La mayoría de los ejemplos numerados tienen código equivalente en examples/; abra los sketches reales en el IDE de Arduino para ver el código fuente completo.


Escenario 1: lectura rápida

Objetivo: imprimir U / I / P / PF / frecuencia una vez por segundo. El «hola mundo» que acaba de escribir en el Inicio rápido, pero usando dev.readAll(s) para una lectura completa de bloque RT en una sola llamada en lugar de llamadas individuales a propiedades.

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

Lo que circula por el bus: readAll() en un UI3 emite 53 transacciones de un solo byte (13 floats × 4 bytes + 1 byte de frecuencia). A 100 kHz con margen de 3 reintentos, ~12-15 ms en total. Pase a lecturas por llamada (dev.voltage, dev.current[ch]) si solo necesita un subconjunto.


Escenario 2 — Medidor de 60 segundos en OLED

Contador de Wh actualizado una vez por minuto en una OLED SSD1306 de 128×64 que comparte el bus I2C (OLED en 0x3C). Mecánica clave de la biblioteca: readPeriodSnapshot() hace instantánea + asentamiento + comprobación de validez + lectura + marca de Wh en una sola llamada.

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();
}

Boceto completo en 02_PeriodEnergyOLED.ino.

Gestión de instantáneas obsoletas: readPeriodSnapshot() devuelve false con lastError() == RB_ERR_STALE si REG_V03_PERIOD_VALID == 0. La biblioteca sigue confirmando internamente la marca de tiempo del reloj de pared del maestro; esto impide que la siguiente instantánea correcta duplique Wh en un intervalo de 2× el periodo.


Escenario 3: monitor multimódulo

Tres módulos rbAmp en un bus en 0x50 / 0x51 / 0x52. Cada uno debe tener una dirección I²C única: use escenario 10 para asignar direcciones durante la instalación.

Instantánea coherente v1.3

todo módulo que admite la instantánea General-Call y ha optado por ella (enableGc(true), persistente) captura el mismo período de red en una única trama all-call: RbAmp::broadcastLatchGroup(Wire, 0x00, tick). La desviación entre módulos de la flota es < 10 µs, así que las potencias de cada módulo se suman de forma coherente. Cada módulo marca su instantánea con el tick de difusión; léalo con readGcTick() para detectar un módulo que se haya perdido la trama. (En firmware v1.0/v1.1, la instantánea General-Call no estaba disponible y este boceto recurría a instantáneas secuenciales por dispositivo; se conserva en el comentario de historial del archivo para los módulos antiguos.)

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

Sketch completo (con sondeo de escaneo del bus y notificación de errores) en 03_MultiModuleBroadcast.ino.


Escenario 4 — UI3 por electrodoméstico + MQTT

Un módulo UI3 con tres pinzas de CT en tres cargas. Contadores de Wh independientes por canal, publicados por MQTT una vez por minuto. Demuestra que dev.energy().wh(ch) funciona en cada canal de forma independiente, sin necesidad de un array manual 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));
    }
}

Sketch completo en 04_UI3PerChannelMQTT.ino. Para la autodetección MQTT de HA sobre esta base, véase Integraciones DIY.


Escenario 5 — Contabilidad bidireccional en el lado del maestro

Separa la potencia RT con signo en cubos de consumo bruto y exportación bruta. Úselo en módulos de nivel BASIC, donde el acumulador de período recorta los valores negativos: muestree dev.readPower(0) a 10 Hz en el lado del maestro.

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"));
    }
}

Sketch completo en 06_BidirectionalEnergy.ino. En un módulo STANDARD (STD), dev.energy().wh(0) ya da el balance neto con signo; esta división en el maestro solo hace falta para informar consumo bruto frente a exportación bruta.


Escenario 6: balance energético del hogar

Tres módulos: principal (bidireccional, STANDARD (STD)) + solar (solo generación, BASIC válido)

  • cargas (UI3 BASIC para cada electrodoméstico). Panel de toda la vivienda combinado, publicado cada 60 s.
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();
}

Para la división explícita consumo/exportación en el módulo de red, combínelo con el patrón del Escenario 5 (ejecute un bucle aparte a 10 Hz sobre mains.readPower(0)).


Escenario 7 — Detección de eventos (EMA)

En cada ventana RT de 100 ms, compare P con una media móvil exponencialmente ponderada. Registre las desviaciones significativas (microondas / hervidor).

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

Escenario compuesto: sin archivo de ejemplo dedicado. Combínelo con la publicación MQTT del escenario 4 para la automatización de eventos en HA, o registre en SD con Adafruit_SD para el seguimiento de eventos sin conexión.


Escenario 8 — Monitor de banco autónomo de 12 horas

Arnés de validación de larga duración: ejecuta la biblioteca contra un DUT real durante 12-15 horas bajo una carga densa por ciclo, y emite una fila CSV cada 5 minutos con contadores de diagnóstico completos. Es la receta de referencia usada para calificar el firmware v1.1 en el maestro de referencia de la biblioteca Arduino.

Características principales:

  • Anulación de RBAMP_NACK_RETRY_ATTEMPTS=5: defínala ANTES del include para ajustar el reintento en cargas densas (≥10 lecturas de un solo byte por ciclo). El valor 3 por defecto basta para el sondeo de 60 s de ESPHome; SoakMonitor lee ~45 bytes por ciclo y necesita el margen adicional.

  • dev.rawTopology(): lectura directa por cable de REG_TOPOLOGY (0x24) para la detección de v1.1. Devuelve 1/2/3 en v1.1, 0x00 en v1.0, 0xFF ante un fallo de I2C.

  • dev.retryExhaustionCount() + dev.sanityRejectCount(): ambos deben permanecer en 0 para dar por superada una prueba de 12 h.

Esqueleto por ciclo:

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

El boceto se construye a partir de los fragmentos de este escenario. Ejecútelo con arduino-cli monitor -p COM3 -c baudrate=115200 > soak.csv y déjelo desatendido entre 12 y 15 h. Criterio de aceptación: retry_exhaust == 0, sanity_reject == 0, period_ok / period_total ≥ 99 %, Wh monótono.


Escenario 9: registrador de deep sleep con batería

El ESP32 se despierta cada 10 minutos, toma una instantánea de periodo, publica por WiFi+MQTT y entra en sueño profundo. La energía persiste entre suspensiones en la memoria RTC. El acumulador de la biblioteca está desactivado: el maestro gestiona la persistencia de Wh.

Esqueleto relevante para la biblioteca:

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() {}

Sketch completo (con configuración de WiFi, publicación MQTT, guardas de marcador mágico en RTC) en 07_DeepSleepLogger.ino.

Presupuesto de potencia (ESP32-WROOM, intervalo de despertar de 10 min):

  • Duración del despertar: ~3 s (WiFi + MQTT + I2C)
  • Corriente de despertar: ~80 mA de media → ~0.07 mAh por despertar
  • Corriente de reposo: ~10 µA (RTC + dominios retenidos)
  • ~10 mAh/día en total → una batería de Li-ion de 2000 mAh dura ~6 meses

Escenario 10: cambio de dirección I2C

Reasigne la dirección de esclavo de un rbAmp de 0x50 a 0x51. Se usa una vez por módulo al construir una instalación multimódulo. Desconecte los demás módulos durante esta operación para evitar colisiones en el bus.

En el firmware actual (v1.3+), cambiar la dirección I²C de un módulo no requiere ningún modo especial, puente ni herramienta de fábrica: se prepara la nueva dirección, se arma el cambio y se confirma (una secuencia en dos fases con armado mágico, para que una dirección no cambie por accidente), y el módulo se reinicia en su nueva dirección. La biblioteca impone un protocolo de dos pasos: prepareAddressChange() arma y commitAddressChange() escribe dentro de una ventana de 5 segundos.

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

Boceto completo en 05_AddressChange.ino. Si la ventana de armado de 5 segundos caduca antes de la confirmación, la biblioteca devuelve false con lastError() == RB_ERR_TIMEOUT y reinicia el indicador de armado: debe volver a llamar a prepareAddressChange(). Así se evita que un solo error de escritura deje el dispositivo inutilizable.


Escenario 11 — Un sketch, ambas líneas de módulos

El ejemplo 11_StdLine muestra que un solo boceto sirve para módulos BASIC y ESTÁNDAR (STD). begin() detecta la línea; las lecturas comunes (readVoltage(), readCurrent(), readPower(), readPowerFactor(), readFrequency()) funcionan en ambas, y los extras exclusivos de STD (potencia reactiva y aparente, lecturas de bloques por canal, stdReadChannel(), contadores de salud, stdReadHealth(), y los bancos de instantáneas de período) están detrás de una comprobación de 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
}

En un módulo BASIC, las llamadas std* devuelven RB_ERR_NOT_IMPLEMENTED. La descripción llamada por llamada está en 09 · Referencia de API § API de la línea STD.


Tabla comparativa

# LOC Bus I2C ¿Período? DRDY? MQTT? Persistencia
1 ~30 compartido no no no ninguno
2 ~50 compartido con OLED sí no no RAM
3 ~50 3 módulos compartidos sí no no RAM
4 ~80 dedicado sí no sí MQTT retenido
5 ~50 dedicado no (RT) no no RAM (propiedad del maestro)
6 ~70 3 módulos compartidos sí no sí MQTT retenido
7 ~40 dedicado no (RT) no no RAM
8 ~250 dedicado sí no no ninguno (flujo CSV)
9 ~150 dedicado sí no sí Memoria RTC + MQTT
10 ~50 dedicado n/a no no flash (lado esclavo)
11 ~130 dedicado sí no no ninguno

Lo siguiente


Fuente e incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/06_examples.md


Fuente e incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/06_examples.md (v1.6.2)