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

02 · Líneas de módulos

Las líneas de módulos BASIC y STANDARD (STD) y lo que aporta cada una.

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)

BASIC cuenta solo el consumo en el módulo, con la exportación gestionada en el maestro, mientras que STD mantiene contadores acumulados en el propio dispositivo.

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:

Python
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_std para 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 lanzan RbAmpNotSupportedError.

  • 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

Cómo saber en tiempo de ejecución si el módulo conectado es BASIC o STANDARD (STD).

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:

Python
# 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
Nota

: 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:

Solo STD

— esta llamada no está disponible en un módulo BASIC.

O, al contrario, comportamiento exclusivo de BASIC:

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


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