02 · Líneas de módulos
Qué es una línea de módulos
Los módulos rbAmp vienen en dos líneas: BASIC y STANDARD (STD). Una línea de módulos es un paquete completo de revisión de hardware y firmware, no un indicador de software. Pasar de una línea a otra requiere un cambio físico de SKU, no una actualización de firmware.
Desde la perspectiva del paquete y del código de usuario: una sola clase RbAmp sirve a todas las líneas de módulos, y las lecturas comunes (voltage, current, power, power_factor, frequency) funcionan en todos ellos. La línea del módulo se detecta automáticamente en begin(). Los módulos STANDARD (STD) exponen además las llamadas exclusivas de STD (energía en el dispositivo y similares, véase abajo); llamar a una de ellas en un módulo BASIC lanza RbAmpNotSupportedError.
Estado actual
Esta biblioteca admite módulos BASIC y STANDARD (STANDARD desde la 1.6.0).
| Línea de módulos | Envío |
|---|---|
| BASIC | ✅ sí |
| STANDARD (STD) | ✅ sí (compatible con esta biblioteca desde la 1.6.0) |
BASIC — línea de módulos de medición de consumo de nivel de entrada
Hardware
Una vía analógica optimizada en coste, adecuada para cargas domésticas típicas. El módulo incluye una etapa analógica de entrada aislada, un regulador de potencia integrado y calibración de fábrica en la memoria flash.
Comportamiento del firmware
La lógica de un contador mecánico de disco clásico: la cuenta solo avanza; la exportación a la red no se resta.
Las tres "capas" de valores de potencia activa se comportan de forma distinta:
| Señal | Significado | Comportamiento en BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
potencia instantánea en tiempo real, actualización ~100 ms | con signo: un valor negativo se ve en tiempo real (exportación) |
snap.avg_p[ch] (de dev.read_period_snapshot()) |
potencia media durante el periodo | cada ventana de 100 ms de P media se limita a max(P, 0) antes de sumarse al acumulador del período |
dev.energy.wh(ch) |
Wh acumulados por el paquete | monótono: solo consumo; la exportación no se cuenta |
Dicho de otro modo: el usuario ve la exportación en la lectura en tiempo real, pero no aparece en el contador de Wh del paquete en BASIC.
Aplicaciones típicas
-
Hogares sin generación propia (sin paneles solares, aerogeneradores ni sistemas de baterías)
-
Submedición de cargas puramente consumidoras (calentadores de agua, motores, electrodomésticos)
-
Monitorización del consumo en edificios donde no se requiere medición bidireccional
Medición bidireccional en BASIC (lado del maestro)
Si necesita registrar la exportación a la red por separado en un módulo BASIC, hágalo en el lado del maestro. La potencia en tiempo real dev.power[0] lleva signo (o el método equivalente dev.read_power(0)), así que:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
t_now = time.monotonic()
dt_s = t_now - t_prev
t_prev = t_now
try:
p = dev.read_power(0)
except RbAmpIOError:
continue
dwh = p * dt_s / 3600.0
if p >= 0.0:
consume_wh += dwh
else:
export_wh += -dwh
En MicroPython, sustituya time.monotonic() por time.ticks_ms() / time.ticks_diff() (más preciso y económico en RAM en plataformas embebidas) y time.sleep(0.1) por time.sleep_ms(100). En CPython no hay cambios.
Un ejemplo completo del patrón está en 06_examples.md, en el escenario «Medición bidireccional en el lado del maestro», así como en los archivos fuente examples_upy/07_bidirectional_energy.py y examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — línea de módulos en producción
Los módulos STANDARD son una línea de módulos comercializada que esta biblioteca admite desde la versión 1.6.0. Usan un mapa de registros diferente (de 16 bits) al de BASIC; la biblioteca oculta la diferencia: la misma clase RbAmp, el mismo cableado I²C y la misma dirección, y los mismos lectores comunes.
Lo que añade la biblioteca en un módulo STD:
-
Energía en el propio dispositivo:
dev.read_std_energy()devuelve los contadores de vida útil del propio módulo: energía activa de importación / exportación / neta y reactiva, con resolución en Wh, mWh y µWh, con cifras por canal.RbAmp.std_energy_delta(prev, now)da la energía usada entre dos lecturas y es seguro ante cortes de alimentación. Para estos contadores no integra usted la potencia en el maestro. -
Medición por periodo:
read_period_snapshot()y las demás llamadas de periodo funcionan igual que en BASIC.begin()elige la fuente: los contadores de energía del módulo (el periodo es la diferencia de dos lecturas; no se envía ningún comando de latch) o, en un módulo solo con bancos de latch, el banco de latch 0. La energía es neta (la exportación resta). -
Bancos de latch (módulos que los notifican):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Funciones auxiliares multifase:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(solo STD; en BASIC esta biblioteca no expone la potencia reactiva),dev.read_apparent(ch). -
Corriente de arranque:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Bloques completos:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Algunas llamadas STD necesitan una imagen de módulo suficientemente reciente (contadores de energía en micro-unidades, ángulos de tensión, corriente de arranque). Si el módulo no ofrece una, la llamada lanza
RbAmpNotSupportedError(«no disponible»). -
Use
dev.is_stdpara bifurcar en el código de la aplicación. -
La configuración de clase de sensor y modelo de pinza, el reinicio y el cambio de dirección, los registros de identidad, el canal de errores/eventos, los auxiliares de flota y
wait_ready()son solo de BASIC; en un módulo STD lanzanRbAmpNotSupportedError. -
Las funciones de energía en el dispositivo, ángulo y corriente de arranque están validadas en CPython (
smbus2). La ruta de 16 bits de MicroPython está implementada pero aún no validada en hardware: para estas funciones, prefiera CPython hasta que una nota de versión diga lo contrario.
Firmas completas: 09 · Referencia de la API.
Cómo detectar la línea de módulo en tiempo de ejecución
En el firmware actual no hay un registro explícito de «línea de módulo». Hay indicadores indirectos disponibles a través de las propiedades del handle:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std indica la línea de módulo (STD frente a BASIC). Los demás indicadores (versión de firmware, número de canales, presencia de sensor de tensión, variante) describen el módulo, pero no identifican la línea. dev.read_variant() es el byte de variante BASIC; use la etiqueta SKU de la carcasa del módulo como fuente de verdad del producto.
Dónde se marcan en la documentación los puntos que dependen de la línea de módulo
En el texto del paquete y en la documentación canónica, las funciones que dependen de la línea de módulo se marcan explícitamente, por ejemplo:
— esta llamada no está disponible en un módulo BASIC.
O, al contrario, comportamiento exclusivo de BASIC:
: el contador dev.energy.wh(ch) es monótono: la exportación a la red no se cuenta. Para la medición bidireccional, véase el escenario "Medición bidireccional en el lado del maestro" en 06_examples.md, o use un módulo STANDARD, donde la energía del periodo es neta y dev.read_std_energy() tiene contadores separados de importación y exportación.
Qué sigue
-
03 · Selección de sensor de corriente: qué SCT-013 para cada tarea
-
04 · Cableado — particularidades de hardware de cada host (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Ejemplos: escenarios para BASIC, incluida la medición bidireccional en el lado del maestro
-
09 · Referencia de la API: la API pública completa
Fuente y incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/02_tiers.md (v1.6.1)