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

05 · Inicio rápido

Un tutorial de cinco minutos: instale el paquete, conecte el módulo, seleccione un sensor y lea su primer valor en tiempo real y su primera instantánea por periodo (Wh). Este tutorial cubre ambos entornos en paralelo: MicroPython (en ESP32 / RP2040 / STM32 / Pyboard) y CPython (en Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).

Para los detalles (pinout de un host concreto, bus multimódulo, elección de un SCT-013 por rango), véanse los capítulos vecinos:

Lo que necesitará

Seguridad

⚠ Seguridad eléctrica. La tensión de red puede matar. Desconecte y bloquee el circuito antes de conectar los terminales L/N o colocar la pinza; que un técnico cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro. Coloque la pinza solo sobre un conductor (L): nunca sobre todo el cable (si abraza L y N, lee ~0). La pinza en sí no tiene contacto eléctrico.

  • Un módulo rbAmp (cualquier línea de módulo; UI1 por simplicidad)
  • Uno de estos hosts:
  • CPython: Raspberry Pi (cualquier modelo) / Orange Pi 5 / Rock Pi 5 / x86 + adaptador USB-I²C

  • MicroPython: ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)

  • Una pinza de CT SCT-013 con la corriente nominal máxima de su instalación (5 A / 10 A / 30 A / 50 A / 100 A)

  • Una alimentación de 5 V para el módulo (desde el USB-5V del host o una fuente externa)
  • Un circuito de CA a medir (una lámpara, un hervidor o un electrodoméstico)

¿Qué camino sigo?

Compruebe dev.is_std (o la etiqueta de SKU en el módulo: véase 02 · Líneas de módulos). Módulo STD: omita los Pasos 4-5 y vaya a 06 · Ejemplos, Escenario 11. Módulo BASIC: siga todos los pasos. El Paso 3 y el Paso 4 son iguales para ambos.

El camino hasta la primera lectura: conecte el módulo, fije el modelo de la pinza y luego lea tensión, corriente y potencia.

Paso 1 — Instalación del paquete

CPython (en una SBC Linux o x86)

Shell
pip install rbamp

(En un sistema Debian/Ubuntu puede usar la alternativa del sistema smbus2, sudo apt install python3-smbus, pero se recomienda smbus2 desde pip, porque admite el gestor de contexto with SMBus(...).)

Verify:

Shell
rbamp --version          # rbamp 1.6.0
rbamp --bus 1 scan       # I²C scan, should show 0x50

MicroPython (en ESP32 y otros)

Shell
mpremote mip install github:rb-amp/rbamp-python

O copie el paquete manualmente:

Shell
mpremote cp -r path/to/rbamp/ :rbamp/

El paquete se instala en /lib/rbamp/ en el dispositivo.

Paso 2 — Cableado

Cuatro cables más DRDY opcional:

Pin de rbAmp Host
VCC +5 V (rango 4.5..5.5 V)
GND GND
SDA SDA de I²C (pin 3 de la RPi, GPIO21 del ESP32, GPIO0/etc. del RP2040)
SCL SCL de I²C (pin 5 de la RPi, GPIO22 del ESP32, GPIO1 del RP2040, etc.)

La alimentación debe ser de 5 V. Las líneas I²C funcionan a lógica de 3.3 V pero toleran 5 V. La placa del módulo ya lleva resistencias pull-up integradas de 4.7 kΩ: para un solo módulo no se necesitan externas.

La tabla completa de pines de cada host está en 04 · Cableado.

La pinza SCT-013 se coloca alrededor solo del conductor de línea (L), con la flecha del cuerpo de la pinza apuntando en el sentido de la corriente hacia la carga. Más detalles en 04 · Cableado.

Conecte la pinza en el cable L con la flecha hacia la carga, y los bornes de referencia de red.

Seguridad

⚠ Seguridad eléctrica. La tensión de red puede matar. Desconecte y bloquee el circuito antes de conectar los terminales L/N o colocar la pinza; que un técnico cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro. Coloque la pinza solo sobre un conductor (L): nunca sobre todo el cable (si abraza L y N, lee ~0). La pinza en sí no tiene contacto eléctrico.

Paso 3 — Primer script (lectura en tiempo real)

