rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub [Edit on GitHub]

01 · Visión general

Cadena de señal de rbAmp: sensor → módulo → I²C → maestro → nube / Home Assistant

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 RbAmpStaleError y 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

Un módulo en la acometida de red y un módulo por cada subcarga comparten un bus I²C con el maestro, que los sondea a todos con una única llamada de flota.

  • 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 (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.poll_all() sondea todo; el balance mains − Σ(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.

Seguridad

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
Nota

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.

Nota

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)

Python
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

Python
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

Python
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

Python
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_PERIOD y una lectura correcta de la instantánea.
  • Compruebe el indicador valid antes de leer; con una instantánea obsoleta lanza RbAmpStaleError.

  • 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: float de 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

Dónde se sitúa un script Python: script, paquete rbamp, backend I²C y el módulo rbAmp, con la velocidad I²C de cada host.

Text
┌─────────────────────────────────────────────────────┐
│  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.

Jerarquía de excepciones del paquete rbamp: todo error deriva de RbAmpError, que deriva de OSError.

El patrón estándar de Python:

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

Secuencia de transacciones de bus que realiza begin(): leer la versión, detectar la línea del módulo, enviar la instantánea de cebado y devolver el control.

Text
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()

Secuencia de read_period_snapshot(): toma la instantánea del periodo, lee el bloque de instantánea e integra la energía en el maestro para BASIC, o lee los contadores del propio dispositivo para STD.

Text
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


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