01 · Visión general
Qué es rbAmp
rbAmp es un módulo de hardware compacto para la medición de precisión de parámetros de la red de corriente alterna mediante la interfaz I²C. Dispone de una front-end analógica aislada integrada y de calibración de fábrica guardada en flash.
Desde el punto de vista del integrador, el módulo se comporta como un esclavo I²C estándar: conecte la alimentación, lea los registros y obtendrá valores listos en unidades físicas. No se requiere procesamiento de señal en el lado del maestro.
El propósito principal de la biblioteca: monitorizar varias cargas
La biblioteca Arduino RbAmp está diseñada para trabajar con un grupo de módulos simultáneamente en un único bus I²C, no para manejar un solo dispositivo. El escenario canónico es un módulo principal en la acometida más N módulos en cargas individuales, todos en un bus, controlados por un único Arduino/ESP32. La biblioteca ofrece la clase RbAmpFleet: un único objeto a través del cual se escanea el bus, se consulta cada módulo con una sola llamada, se obtiene la potencia consumida total y el balance «acometida − Σ(cargas)», se capturan los errores de cada módulo y, cuando hace falta, se sincronizan las instantáneas de periodo con un comando de difusión.
Los módulos multicanal también están admitidos: los de solo corriente I2 / I3 (dos o tres TC) y los equipados con tensión UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 canales de corriente, con potencia, FP y Wh por canal). Cada canal tiene su propio modelo de sensor. Es lo típico en un subcuadro, donde un único punto de instalación supervisa varios circuitos.
Trabajar con un único módulo es el caso mínimo de esta misma biblioteca: la clase RbAmp es el bloque sobre el que se construye RbAmpFleet. Si tiene un solo módulo en el bus, use directamente ese mismo handle: no se necesita la API de flota.
El escenario del 80 % — acometida + N subcargas
- 1 módulo en la acometida de red: consumo global y calidad de la red.
- N módulos en cargas individuales: medición por canal.
- Los módulos multicanal también encajan en este caso: un
UI2/UI3/UI5/UI7(oI2/I3) puede medir varias cargas, cada una en su propio canal: N módulos no tienen por qué significar N cargas. -
Una sola llamada a
fleet.pollAll()consulta todo; el balancemains − Σ(sub_loads)revela «el resto» (consumo de fondo, cargas no medidas, fugas). -
Una sola marca de tiempo maestra → medición correcta de Wh sin deriva entre módulos (véase 02_tiers.md y la sección sobre el reloj de pared del maestro en 09_api_reference.md).
Detalle arquitectónico importante. Las variantes I (I1/I2/I3) miden solo corriente: no tienen tensión, ni potencia activa, ni PF. La energía activa (Wh) y la potencia se calculan solo en las variantes UI (que tienen una etapa de entrada de tensión). En el despliegue canónico, el papel de «contador de red» (medición tarifaria y por período) lo desempeña un único UI1 en la acometida; el papel de submedidor (detalle de corriente por carga) lo desempeñan los I2/I3 (o UI2 / UI3 / UI5 / UI7 cuando se necesitan potencia y Wh por carga).
Para más detalles, véase el capítulo 06 · Ejemplos, escenario 1 («Red + N cargas secundarias: el canon del 80 %»). Para la API, véase el capítulo 09 · Referencia de la API, sección «Gestor de flota».
Qué mide rbAmp
| Magnitud | Tipo | Rango |
|---|---|---|
| Tensión RMS U_rms | float32, V | 0…300 V |
| Tensión de pico U_peak | float32, V | 0…450 V |
| Corriente RMS I_rms | float32, A | depende del sensor seleccionado: véase 03_sensor_selection.md |
| Corriente de pico I_pico | float32, A | depende del sensor seleccionado |
| Potencia activa P (con signo en RT) | float32, W | depende del sensor seleccionado |
| Factor de potencia PF | float32 | −1…+1 |
| Frecuencia de red | uint8, Hz | 50 / 60 Hz (detectado) |
| P promediada por período | float32, W | igual que para P |
El valor RT de la potencia activa P es siempre con signo en cualquier nivel de módulo (negativo significa exportación a la red). El comportamiento del valor promediado por periodo (PERIOD_AVG_P_W) depende del nivel del módulo: véase la sección «Niveles de módulo» más abajo y 02_tiers.md.
Conexión
El módulo se conecta al maestro con cuatro cables en el lado de baja tensión; todo lo que toca la red permanece dentro de la carcasa.
| Cable | Finalidad |
|---|---|
VCC |
+5 V (4.5..5.5 V), corriente ~15 mA, pico ~25 mA. Regulador integrado y filtrado |
GND |
en común con el maestro (obligatorio) |
SDA, SCL |
I²C, lógica de 3.3 V tolerante a 5 V. Pull-ups integradas de 4.7 kΩ a 3.3 V |
DRDY |
opcional, drenador abierto en BAJO durante ~10 µs cada ~100 ms |
La dirección por defecto es 0x50 (7 bits, rango de cambio 0x08..0x77), a 100 kHz (UNO / Mega / STM32 / RP2040) o 50 kHz (ESP32 / ESP8266); no use 400 kHz. El arranque en frío hasta la primera medición válida es de ~250 ms.
Las reglas completas (longitud del bus, recomendaciones de pull-up en un bus multimódulo, esquemas de cableado con distintos hosts) están en el capítulo 04 · Conexión.
Niveles de módulo (hoja de referencia rápida)
El nivel BASIC implementa una medición unidireccional (solo consumo), siguiendo la lógica de un contador mecánico clásico; la línea STANDARD (STD) es una segunda línea de módulos comercializada, con energía con signo (importación / exportación):
| Nivel | Potencia RT P |
Acumulador por periodo PERIOD_AVG_P_W |
Contador de Wh de la biblioteca |
|---|---|---|---|
| BASIC | con signo (negativo = exportación a la red, visible en tiempo real) | cada ventana de 100 ms de la potencia media P se limita a max(P, 0) antes de sumarse al acumulador del periodo |
monótono: solo mide el consumo |
| STANDARD (STD) | con signo | importación y exportación contabilizadas por separado (bancos de instantáneas, o los contadores persistentes de vida útil del módulo) | energía neta = importación − exportación (wh_net, stdReadEnergy()) |
Los detalles están en el capítulo 02 · Niveles de módulo. A nivel de biblioteca se usa la misma clase RbAmp independientemente del nivel; las diferencias aparecen en los valores que devuelve el módulo.
Medición bidireccional en BASIC: dev.energy().wh(ch) de la biblioteca en el nivel BASIC da solo consumo. Si necesita contabilizar la exportación por separado, muestree la potencia RT dev.readPower(0) a ~10 Hz y separe las muestras positivas y negativas en dos variables acumuladoras por su cuenta. Un ejemplo está en 06_examples.md (el escenario BidirectionalEnergy).
Qué hace esta biblioteca
La función principal es ocultar el intercambio de protocolo y liberar al boceto del usuario de la rutina de trabajar con registros, el orden de bytes y los tiempos de estabilización tras los comandos. Además, la biblioteca calcula la energía (Wh): el módulo solo devuelve la potencia promediada por período, y la integración la hace el maestro con su propio reloj.
¿Compila para ESPHome? Use el componente externo en lugar de esta biblioteca directamente: integra el protocolo rbAmp de forma nativa en el pipeline YAML de ESPHome.
Sin la biblioteca (acceso directo a los registros)
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);
Con la biblioteca
float u_rms = dev.readVoltage();
Lectura del periodo: sin la biblioteca
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27); // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50); // settling time after the command
Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
// snapshot is stale — t_latch_ms must STILL be recorded,
// otherwise the next snapshot will count Wh over two periods
t_prev_latch_ms = t_latch_ms; // <-- this line is easy to forget
return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
// float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
// E_Wh += avg_p × dt_s / 3600.0f;
Leer el período: con la biblioteca
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
// snap.avg_p[0] is filled,
// dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
// master_dt_ms is accounted for and saved for the next cycle.
}
Internamente, la biblioteca garantiza:
-
Un tiempo de estabilización de 50 ms tras
CMD_LATCH_PERIOD, y una lectura correcta de la instantánea (instantánea atómica en el lado del módulo). -
Una comprobación del flag
PERIOD_VALIDantes de leer. -
Registrar la hora según el reloj del maestro incluso con una instantánea obsoleta (evita la doble contabilización de Wh en el siguiente período).
-
Acumulación de Wh por canal en doble precisión.
- Carga automática de los coeficientes de calibración al seleccionar un sensor de corriente mediante
setSensorClass(class)+setCTModel(code): el usuario no necesita conocer los registros NF/GAIN.
Cuándo usar la biblioteca y cuándo el acceso directo a registros
| Tarea | Biblioteca | Acceso directo a registros |
|---|---|---|
| Lectura de U / I / P / FP / frecuencia | ✅ | solo para depuración con analizador lógico |
| Medición de energía por periodos | ✅ | solo si los Wh se almacenan fuera de la biblioteca (por ejemplo, en una base de datos en el lado del maestro) |
| Varios módulos en un mismo bus | ✅ | — |
| Medición bidireccional en BASIC | ✅ (mediante lecturas RT: véase 06_examples.md) | alternativa: su propio bucle de lecturas RT e integración manual |
| Adaptación a una plataforma que no es Arduino | n/a | ✅ — véase 09 · Referencia de la API, la sección «Detalles del protocolo de cable» |
| Límite duro de RAM (AVR Uno) | ~42 B por instancia de RbAmp + 63 B por instantánea; viable, pero ajustado en multimódulo (3 módulos × ~42 B + 3 × 63 B ≈ 315 B ya ocupan una parte notable del presupuesto de RAM de la aplicación) |
✅ si la instancia de la biblioteca no cabe |
Para todas las tareas habituales de las primeras filas, la biblioteca es la opción adecuada.
Arquitectura
Diagramas de interacción
El flujo de begin()
La primera instantánea es de cebado (el módulo devuelve lo acumulado desde el encendido, lo que no sirve para la medición tarifaria). La biblioteca registra por sí misma que esta instantánea debe descartarse: el código del usuario nunca la ve.
El flujo de readPeriodSnapshot(snap)
La instantánea atómica en el lado del módulo garantiza que cada medición dentro del periodo caiga en exactamente una instantánea: sin duplicados ni pérdidas en el límite del periodo.
Correspondencia con la API de registros directa
Una tabla para quienes migran desde su propio código basado en acceso directo:
| API directa | Equivalente mediante la biblioteca |
|---|---|
Lectura manual de 4 bytes + memcpy |
dev.readVoltage() / dev.readPower(ch) |
Wire.write(0x01); Wire.write(0x27); delay(50) |
dev.latchPeriod(); delay(50) (o simplemente dev.readPeriodSnapshot()) |
Comprobación de Wire.read(0x07) & 1 |
dev.isPeriodValid() |
La fórmula manual E_Wh += avg_p × dt_s / 3600 |
dev.energy().wh(0): se actualiza automáticamente |
| Configuración manual del sensor de corriente mediante la API de registros directa | dev.setSensorClass(class) + dev.setCTModel(code): los preajustes de fábrica se cargan automáticamente |
Lo que viene después
- 02 · Niveles de módulo — qué nivel para qué tarea
- 04 · Conexión — pull-ups, longitud del bus, configuración multimódulo
- 05 · Inicio rápido — el primer sketch funcional
- 06 · Ejemplos: recorrido por los bocetos listos para usar
- 09 · Referencia de API — todos los métodos públicos
- 10 · Solución de problemas: cuando algo no funciona
Fuente e incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/01_overview.md (v1.6.2)