Un script mínimo: indique al módulo qué pinza usa (una vez) y luego lea U / I / P / PF. Los códigos de modelo están en el Paso 4; el 3 de abajo es el SCT-013-030. La tabla de líneas de módulo y variantes está en 02 · Líneas de módulos.

Versión de CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

with SMBus(1) as bus:
    with RbAmp(bus, 0x50) as dev:
        # the context manager's __enter__ automatically calls dev.begin()
        # the module variant is detected automatically
        variant = dev.read_variant()
        label = dev.read_label() or "(unset)"
        print(f"Module ready: variant={variant}  label={label!r}")
        # variant codes: see the table in 02 · Module lines
        # Once per installation (saved in the module's flash):
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)   # SCT-013-030, see Step 4
        while True:
            try:
                print(f"U={dev.voltage:.1f}V  "
                      f"I={dev.read_current(0):.3f}A  "
                      f"P={dev.read_power(0):.1f}W  "
                      f"PF={dev.read_power_factor(0):.3f}")
            except RbAmpError as e:
                print("read failed:", e)
            time.sleep(1)

Run:

Shell
python quick_read.py

Versión de MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)   # ESP32 default
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)   # once per installation
    dev.set_ct_model(3)                              # SCT-013-030, see Step 4
    print("Module ready.")
    while True:
        try:
            print("U={:.1f}V  I={:.3f}A  P={:.1f}W  PF={:.3f}".format(
                dev.voltage, dev.read_current(0),
                dev.read_power(0), dev.read_power_factor(0)))
        except RbAmpError as e:
            print("read failed:", e)
        time.sleep(1)

(En MicroPython se usa .format() en lugar de f-strings, por rendimiento y compatibilidad con puertos antiguos; en puertos más recientes las f-strings también funcionan.)

Run:

Shell
mpremote run quick_read.py

Salida esperada con una carga conectada (los valores dependen de su carga):

Text
Module ready.
U=230.4V  I=0.523A  P=119.8W  PF=0.987
Seguridad

U muestra aproximadamente la tensión de red (220-240 V en redes de 230 V). Sin carga, I es ~0 y PF no está definido (puede mostrar nan, 0 o un marcador): la forma exacta no importa mientras la corriente sea cero. Si I se queda en 0.000 A con la carga encendida, compruebe la pinza (un solo conductor, sentido correcto) y el código de modelo, y luego consulte 10 · Solución de problemas.

Paso 4 — Configuración del sensor de corriente

Debe indicar al módulo la clase y el modelo del sensor (lo hace el script del Paso 3). Sin esto, los coeficientes de calibración no se cargan y las lecturas de corriente se quedan en cero. Llame siempre primero a set_sensor_class() y después a set_ct_model(code).

Elija el código que coincida con su pinza:

code Modelo Rango Uso típico
1 SCT-013-005 0..5 A Cargas pequeñas, una sola toma
2 SCT-013-010 0..10 A Frigorífico, lavadora
3 SCT-013-030 0..30 A Alimentación doméstica de hasta ~7 kW
4 SCT-013-050 0..50 A Cargador de VE, calefacción eléctrica
6 SCT-013-020 0..20 A Acometida media, aparatos de 3–4 kW

Más sobre la selección — 03 · Selección del sensor de corriente.

Nota

Estas dos llamadas se hacen una vez en la primera instalación: la elección se guarda en la flash del módulo y sobrevive a un reinicio. El tiempo total es de unos 1.4 segundos (dos escrituras en flash × ~700 ms cada una).

En las siguientes ejecuciones del script no necesita llamar a set_sensor_class() ni a set_ct_model() (el módulo lo recuerda). Volver a llamarlas con el valor que el módulo ya tiene es un no-op.

Paso 5 — Contabilidad de energía (Wh)

El módulo devuelve solo magnitudes instantáneas más la potencia media en un periodo. Los propios Wh los calcula el paquete usando el reloj del maestro (time.monotonic() en CPython, time.ticks_ms() en MicroPython):

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

donde master_dt_s son los segundos entre dos llamadas correctas a dev.read_period_snapshot().

Nota

