01 · Visión general
rbAmp es un módulo compacto de hardware para la medición de precisión de parámetros de la red eléctrica de CA mediante la interfaz I²C. Está construido en torno a un microcontrolador con una etapa analógica frontal aislada integrada y calibración de fábrica guardada en flash.
Qué es rbAmp
El propósito principal de la biblioteca: monitorizar varias cargas
components/rbamp está diseñado para trabajar con un grupo de módulos en un único bus I²C a la vez, en lugar de controlar un solo dispositivo. El escenario canónico es un módulo principal en la acometida de red más N módulos en cargas individuales, todos en un bus, gestionados por un solo ESP32. La biblioteca ofrece un manejador de flota: un único objeto a través del cual se escanea el bus, se sondean todos los módulos en una llamada, se obtiene la potencia total consumida y el balance «acometida − Σ(cargas)», se capturan los errores por módulo y, cuando hace falta, se sincronizan las instantáneas de período con un comando de difusión.
Los módulos multicanal también se admiten: los I2 / I3 de solo corriente (2 / 3 canales de corriente) y los UI2 / UI3 / UI5 / UI7 con tensión (2 / 3 / 5 / 7 canales de corriente, con potencia, PF y Wh por canal). Cada canal tiene su propio modelo de sensor CT. Es típico de un subcuadro donde un único punto de instalación vigila varios circuitos: un módulo ofrece un desglose por canal sin necesitar un módulo aparte en cada uno.
Detalle arquitectónico importante. Potencia y Wh requieren una variante UI; un balance «red menos suma de cargas» requiere un módulo UI en cada carga. Las variantes I (I1/I2/I3) miden solo corriente: no tienen tensión, 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 la implantación canónica, la función de «contador de red» (energía total) la cumple un único UI1 en la acometida, mientras que la función de subcontador (detalle de corriente por carga) la cumplen los módulos I2/I3 (o UI2 / UI3 / UI5 / UI7 cuando se necesitan potencia y Wh por carga).
Trabajar con un único módulo es el caso mínimo de esta misma biblioteca: rbamp_handle_t es el bloque sobre el que se construye la flota. Si tiene un módulo en el bus, use ese mismo manejador directamente: no hace falta la API de flota.
El escenario del 80 % — acometida + N subcargas
- 1 módulo en la acometida (red): consumo total y calidad de red.
- N módulos en cargas individuales — contabilidad por canal.
- Los módulos multicanal también encajan en este caso: un único 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 única llamada a la flota,
rbamp_fleet_poll_all(), sondea todo; el balancemains − Σ(sub_loads)revela el «resto» (consumo de fondo, cargas no contabilizadas, fugas). -
Una marca de tiempo maestra compartida → contabilidad de Wh correcta, sin deriva entre módulos (véanse 02_tiers.md y la sección sobre el reloj de pared del maestro en 09_api_reference.md).
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 | float, V | 0…300 V |
| Tensión de pico U_peak | float, V | 0…450 V |
| Corriente RMS I_rms | float, A | depende del sensor seleccionado — véase 03_sensor_selection.md |
| Corriente de pico I_pico | float, A | depende del sensor seleccionado |
| Potencia activa P (con signo en RT) | float, W | depende del sensor seleccionado |
| Factor de potencia PF | float | −1…+1 |
| Frecuencia de red | uint8, Hz | 50 / 60 Hz (detectado) |
| P promediada en un período | float, W | igual que P |
El valor RT de la potencia activa P siempre tiene signo en cualquier línea de módulos (negativo = exportación a la red). El comportamiento del valor promediado por período (avg_p[ch] en rbamp_period_snapshot_t) depende de la línea del módulo: vea la sección «Líneas de módulos» más abajo y 02_tiers.md.
Cableado
El módulo se conecta al master con cuatro cables en el lado de BT. La única referencia de red (la entrada de tensión L/N en las variantes UI*) está tras un divisor aislado galvánicamente, y la pinza de CT se acopla magnéticamente sin contacto eléctrico; vea 04 · Cableado, «Conexión a la red y a la pinza de CT» (la tensión de red puede matar: lea antes la advertencia de allí).
| Cable | Finalidad |
|---|---|
VCC |
+5 V (4.5..5.5 V), ~15 mA, pico ~25 mA. Regulador y filtrado integrados |
GND |
común con el master (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, colector abierto: BAJO ~10 µs cada ~100 ms |
La dirección por defecto es 0x50 (7 bits, rango configurable 0x08..0x77); la velocidad recomendada es 50 kHz en ESP32 (véase la sección sobre la disciplina de reintento + cordura más abajo). 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, diagramas de cableado para los distintos objetivos ESP32) están en el capítulo 04 · Cableado.
Líneas de módulos (chuleta rápida)
Los módulos BASIC y STANDARD (STD) se están entregando. BASIC sigue la lógica de un contador mecánico clásico: contabilidad unidireccional (solo consumo); STD mantiene contadores de energía con signo:
| Nivel | Potencia RT P |
Acumulador por período avg_p[ch] |
Contador de Wh del componente |
|---|---|---|---|
| BASIC | con signo (negativo = exportación a la red, visible en tiempo real) | cada ventana de 100 ms de la P media se limita a max(P, 0) antes de sumarse al acumulador del período |
monotónico — contabilidad solo de consumo |
| STANDARD (STD) | con signo; también potencia reactiva y aparente | bancos de instantáneas, o diferencias de contadores: la exportación se conserva (importación y exportación se cuentan por separado) | Valor neto con signo (negativo = exportación neta) |
Para más detalles, véase el capítulo 02 · Líneas de módulos. A nivel de componente se usa el mismo manejador rbamp_handle_t independientemente del nivel: rbamp_begin() detecta la línea del módulo (rbamp_line()); las diferencias aparecen en los valores que devuelve el módulo y en las llamadas extra rbamp_std_* que ofrece un módulo STD.
Contabilidad bidireccional en BASIC: rbamp_energy_wh(dev, ch) en el nivel BASIC solo da consumo. Si necesita contabilizar la exportación por separado, muestree la potencia RT rbamp_read_power(dev, 0, &p) a unos 10 Hz y separe usted mismo las muestras positivas y negativas en dos variables acumuladoras. Véase el ejemplo en 06_examples.md (escenario 9, «Medición bidireccional en el lado del maestro»).
Qué hace este componente
esp_timer_get_time().
El componente también se encarga de la contabilidad por período: toma una instantánea, espera a que el módulo se asiente, comprueba que la instantánea es válida e integra los Wh frente al reloj del master (rbamp_read_period_snapshot() y rbamp_energy_wh(), vea 05 · Inicio rápido, Paso 5). La comparación a nivel de registro («sin el componente»), el diagrama de arquitectura, los diagramas de interacción y la tabla de correspondencias están en 09 · Referencia de la API, apéndice «Por dentro».
Registro y Kconfig
A diferencia de la biblioteca Arduino, donde el flujo de registro se configura en tiempo de ejecución (setLogStream(&Serial)), aquí se usa el patrón estándar de ESP-IDF: el componente registra con la etiqueta "rbamp" mediante esp_log. El nivel de registro se compila mediante la opción Kconfig CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, INFO por defecto). Con NONE las cadenas de registro se eliminan del binario por completo.
El filtro en tiempo de ejecución también funciona (mediante esp_log_level_set("rbamp", ...)), pero está limitado desde arriba por el nivel de compilación.
Seis símbolos CONFIG_RBAMP_* están disponibles en idf.py menuconfig → Configuración de componentes [Component config] → cliente rbAmp:
| Símbolo | Finalidad | Predeterminado |
|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
Frecuencia de SCL para el bus compartido | 50000 (50 kHz) |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
tiempo límite de transmisión / recepción | 100 ms |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
intentos de reintento por lectura de un byte | 3 |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
pausa entre intentos de reintento | 5 ms |
CONFIG_RBAMP_DISABLE_ENERGY |
eliminar el acumulador de Wh de la compilación | n |
CONFIG_RBAMP_LOG_LEVEL_* |
nivel de compilación de las cadenas de registro | INFO |
Para más detalles, vea 09 · Referencia de la API, la sección «Configuración en tiempo de compilación».
Lo que viene después
- 02 · Líneas de módulos — qué nivel para qué tarea
- 04 · Cableado — pull-ups, longitud del bus, pinout de la familia ESP32
- 05 · Inicio rápido — su primer proyecto funcionando
- 06 · Ejemplos — recorridos por proyectos IDF listos
- 09 · Referencia de la API: cada función pública
- 10 · Solución de problemas — cuando algo no funciona
Fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/01_overview.md (v1.7.3)