01 · Visión general
Qué es rbAmp
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.
Desde el punto de vista del integrador, el módulo se comporta como un esclavo I²C estándar: crea RbAmp(bus, 0x50), llama a dev.begin() y obtiene valores listos para usar mediante propiedades y métodos. El mismo código funciona en MicroPython (con machine.I2C) y en CPython (con smbus2); el backend se selecciona automáticamente según el tipo del objeto de bus.
Términos usados en esta documentación
- Línea de módulo: BASIC o STANDARD (STD), la línea de producto del módulo (véase 02).
- Variante: UI1, UI2, UI3, I1, I2, I3 (y UI5/UI7): cuántos canales de corriente tiene y si el módulo dispone de entrada de tensión.
- Versión de firmware / versión de imagen del módulo: el software dentro del módulo; algunas llamadas STD necesitan una imagen suficientemente reciente.
- Lectura en tiempo real — una lectura instantánea (tensión, corriente, potencia), actualizada por el módulo cada 100 ms.
- Periodo / instantánea: una instantánea congela los totales del periodo transcurrido y empieza el siguiente; una instantánea de periodo es el resultado congelado (potencia media por canal).
- Instantánea obsoleta — el módulo no tenía una instantánea nueva lista; la biblioteca lanza
RbAmpStaleErrory la siguiente buena instantánea cubre todo el intervalo. - Cebado: la primera instantánea que toma
begin(); descarta lo acumulado desde el encendido. - GC (General Call, llamada general): una única trama de difusión I²C que hace que varios módulos tomen su instantánea en el mismo instante.
- DRDY: pin opcional que pulsa cada ~100 ms cuando hay datos RT nuevos.
Un módulo o varios
Un módulo o varios: empiece con un RbAmp; use RbAmpFleet para varios. El paquete Python rbamp funciona con un único módulo y también con un grupo de módulos en un mismo bus I²C. El escenario canónico multimódulo es un módulo maestro en la acometida de red más N módulos en cargas individuales, todos en un bus, gestionados por un único ESP32 / RPi / SBC. La biblioteca ofrece la clase RbAmpFleet: un único objeto a través del cual escanea el bus, sondea todos los módulos en una llamada, obtiene la potencia total y el balance "acometida − Σ(consumidores)", recoge los errores de cada módulo y, cuando hace falta, sincroniza 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 la misma biblioteca: la clase RbAmp es el bloque sobre el que se apoya RbAmpFleet. 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 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.poll_all()sondea todo; el balancemains − Σ(sub_loads)muestra "el resto" (consumo de fondo, cargas no medidas, fugas). -
Una marca de tiempo común del maestro → medición de Wh correcta, sin deriva entre módulos.
Detalle arquitectónico importante. 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 etapa de tensión). En el despliegue canónico, el papel de «contador de red» (medir la energía) lo cumple un único UI1 en la acometida; el papel de submedidor (detalle de corriente por carga) lo cumplen los módulos 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 ("Acometida + N subcargas — 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 de Python | 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 | int, Hz |
50 / 60 Hz (detectado) |
| P promediada por período | float, W |
igual que P |
El valor en tiempo real de la potencia activa P es siempre con signo en cualquier línea de módulo (negativo significa exportación a la red). El comportamiento del valor promediado por periodo (snap.avg_p[ch] en RbAmpPeriodSnapshot) depende de la línea de módulo; véase la sección "Líneas de módulos" más abajo y 02_tiers.md.
Cableado
El módulo se conecta al host 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 |
GND |
común con el host (obligatorio) |
SDA, SCL |
I²C, lógica de 3.3 V, tolerante a 5 V. Pull-ups integradas de 4.7 kΩ |
DRDY |
opcional, colector abierto: BAJO ~10 µs cada ~100 ms |
La dirección por defecto es 0x50 (7 bits, rango de cambio 0x08..0x77). La velocidad recomendada para MicroPython en ESP32 es 50 kHz; para CPython mediante el I²C del kernel suele ser 100 kHz (el patrón de NACK no aparece con la API del kernel de Linux).
Las reglas completas (longitud del bus, recomendaciones de pull-up en un bus multimódulo, diagramas de cableado para RPi / ESP32 / RP2040 / STM32) están en el capítulo 04 · Cableado.
Líneas de módulos (chuleta rápida)
Los módulos BASIC y STANDARD (STD) están en fabricación; STANDARD es compatible con esta biblioteca desde la 1.6.0.
BASIC es una medición unidireccional (solo consumo), con la lógica de un contador mecánico clásico:
| Línea de módulos | Potencia en tiempo real dev.power[ch] |
Acumulador de periodo snap.avg_p[ch] |
Contador de Wh del paquete |
|---|---|---|---|
| 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 — medición solo de consumo |
| STANDARD (STD) | con signo | las mismas llamadas que BASIC; la fuente son los contadores de energía del módulo o el banco de latch 0, elegida en begin(); la energía es neta (la exportación resta) |
dev.energy integra el periodo; los totales propios del módulo: read_std_energy() (véase el capítulo 02) |
Para más detalles, consulte el capítulo 02 · Líneas de módulos. A nivel de paquete se usa la misma clase RbAmp con independencia de la línea de módulo; las diferencias aparecen en los valores que devuelve el módulo.
Medición bidireccional en BASIC: dev.energy.wh(ch) en la línea de módulos BASIC da solo consumo. Si necesita contabilizar la exportación por separado, muestree la potencia RT dev.power[0] (o dev.read_power(0)) a ~10 Hz y separe usted mismo las muestras positivas y negativas en dos variables acumuladoras. Para un ejemplo, véase 06_examples.md, escenario «Medición bidireccional en el lado del maestro».
Qué hace este paquete
La tarea principal es ocultar el intercambio de protocolo y liberar al código de usuario de la rutina de trabajar con registros, orden de bytes y tiempos de estabilización tras los comandos. Además, el paquete calcula la energía (Wh): el módulo devuelve solo la potencia promediada por periodo, y el maestro hace la integración usando time.monotonic() / time.ticks_us().
Sin el paquete (acceso directo a registros mediante smbus2)
import struct
from smbus2 import SMBus, i2c_msg
# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("
Con el paquete
from smbus2 import SMBus
from rbamp import RbAmp
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
u_rms = dev.voltage # property (one call = one transaction)
# or: u_rms = dev.read_voltage()
Lectura de un periodo — sin el paquete
import time, struct
with SMBus(1) as bus:
# Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
bus.write_byte_data(0x50, 0x01, 0x27) # REG_COMMAND, CMD_LATCH_PERIOD
t_latch = time.monotonic()
time.sleep(0.050) # settle
bus.write_byte(0x50, 0x07)
if bus.read_byte(0x50) & 0x01 == 0:
# snapshot is stale — keep the previous t_prev_latch, so the next
# good snapshot covers the full interval
raise SystemExit("stale snapshot")
# ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
# dt_s = time.monotonic() - t_prev_latch
# E_Wh += avg_p * dt_s / 3600
Lectura de un periodo — con el paquete
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
snap = dev.read_period_snapshot() # snapshot + settle + valid + read + Wh tick
print(snap.avg_p[0], "W")
print(dev.energy.wh(0), "Wh")
Internamente, el paquete garantiza:
- Una espera de 50 ms tras
CMD_LATCH_PERIODy una lectura correcta de la instantánea. -
Compruebe el indicador
validantes de leer; con una instantánea obsoleta lanzaRbAmpStaleError. -
Mantener la marca de tiempo anterior ante una instantánea obsoleta, para que la siguiente instantánea válida cubra todo el intervalo y los Wh sigan siendo exactos.
-
Acumulación de energía por canal en doble precisión (CPython:
floatde 64 bits; MicroPython: depende de la compilación, véase 04 · Cableado). -
Carga automática de los coeficientes de calibración al seleccionar el sensor de corriente mediante
dev.set_sensor_class(cls)+dev.set_ct_model(code): el usuario no necesita conocer los registros internos de calibración.
Cuándo usar el paquete y cuándo el acceso directo al bus
| Tarea | Paquete | Acceso directo mediante smbus2 / machine.I2C |
|---|---|---|
| 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 del paquete (por ejemplo, en una base de datos del lado del maestro) |
| Varios módulos en un mismo bus | ✅ (mediante instantánea secuencial + estabilización compartida) | — |
| Medición bidireccional en BASIC | ✅ (mediante lecturas en tiempo real; véase 06_examples.md) | alternativa: su propio bucle de lectura en tiempo real |
| Transmisión asíncrona mediante asyncio / uasyncio | ✅ (async for snap in dev.stream_period()) |
difícil — no hay envoltorio asíncrono integrado |
| Adaptación a otra plataforma | n/a | ✅ véase rbamp-docs (mapa de registros y protocolo) |
Para todas las tareas típicas de las primeras filas, el paquete es la vía indicada.
Arquitectura
┌─────────────────────────────────────────────────────┐
│ User code (.py) │
│ from smbus2 import SMBus │
│ from rbamp import RbAmp, RbAmpSensorClass │
│ with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: │
│ # __enter__ calls dev.begin() itself; │
│ # explicit begin() shown for transparency │
│ dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│ dev.set_ct_model(3) │
│ snap = dev.read_period_snapshot() │
│ dev.energy.wh(0) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Public API of the RbAmp class (rbamp/__init__.py) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Lifecycle: begin / probe / wait_ready │ │
│ │ RT properties: .voltage / .power[ch] / │ │
│ │ .current[ch] / .frequency │ │
│ │ RT methods: read_voltage / read_power / │ │
│ │ read_all │ │
│ │ Period: latch_period / │ │
│ │ read_period_snapshot │ │
│ │ Async: stream_period │ │
│ │ Configuration: set_sensor_class / │ │
│ │ set_ct_model │ │
│ │ Diagnostics: retry_exhaustion_count / │ │
│ │ sanity_reject_count │ │
│ │ Exceptions: RbAmpError → IOError / │ │
│ │ TimeoutError / StaleError / │ │
│ │ ParamError / ModeError / │ │
│ │ VersionError │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Backend selection (inside __init__): │ │
│ │ bus.readfrom_mem → MachineI2CBackend │ │
│ │ bus.read_byte_data → SMBusBackend │ │
│ │ duck-typed → custom (FTDI / mocks) │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Instance state: │ │
│ │ • RbAmpEnergy — Wh accumulator │ │
│ │ • RbAmpSnapshot / RbAmpPeriodSnapshot │ │
│ │ • Time of last snapshot (monotonic) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Backend — native I²C on the host platform: │
│ smbus2 (CPython) / machine.I2C (MicroPython) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ rbAmp module at address 0x50 │
│ • U / I / P / PF measurement pipeline (~100 ms) │
│ • Period accumulator (atomic CMD_LATCH_PERIOD) │
└─────────────────────────────────────────────────────┘
Jerarquía de excepciones
A diferencia de la biblioteca de Arduino (donde los errores se notifican mediante lastError() más un código de retorno) y del componente de ESP-IDF (donde se notifican mediante esp_err_t), el paquete Python usa el patrón clásico de Python: una jerarquía de excepciones.
El patrón estándar de Python:
from rbamp import RbAmp, RbAmpStaleError, RbAmpError
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
# Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
continue
except RbAmpError as e:
log.warning("rbAmp failure: %s", e)
Diagramas de interacción
El flujo de dev.begin()
code RbAmp Backend rbAmp module
│ │ │ │
├─dev.begin()► │ │
│ ├─read_u8(REG_VERSION)► │
│ │ ├──[0x50, 0x03]────────►│
│ │ │◄────────────────ACK───┤
│ │ ├──[read 1 byte]───────►│
│ │ │◄──────────────[0x04]──┤
│ │◄─────── version_byte ─────┤ │
│ │ │ │
│ ├─read_float_le(U_RMS)►(4 single-byte reads) │
│ │ → 226.3 V │ │
│ │ → has_voltage_hw = True │
│ │ │ │
│ ├─write_cmd(LATCH)──►│ │
│ │ ├──[0x50, 0x01, 0x27]──►│
│ │ sleep(50ms) │ │
│ │ │ │
│◄────self────┤ (or raises RbAmpIOError on failure) │
La primera instantánea es un cebado (el módulo devuelve lo acumulado desde el encendido, lo que no sirve para la medición tarifaria). El paquete registra por sí mismo que esta instantánea debe descartarse: el código de usuario nunca la ve.
El flujo de dev.read_period_snapshot()
code RbAmp Backend rbAmp module
│ │ │ │
├─read_period_snapshot()► │ │
│ ├─write_cmd(LATCH)──►│ t_now = time.monotonic()
│ │ │ │
│ │ sleep(50ms) │ │
│ │ │ │
│ ├─is_period_valid()─►│ │
│ │ → True │ │
│ │ │ │
│ ├─read_float_le(AVG_P0)►(4 reads) │
│ ├─read_float_le(MAX_P0)►(4 reads) │
│ ├─read_u32_le(LATCH_MS)►(4 reads) │
│ │ │ │
│ │ dt = t_now − last_latch │
│ │ energy.wh[ch] += avg_p[ch] × dt / 3600 │
│ │ last_latch = t_now │
│ │ │ │
│◄─snap──────┤ │ │
La instantánea atómica en el lado del módulo garantiza que cada medida dentro de un 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 trabajo de acceso directo:
API directa (smbus2 / machine.I2C) |
Equivalente del paquete |
|---|---|
Lectura manual de 4 bytes + struct.unpack |
dev.voltage (propiedad) o dev.read_voltage() |
read_byte por canal × 4 |
dev.power[ch] (_ChannelProxy) o dev.read_power(ch) |
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) |
dev.latch_period(); time.sleep(0.05) (o directamente dev.read_period_snapshot()) |
Comprobando read_byte(0x07) & 1 |
dev.is_period_valid() o el campo snap.valid |
Fórmula manual E_Wh += avg_p × dt / 3600 |
dev.energy.wh(0): se actualiza automáticamente |
| Configuración manual del sensor de corriente mediante la API de registros directa | dev.set_sensor_class(cls) + dev.set_ct_model(code): los preajustes de fábrica se cargan automáticamente |
Lo que viene después
- 02 · Líneas de módulos — qué línea de módulo sirve para cada tarea
-
04 · Cableado: resistencias pull-up, longitud del bus, cableado por host (RPi / ESP32 / RP2040 / STM32)
-
05 · Inicio rápido — el primer script funcional para ambos backends
-
06 · Ejemplos: recorrido por escenarios listos para usar
-
09 · Referencia de la API — cada clase, método, propiedad y excepción pública
-
10 · Solución de problemas — cuando algo no funciona
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/01_overview.md (v1.6.1)