Espere un periodo completo antes de la primera read_period_snapshot(). begin() ya inicia un periodo, así que una instantánea tomada justo después cubre solo una fracción de segundo y los Wh leerán ~0. Por eso los bucles de abajo duermen 60 s antes.

El contador de Wh se mantiene en memoria. Se reinicia desde 0 tras reiniciar el script o el dispositivo. Para un total absoluto, guarde usted dev.energy.wh(0). En módulos BASIC la exportación no se cuenta (véase 02 · Líneas de módulos). En un módulo STD las mismas llamadas funcionan y el valor es energía neta (la exportación resta); begin() elige la fuente (los contadores de energía del módulo o el banco de latch 0), y el primer periodo empieza en begin(). Los totales de vida propios del módulo están en read_std_energy() (Escenario 11 en 06 · Ejemplos).

Una plantilla mínima de contabilidad periódica (una vez por minuto):

Versión de CPython (medidor por periodos)

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)   # SCT-013-030

    while True:
        time.sleep(60)   # 60-second period

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print(f"avg P over period: {snap.avg_p[0]:.2f} W   "
              f"accumulated: {dev.energy.wh(0):.4f} Wh   "
              f"dt={snap.master_dt_ms} ms")

Versión de MicroPython (medidor de periodos)

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)

    while True:
        time.sleep_ms(60_000)

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print("avg P over period: {:.2f} W   accumulated: {:.4f} Wh   dt={} ms".format(
            snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Nota

Tras el Paso 4, las llamadas set_sensor_class() y set_ct_model() ya se han ejecutado una vez y se han guardado en la flash del módulo; en la plantilla de arriba están para las repeticiones del script: el módulo ignora una llamada repetida con el mismo valor.

Lo que hace read_period_snapshot() por dentro:

  1. Envía al módulo el comando de instantánea de periodo (CMD_LATCH_PERIOD).
  2. Espera 50 ms mientras el módulo prepara la instantánea.
  3. Comprueba el indicador de listo (snap.valid); lee la potencia media o de pico.

  4. Actualiza el contador interno de Wh: dev.energy.wh(ch) += avg_p[ch] × dt / 3600.

  5. Ante una instantánea obsoleta lanza RbAmpStaleError y conserva la marca de tiempo anterior, así que la siguiente instantánea correcta cubre el intervalo completo y los Wh siguen siendo exactos.

dev.begin() inicia él mismo el primer periodo (un cebado) y descarta lo que el módulo acumuló desde el encendido, así que el código de usuario nunca ve esos datos.

Salida esperada:

Text
avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Variante de streaming asíncrono (opcional)

Para aplicaciones con asyncio (CPython) o uasyncio (MicroPython), existe un generador asíncrono dev.stream_period(interval_s=...):

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)

        # Once a minute, with built-in stale handling (skip_stale=True)
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"{snap.avg_p[0]:.2f} W,  {dev.energy.wh(0):.4f} Wh")

asyncio.run(main())

Funciona igual en MicroPython (import uasyncio as asyncio).

Más sobre escenarios asíncronos: 06 · Ejemplos, el escenario «Transmisión de periodos asíncrona».

Paso 6 — Inicio rápido para una flota de N módulos

Este inicio rápido muestra cómo trabajar con un único módulo. El escenario canónico real del paquete son varios módulos en un bus mediante RbAmpFleet (red + N cargas). Para el ejemplo completo, véase el capítulo 06 · Ejemplos, escenario 1 «Red + N cargas: el canon del 80%». Un esqueleto mínimo de flota (CPython):

Python
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    added = fleet.scan()
    print(f"fleet: {added} modules; excluded: {fleet.excluded}")

    while True:
        snaps = fleet.poll_all()
        total_w = fleet.total_power()
        n_ok = sum(1 for snap, info in snaps if info.ok)
        print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
        time.sleep(0.2)

La versión de MicroPython es idéntica: sustituya SMBus(1) por I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).

En el escenario canónico del 80 %, uno de los módulos es un UI1 en la acometida de red (proporciona total_power() y total_energy_wh()) y el resto, I2/I3, son submedidores de corriente. Los detalles y los escenarios avanzados (desagregación red + subcargas, sincronización GC para instantáneas estrechamente sincronizadas, flujo de aprovisionamiento) están en el capítulo 06.

Lo que viene después


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