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:
-
04 · Cableado: detalles de hardware y tablas de pines por host
-
03 · Selección del sensor de corriente — qué modelo SCT-013 usar y por qué
Lo que necesitará
⚠ 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.
Paso 1 — Instalación del paquete
CPython (en una SBC Linux o x86)
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:
rbamp --version # rbamp 1.6.0
rbamp --bus 1 scan # I²C scan, should show 0x50
MicroPython (en ESP32 y otros)
mpremote mip install github:rb-amp/rbamp-python
O copie el paquete manualmente:
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.
⚠ 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
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:
python quick_read.py
Versión de MicroPython
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:
mpremote run quick_read.py
Salida esperada con una carga conectada (los valores dependen de su carga):
Module ready.
U=230.4V I=0.523A P=119.8W PF=0.987
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.
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):
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().
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)
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)
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))
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:
- Envía al módulo el comando de instantánea de periodo (
CMD_LATCH_PERIOD). - Espera 50 ms mientras el módulo prepara la instantánea.
-
Comprueba el indicador de listo (
snap.valid); lee la potencia media o de pico. -
Actualiza el contador interno de Wh:
dev.energy.wh(ch) += avg_p[ch] × dt / 3600. - Ante una instantánea obsoleta lanza
RbAmpStaleErrory 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:
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=...):
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):
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
- 01 · Descripción general: qué es rbAmp y qué hace el paquete
- 02 · Líneas de módulos — qué línea de módulo sirve para cada tarea
-
06 · Ejemplos — escenarios de trabajo: red + N subcargas (el canon del 80 %), flujo de aprovisionamiento, multicanal de tipo mixto, sincronización GC de flota, MQTT, sueño profundo y streaming asíncrono
-
07 · Integraciones DIY: Home Assistant / Node-RED / OpenHAB
-
08 · Integraciones en la nube — AWS IoT / Azure / GCP / InfluxDB
-
09 · Referencia de la API — la API pública completa (incluidos
RbAmpFleet+ multicanal + modelo de errores v1.3 + identidad y aprovisionamiento) -
10 · Solución de problemas: si algo no funciona (el bloqueo i2c-hang de MicroPython@ESP32 en tres capas, latch_ms es un temporizador de diagnóstico, RbAmpStaleError por el ancla de retención del maestro)
Fuente y incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/05_quickstart.md (v1.6.1)