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:
-
04 · Cableado: detalles de hardware y secciones por MCU de cada plataforma
-
03 · Selección de sensor de corriente: qué modelo SCT-013 elegir y por qué
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
arduino-cli lib install RbAmp
PlatformIO
[env:esp32dev]
platform = espressif32
framework = arduino
lib_deps = rbamp/RbAmp@^1.6.1
Paso 2 — Cableado
⚠ 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.
Paso 3: primer boceto (lectura RT)
Un boceto mínimo: verifique la comunicación sin configurar el sensor:
#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):
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.
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():
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.
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:
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:
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):
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
}
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:
- Envía al módulo un comando de instantánea de periodo.
- Espera 50 ms mientras el módulo prepara la instantánea.
- Comprueba el indicador de listo; lee la potencia media/pico.
- 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:
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
- 01 · Visión general — qué es rbAmp y qué hace la biblioteca
- 02 · Niveles de módulo: qué nivel encaja con cada tarea
-
06 · Ejemplos: escenarios de trabajo: red + N cargas secundarias (el canon del 80 %), flujo de aprovisionamiento, mezcla multicanal con CT, sincronización GC de flota, MQTT, deep sleep
-
07 · Integraciones DIY — Home Assistant / Node-RED / OpenHAB
-
08 · Integraciones en la nube: AWS IoT / Azure / GCP / InfluxDB
-
09 · Referencia de API — la API pública completa (incluidos
RbAmpFleet+ multicanal + modelo de errores v1.3 + identidad y aprovisionamiento) -
10 · Solución de problemas — cuando algo no funciona (mitigación en tres capas del bloqueo i2c, modos de fallo de conflicto de flota / bloqueo / fallo de aprovisionamiento)
Fuente y incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/05_quickstart.md (v1.6.2)