rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub [Edit on GitHub]

05 · Inicio rápido

Un «hola mundo» de cinco minutos: instale la biblioteca, conecte el módulo, seleccione un sensor, tome su primera lectura RT y su primera instantánea por periodo (Wh).

Los detalles (disposición de pines para un host concreto, bus multimódulo, elección de un SCT-013 por rango) están en los capítulos vecinos:

Primera lectura en ocho pasos: cablear, encender, escanear 0x50, begin(), configuración opcional del sensor, leer U, I, P, FP, comprobación de cordura y después energía.

Qué necesitará

  • Un módulo rbAmp (cualquier nivel; UI1 por simplicidad)
  • Un host compatible con Arduino: UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • Una pinza SCT-013 con calibre superior a su mayor corriente prevista (5A / 10A / 30A / 50A / 100A), o el TC que vino conectado a su módulo
  • Una alimentación de 5 V para el módulo (desde el USB-5V del host o una fuente externa)
  • Un circuito de CA que medir (una lámpara, un hervidor, un electrodoméstico)

Paso 1 — Instale la biblioteca

Arduino IDE — Gestor de bibliotecas [Library Manager]

Sketch → Include Library → Manage Libraries… → busque RbAmp → Install. No tiene dependencias. Tras la instalación, los ejemplos aparecen en File → Examples → RbAmp.

Arduino CLI

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

Paso 2 — Cableado

Seguridad

⚠ La tensión de red puede matar. Desconecte y bloquee el circuito antes de conectar los terminales L/N o colocar la pinza; que un profesional cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro. Pince UN solo conductor (L): nunca el cable completo (L+N se anulan hasta ~0). Proteja la derivación de L según la normativa local.

Cuatro cables de baja tensión, más un DRDY opcional, y después los terminales de red:

