rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

01 · Visión general

Cadena de señal desde la pinza de corriente, a través del módulo rbAmp y el I²C, hasta el maestro y de ahí a la nube o a Home Assistant.

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

Un módulo en la acometida y un módulo por cada subcarga, todos en un bus I²C compartido leído por un único maestro.

  • 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 (o I2 / 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 balance mains − Σ(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).

Seguridad

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
Nota

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.

Nota

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.

Nota

¿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)

C++
// 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

C++
float u_rms = dev.readVoltage();

Lectura del periodo: sin la biblioteca

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

C++
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_VALID antes 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

Dónde está su boceto: boceto, biblioteca RbAmp, Wire (I²C) y el módulo rbAmp en la dirección por defecto 0x50.

Diagramas de interacción

El flujo de begin()

Secuencia de begin(): lectura de versión, detección de línea, instantánea de cebado (descartada), y después listo.

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)

Secuencia de readPeriodSnapshot(): la biblioteca cierra el período en el módulo, lee la instantánea, integra la energía con el reloj del maestro y devuelve el resultado al boceto.

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


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