Pin de rbAmp Host
VCC +5 V (rango 4.5..5.5 V)
GND GND
SDA SDA de I²C (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (opcional) sáltelo para el primer boceto; véase 04_hardware.md
Terminales L y N el mismo circuito que alimenta la carga que mide (lado de red: véase la advertencia de arriba)
Conector de CT Conector SCT-013 introducido por completo

La alimentación debe ser de 5 V. Las líneas I²C funcionan a lógica de 3.3 V, pero toleran 5 V: conéctelas directamente a un Arduino UNO sin conversor de nivel. La placa del módulo ya incluye resistencias de pull-up de 4.7 kΩ integradas: para un módulo único no se necesitan externas.

La tabla completa de pines de cada host Arduino está en 04 · Cableado.

La pinza SCT-013 se coloca alrededor solo del conductor de línea (L), con la flecha del cuerpo de la pinza apuntando en el sentido de la corriente hacia la carga. Para más detalle (sección «Sensor de corriente») véase el capítulo 04 · Cableado.

Conexión del lado de red: la pinza CT solo en el cable L con la flecha hacia la carga, y la derivación de referencia de tensión L/N.

Paso 3: primer boceto (lectura RT)

Un boceto mínimo: verifique la comunicación sin configurar el sensor:

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

Cargue el boceto y abra el monitor serie a 115200 baudios.

Salida esperada (sin calibración del sensor):

Text
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 puede mostrar nan, 0.000 u otro valor de relleno mientras la corriente sea cero.

Seguridad

U muestra aproximadamente la tensión de red (220-240 V en redes de 230 V), lo que significa que el módulo está bien conectado. I=0.000 A incluso con la carga encendida es normal en esta fase: el módulo aún no sabe qué pinza CT está usando. Con I=0, el PF es matemáticamente indefinido (depende del firmware: puede ser NaN, 0 o un valor de relleno); la forma exacta del valor no importa mientras la corriente sea cero. El siguiente paso lo corrige.

Paso 4: configuración del sensor de corriente

Si instaló una pinza SCT-013 independiente, debe indicar al módulo la clase de sensor y el modelo. Sin ello no se cargan los coeficientes de calibración y las lecturas de corriente permanecen en cero. Si su módulo llegó con el TC ya conectado, omita este paso.

Lea el modelo en la etiqueta impresa en la pinza (por ejemplo SCT-013-030 → código 3, véase la tabla de abajo). Elija la pinza de clasificación más pequeña por encima de su corriente máxima esperada. Una pinza con clasificación demasiado pequeña da lecturas recortadas y demasiado bajas en los picos; una con clasificación muy superior da lecturas ruidosas e imprecisas con corrientes pequeñas.

Añada esto a setup() tras dev.begin(). La función loop() sigue igual que en el Paso 3: solo cambia setup():

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

Códigos de modelo: el conjunto aceptado es {1, 2, 3, 4, 5, 6, 7}:

code Modelo Rango Estado Uso típico
1 SCT-013-005 0..5 A ✅ seleccionable Cargas pequeñas, una sola toma
2 SCT-013-010 0..10 A ✅ seleccionable Frigorífico, lavadora
3 SCT-013-030 0..30 A ✅ seleccionable Alimentación doméstica de hasta ~7 kW
4 SCT-013-050 0..50 A ✅ seleccionable Cargador de VE, calefacción eléctrica
5 SCT-013-100 0..100 A ✅ seleccionable Entrada principal de servicio, alimentaciones grandes
6 SCT-013-020 0..20 A ✅ seleccionable Alimentación media: electrodomésticos de 3-4 kW
7 SCT-013-060 0..60 A ✅ seleccionable Submedidor industrial

Para más información sobre la selección, véase 03 · Selección de sensor de corriente.

Nota

Estas dos llamadas se hacen una sola vez en la primera instalación: la elección se guarda en la flash del módulo y sobrevive a un reinicio. El tiempo total es de unos 1.4 segundos (dos escrituras en flash × ~700 ms cada una). La biblioteca serializa ambas llamadas internamente: cada una bloquea hasta que termina la escritura en flash, así que no necesita añadir un delay() entre ellas: la segunda espera por su cuenta hasta que la primera libera el recurso.

En las siguientes ejecuciones del boceto puede omitir setSensorClass() y setCTModel() (el módulo lo recuerda). Pero no pasa nada si las repite: una llamada repetida con el mismo valor reescribe el mismo byte.

Tras reiniciar el boceto, debería aparecer el valor de corriente correcto:

Text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

Paso 5 — Contabilidad de energía (Wh)

El módulo devuelve solo cantidades instantáneas más la potencia media durante un periodo. La propia biblioteca calcula los Wh a partir del reloj de pared del maestro:

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

donde master_dt_s es el número de segundos entre dos llamadas correctas a readPeriodSnapshot().

Una plantilla mínima de contabilidad periódica (una vez por minuto):

C++
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
}
Nota

Tras el paso 4, setSensorClass() y setCTModel() ya se han ejecutado una vez y se han guardado en la flash del módulo; en la plantilla anterior están para las repeticiones del boceto: el módulo ignora una llamada repetida con el mismo valor. Se omite el tratamiento de errores por brevedad: añada guardas if (!...) si quiere detectar los fallos ocasionales de comunicación al arrancar.

Lo que hace readPeriodSnapshot() por dentro:

  1. Envía al módulo un comando de instantánea de periodo.
  2. Espera 50 ms mientras el módulo prepara la instantánea.
  3. Comprueba el indicador de listo; lee la potencia media/pico.
  4. Actualiza el contador interno de Wh: += avg_p × master_dt_s / 3600.

begin() ya ejecuta una primera instantánea que la biblioteca descarta. Por eso, la primera readPeriodSnapshot() de su boceto solo cubre el tiempo transcurrido desde begin() (unos segundos, véase dt= en la salida): ignore esa primera línea y espere a un período completo. A partir de la segunda llamada, cada línea cubre un período completo.

Salida esperada:

Text
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
...

Varios módulos

Para varios módulos en un mismo bus (acometida general + subcargas) use RbAmpFleet. El ejemplo completo está en 06 · Ejemplos, escenario 1; las reglas de cableado para un bus multimódulo están en 04 · Cableado.

Qué sigue


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