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

09 · Referencia de API

Mapa de registros del módulo: el espacio de direcciones de la página 0, de 0x00 a 0xFF

Instantánea atómica de periodo: una sola escritura cierra el periodo actual y abre el siguiente

La API pública completa del paquete rbamp. Fuente — __init__.py (reexportaciones), _rbamp_core.py (la clase principal RbAmp), _snapshot.py (estructuras POD + jerarquía de excepciones), _energy.py (acumulador de Wh), _registers.py (constantes generadas automáticamente).

Este capítulo es una referencia: firmas, valores devueltos, efectos secundarios y casos límite. Para ejemplos de trabajo vaya a 06 · Ejemplos; para un inicio rápido, véase 05 · Inicio rápido.

Importaciones

Python
from rbamp import (
    RbAmp,                     # main class
    RbAmpEnergy,               # Wh accumulator (accessed via dev.energy)
    RbAmpSnapshot,             # RT-block dataclass-style
    RbAmpPeriodSnapshot,       # period snapshot dataclass-style
    RbAmpSensorClass,          # sensor-class enum
    TOPOLOGY_SINGLE, TOPOLOGY_SPLIT_PHASE, TOPOLOGY_THREE_PHASE,
    TOPOLOGY_FIVE_CH, TOPOLOGY_SEVEN_CH,
    topology_name,             # helper: int → topology name
    # STD module line (1.6.0)
    RbAmpStdEnergy, RbAmpStdVoltage, RbAmpStdChannel,
    RbAmpStdConfig, RbAmpStdHealth,   # value objects
    std_energy_delta,          # energy between two read_std_energy() snapshots
    phase_seq_name,            # helper: phase-sequence code → name
    PHASE_SEQ_NA, PHASE_SEQ_FORWARD, PHASE_SEQ_REVERSE, PHASE_SEQ_ABNORMAL,
    # Exception hierarchy
    RbAmpError,                # base class of all errors
    RbAmpIOError,
    RbAmpTimeoutError,
    RbAmpNotReadyError,
    RbAmpStaleError,
    RbAmpParamError,
    RbAmpModeError,
    RbAmpVersionError,
    RbAmpNotSupportedError,    # call not available on this module / firmware
    # Metadata
    __version__,               # "1.6.0"
    __protocol_version__,      # 0x04 (RBAMP_PROTOCOL_VERSION)
    REGISTERS, COMMANDS,       # raw protocol constants (advanced use)
)

Importación mínima para una aplicación típica:

Python
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError

Modismos generales

La API sigue los patrones estándar de Python:

  • Una clase para cada línea de módulo: la misma clase RbAmp sirve a los módulos BASIC y STANDARD (STD). La línea se detecta automáticamente en begin() (véase Línea de módulos STD); nunca la elige usted.

  • Basada en clases: la clase principal RbAmp lo gestiona todo: lecturas RT, periodo, configuración, diagnósticos. El handle mantiene internamente el backend y el acumulador de energía.

  • Gestor de contexto: with RbAmp(bus, addr) as dev:: el idioma recomendado. __enter__ llama automáticamente a dev.begin().

  • Propiedades para lecturas RT: dev.voltage, dev.frequency: una propiedad = una transacción I²C. Las propiedades indexadas por canal pasan por _ChannelProxy: dev.current[ch], dev.power[ch], dev.power_factor[ch].

  • Métodos para lecturas indexadas por canal: dev.read_current(ch), dev.read_power(ch). Totalmente equivalentes a la forma de propiedad: use la que le resulte más cómoda.

  • Excepciones para los errores: todo error es una subclase de RbAmpError. El patrón estándar de Python try / except (no last_error() más un código de retorno).

  • Generador asíncrono para el streaming periódico: async for snap in dev.stream_period(interval_s=...).

Tipos

RbAmp

Python
class RbAmp:
    def __init__(self, bus, addr: int = 0x50): ...

La clase principal. Una instancia por dispositivo esclavo. El bus es cualquier objeto con una de las firmas de API "conocidas": smbus2.SMBus, machine.I2C o un backend personalizado (véase 04 · Hardware).

El backend se selecciona automáticamente en el primer acceso al bus:

método del objeto de bus Backend
bus.readfrom_mem, bus.writeto_mem MachineI2CBackend (MicroPython)
bus.read_byte_data, bus.write_byte_data SMBusBackend (CPython + smbus2)
bus.read_byte, bus.register_acks, bus.now_ms ya envueltos (mocks de prueba, adaptadores FTDI)

Si ninguna firma coincide, se lanza RbAmpParamError con una descripción.

Jerarquía de excepciones

Todo error del paquete es una subclase de RbAmpError, que a su vez hereda de OSError (no de Exception a secas). Esto significa que el código existente con manejadores except OSError: sigue capturando los errores de rbAmp sin ninguna reescritura: es la convención estándar de Python para drivers de E/S de hardware.

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

Nota

: RbAmpParamError hereda de RbAmpError + ValueError en CPython (herencia múltiple). En MicroPython, donde la herencia múltiple no es compatible con todos los puertos, recurre a herencia simple. Desde el punto de vista del usuario, try / except RbAmpParamError funciona igual. Pero try / except ValueError solo captura en CPython: en MicroPython ese manejador no captura el error. El código que depende de un comportamiento multiplataforma debe capturar RbAmpParamError explícitamente.

Uso estándar:

Python
try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # period not ready yet — the master timestamp was committed by the package
    continue
except RbAmpIOError as e:
    log.warning("bus failure: %s", e)
except RbAmpError as e:
    log.error("unexpected: %s", e)

RbAmpSensorClass

Python
class RbAmpSensorClass(IntEnum):
    UNSET       = 0   # factory value after reset
    SCT_013     = 1   # SCT-013 series (shipping default)
    WIRED_CT    = 2   # factory-fitted wired CT (module ships paired)
    BUILTIN_CT  = 3   # factory-fitted built-in CT (module ships paired)
Nota

: en CPython se usa IntEnum de la biblioteca estándar enum. En puertos de MicroPython sin módulo enum, se usa un sustituto de clase simple con los mismos valores de miembro. Desde el punto de vista del usuario las dos formas son idénticas: dev.set_sensor_class(RbAmpSensorClass.SCT_013) o dev.set_sensor_class(1), ambas funcionan.

SCT_013 es la clase que se selecciona en un módulo con pinzas SCT-013 montadas por el usuario. WIRED_CT y BUILTIN_CT describen módulos que se entregan emparejados de fábrica con su sensor: set_sensor_class() y set_ct_model*() se niegan a cambiar un módulo así (RbAmpModeError, véase protección de lectura antes de escritura). Los valores fuera de 0..3 lanzan RbAmpParamError.

RbAmpSnapshot

Devuelto por dev.read_all(). Una clase Python simple (no un @dataclass, por compatibilidad con MicroPython). Todos los campos en unidades SI.

Python
class RbAmpSnapshot:
    voltage:        float       # V — RMS voltage
    voltage_peak:   float       # V — peak voltage
    current:        list        # [ch0, ch1, ...] — RMS current per channel, A
    current_peak:   list        # [ch0, ch1, ...] — peak current, A
    power:          list        # [ch0, ch1, ...] — active power (signed), W
    power_factor:   list        # [ch0, ch1, ...] — dimensionless, −1..+1
    frequency:      float       # Hz
    topology:       int         # TOPOLOGY_* constant
    channels:       int         # number of valid channels (1..3, or 5 / 7 on UI5 / UI7)
    has_voltage_hw: bool        # True if a voltage sensor is present

Los canales no usados (más allá de channels) se rellenan con ceros.

RbAmpPeriodSnapshot

Devuelto por dev.read_period_snapshot(). La primitiva de contabilidad de energía.

Python
class RbAmpPeriodSnapshot:
    avg_p:        list   # [ch0, ch1, ...] — average P over the period, W (all channels)
    max_p:        float  # peak instantaneous power on channel 0
    latch_ms:     int    # period duration (device's view)
    master_dt_ms: int    # master wall-clock dt since the last snapshot
    valid:        bool   # True if the snapshot-ready flag was set
    avg_p_total:  float  # STD: total average P over the period, W (0.0 on BASIC)
    wh_net:       float  # STD: net energy over the period, Wh (0.0 on BASIC)
    module_restarted: bool  # STD counter source: the module restarted during the period
Nota

Para la integración de energía, use master_dt_ms, no latch_ms: latch_ms es un temporizador de diagnóstico del módulo.

Constantes de topología

Python
TOPOLOGY_SINGLE      = 1   # 1 current channel (UI1 / I1)
TOPOLOGY_SPLIT_PHASE = 2   # 2 current channels (UI2 / I2)
TOPOLOGY_THREE_PHASE = 3   # 3 current channels (UI3 / I3)
TOPOLOGY_FIVE_CH     = 5   # 5 current channels + voltage (UI5)
TOPOLOGY_SEVEN_CH    = 7   # 7 current channels + voltage (UI7)

topology_name(topology: int) -> str   # 1 → "SINGLE", 2 → "SPLIT_PHASE", ...

Ciclo de vida

RbAmp(bus, addr=0x50)

Constructor. La resolución del backend ocurre en __init__. No se genera tráfico I²C hasta begin().

Parámetro Descripción
bus Objeto de bus I²C (smbus2.SMBus, machine.I2C, o un envoltorio)
addr Dirección de esclavo de 7 bits. Rango 0x08..0x77, por defecto 0x50

Lanza: RbAmpParamError si el objeto de bus no se reconoce o si addr está fuera de rango.

dev.begin()

Sondea el dispositivo, detecta la línea del módulo, guarda en caché la topología y prepara el comando de instantánea.

Detección de la línea de módulo (1.6.0). begin() comprueba primero si el módulo es un módulo STD (mapa de registros de 16 bits). Si lo es, el manejador pasa al modo STD (dev.is_std pasa a True, dev.channels y dev.has_voltage_hw se obtienen del módulo) y begin() termina. Si no, se ejecuta la secuencia BASIC de abajo. Esto requiere un backend de bus capaz de transacciones de 16 bits; en caso contrario el módulo se trata como BASIC.

Secuencia BASIC:

  1. Lee REG_VERSION: lanza RbAmpIOError ante un NACK y RbAmpVersionError si se devuelve 0x00 / 0xFF.

  2. Almacena en caché la topología (en el firmware actual, begin() no hace autosondeo; usa la pista del constructor).

  3. Lee U_rms para determinar si hay un sensor de tensión (umbral 1.0 V).

  4. Escribe CMD_LATCH_PERIOD (cebado) y espera 50 ms. La primera instantánea tras el encendido se descarta.

  5. Guarda time.monotonic() (o time.ticks_ms() en uPy) para la posterior integración de energía.

En un módulo BASIC con pinzas SCT-013, begin() también evalúa la corrección del cambio de calibre SCT-013.

Idempotente: seguro de llamar repetidamente.

Gestor de contexto

Python
with RbAmp(bus, 0x50) as dev:
    # dev.begin() has already been called in __enter__
    ...
# __exit__ — no-op (bus closing is the caller's responsibility)

El idioma recomendado. El __exit__ del paquete NO cierra el bus: gestionar el objeto de bus sigue siendo tarea del llamador (el patrón típico es with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: anidado).

dev.probe() -> bool

Una comprobación ligera de vida. Una única lectura de REG_VERSION sin efectos secundarios.

Devuelve: True si el esclavo respondió con ACK y notificó una versión compatible; False en otro caso. No lanza excepciones; pensado para escenarios de sondeo.

dev.wait_ready(timeout_ms=1000) -> None

Sondea el indicador de listo del módulo hasta que se activa. Útil tras encender: el módulo puede necesitar hasta 100 ms para su primera ventana de tiempo real.

Lanza: RbAmpTimeoutError si el bit no aparece antes de que transcurra timeout_ms.

Propiedades: estado del handle

Python
dev.firmware_version: int      # REG_VERSION — opaque byte
dev.topology:         int      # TOPOLOGY_* constant
dev.topology_name:    str      # "SINGLE" / "SPLIT_PHASE" / "THREE_PHASE"
dev.channels:         int      # 1..3 (BASIC), 5 / 7 on UI5 / UI7, or the STD module's channel count
dev.is_std:           bool     # True if begin() detected an STD module
dev.has_voltage_hw:   bool     # True if begin() detected U_rms > 1.0
dev.address:          int      # 7-bit I²C address (updated after commit_address_change)

firmware_version es una propiedad en vivo: cada lectura accede al bus (una lectura de un byte de REG_VERSION). Guárdela en caché en la aplicación si la sondea en un bucle intensivo: fw = dev.firmware_version una vez tras begin(). Si aún no se ha llamado a begin(), firmware_version lanza RbAmpIOError (el módulo puede responder con NACK mientras el manejador está "frío").

Las demás propiedades (topology, channels, has_voltage_hw, address) se guardan en caché en el manejador y devuelven los valores almacenados tras begin() sin acceder al bus.

Lecturas en tiempo real (bloque RT, actualización cada 100 ms)

Todos los métodos lanzan RbAmpIOError ante un fallo de comunicación (NACK tras reintento o rechazo por filtro de validez) o RbAmpParamError ante un argumento no válido.

Las ventanas de medida de 100 ms se suceden sin pausa, DRDY pulsa una vez por ventana y el maestro lee el bloque de resultado atómico.

Propiedades

Python
dev.voltage         -> float   # V — RMS voltage
dev.voltage_peak    -> float   # V — peak voltage
dev.frequency       -> float   # Hz — mains frequency

Indexado por canal a través de _ChannelProxy: admite indexación [ch] e iteración:

Python
dev.current         # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak    # _ChannelProxy
dev.power           # _ChannelProxy
dev.power_factor    # _ChannelProxy

Usage:

Python
i0 = dev.current[0]                       # a single channel
for i in dev.current:                      # iterate over all valid channels
    print(i)
total = sum(p for p in dev.power)          # sum of all channels

len(dev.current) es igual a dev.channels.

Métodos (totalmente equivalentes a la forma de propiedad)

Python
dev.read_voltage(phase=0)         -> float
dev.read_voltage_peak(phase=0)    -> float
dev.read_current(ch=0)            -> float
dev.read_current_peak(ch=0)       -> float
dev.read_power(ch=0)              -> float       # signed
dev.read_power_factor(ch=0)       -> float
dev.read_frequency()              -> float

Lectura única de todo el bloque en tiempo real

Python
dev.read_all()  -> RbAmpSnapshot

Equivale a las lecturas consecutivas de read_voltage + read_voltage_peak + read_current(0..N) + read_current_peak(0..N) + read_power(0..N) + read_power_factor(0..N) + read_frequency. Los canales no usados (más allá de channels) se rellenan con ceros.

Lanza: RbAmpIOError si falla alguna de las lecturas parciales.

Los lectores comunes — voltage, voltage_peak, current, current_peak, power, power_factor, frequency y sus formas read_* — funcionan en todas las líneas de módulo. En un módulo STD, phase en read_voltage() / read_voltage_peak() selecciona la entrada de tensión (0..n_voltage-1); en un módulo BASIC solo es válido phase=0.

Línea de módulos STD (1.6.0)

Seguridad

⚠️ Estado de validación. Las funciones de energía en el propio dispositivo, ángulo de tensión y corriente de arranque están validadas en CPython (smbus2). Las mismas llamadas están implementadas para MicroPython (machine.I2C), pero la ruta de 16 bits de MicroPython aún no está validada en hardware: para estas funciones en el dispositivo, prefiera CPython hasta que una nota de versión diga lo contrario. Las lecturas comunes (dev.voltage, dev.current[ch], dev.power[ch], instantáneas de periodo) funcionan en todos los hosts compatibles en cualquier caso.

Una única clase RbAmp sirve a ambas líneas de módulo. begin() detecta la línea automáticamente; dev.is_std es True en un módulo STD. Se usan el mismo cableado I²C y la misma dirección (véase 04 · Hardware).

  • Los lectores comunes (voltage, current, power, power_factor, frequency) funcionan en cualquier módulo.

  • Las llamadas de esta sección son exclusivas de STD. En un módulo BASIC lanzan RbAmpNotSupportedError.

  • Algunas llamadas STD también requieren una imagen de módulo lo bastante reciente (energía en el dispositivo, contadores de micro-unidades, ángulos de tensión, corriente de arranque). Si el módulo no las proporciona, la llamada lanza RbAmpNotSupportedError ("no disponible").

  • Las llamadas de periodo (latch_period, read_period_*, stream_period) y el acumulador dev.energy funcionan en un módulo STD: véase «Contabilidad por periodos» más abajo. Los totales de vida propios del módulo son read_std_energy().

  • Las llamadas de configuración del sensor (set_sensor_class, set_ct_model, set_ct_model_ch, set_ct_model_ch_force, read_ct_model_ch, read_sensor_class), reset, factory_reset, el par de cambio de dirección, los registros de identidad (firmware_version, read_variant, read_capability, read_product_id, read_uid, read_label, set_label, read_seq_digest), el canal de errores y eventos (read_last_error, read_event_flags, clear_event_flags, has_error, clear_error), los ayudantes de flota (read_fleet_config, enable_gc, set_group_id, read_group_id, read_gc_tick), read_period_latch_ms y wait_ready son solo de BASIC: en un módulo STD lanzan RbAmpNotSupportedError antes de enviar nada al bus.

Python
dev.is_std        -> bool   # True on an STD module (set by begin())
dev.std           -> object # internal STD client (advanced use) or None on BASIC

Lectores

Python
dev.read_std_voltage(phase=0)    -> RbAmpStdVoltage   # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0)  -> (float, bool)     # (degrees, valid)
dev.read_phase_sequence()        -> int               # 0..3
dev.read_std_channel(ch=0)       -> RbAmpStdChannel   # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0)         -> RbAmpStdChannel   # totals block k (0 = grand total)
dev.read_reactive(ch=0)          -> float             # var
dev.read_apparent(ch=0)          -> float             # VA
dev.read_std_config()            -> RbAmpStdConfig
dev.read_std_health()            -> RbAmpStdHealth
  • read_voltage_angle(phase) — ángulo de fase de la tensión respecto a la fase 0, devuelto como (degrees, valid). valid es False en un módulo de una sola tensión o en una imagen de módulo que no informa ángulos.

  • read_phase_sequence() — código de secuencia de fases: PHASE_SEQ_NA (0, no disponible), PHASE_SEQ_FORWARD (1), PHASE_SEQ_REVERSE (2), PHASE_SEQ_ABNORMAL (3). phase_seq_name(code) devuelve el nombre en texto. Lanza RbAmpNotSupportedError en un módulo BASIC o en una imagen de módulo que no lo informa.

  • read_reactive(ch) / read_apparent(ch): potencia reactiva en var y potencia aparente en VA para un canal. Solo módulos STD; en un módulo BASIC lanzan RbAmpNotSupportedError (en BASIC esta biblioteca no expone la potencia reactiva).

  • read_std_totals(k): bloque de totales k; k=0 es el total general. Los totales por fase dependen de la versión del mapa de registros del módulo.

  • read_std_config() / read_std_health(): bloques de configuración y de estado/salud.

Objetos de valor

Clases simples (no @dataclass), todas reexportadas desde rbamp.

Clase Campos
RbAmpStdVoltage u_rms, u_peak, thd_u, angle_deg, angle_valid
RbAmpStdChannel i_rms, i_peak, p, q, s, pf, thd_i, pf1, q1
RbAmpStdConfig sensor_class, ct_model, tier, i2c_addr, rate_ms, harmonics, start_ua, start_ua_supported
RbAmpStdHealth status, cal_ok, sensor_ok, mains_ok, time_valid, nvm_fault, maint, frame_count, crc_errors, lta_status, lta_src, cal_src, group_status, ring_drop, lost_frames, uptime_s, reset_cause, boot_count
RbAmpStdEnergy véase abajo

dev.read_std_energy() -> RbAmpStdEnergy

Instantánea de energía de vida en el propio dispositivo. Requiere un módulo que ofrezca energía en el dispositivo; si no, RbAmpNotSupportedError.

RbAmpStdEnergy contiene:

Grupo Campos
Activa, Wh act_import_wh, act_export_wh, act_net_wh
Activa, mWh act_import_mwh, act_export_mwh, act_net_mwh
Activa, µWh act_import_uwh, act_export_uwh, act_net_uwh
Reactiva rea_import_varh, rea_export_varh; µvarh: rea_import_uvarh, rea_export_uvarh
Por canal channels (número de entradas válidas); ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[]
Contabilidad generation, uptime_s, group_status
Indicadores de procedencia fine, fine_reactive

Los campos µWh / µvarh siempre se rellenan. Cuando la imagen del módulo no ofrece contadores más finos, se escalan a partir de los más gruesos, y fine (activa) / fine_reactive valen False; lea el indicador si necesita saber de dónde viene el valor.

RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)

Energía consumida entre dos instantáneas de read_std_energy() (método estático; también exportado como std_energy_delta). Seguro ante cortes de alimentación.

  • module_restarted es True cuando now.uptime_s < prev.uptime_s.
  • delta es un RbAmpStdEnergy con el incremento de cada campo, o None cuando el contador generation ha cambiado (las dos lecturas no son comparables).

  • Un contador que vuelve algo por debajo de la lectura anterior (reanudación tras un corte de corriente) se fija a 0; net es siempre importación − exportación de las partes recortadas.

  • Las entradas por canal solo se rellenan cuando ambas instantáneas tienen el mismo número de canales.

Python
prev = dev.read_std_energy()
time.sleep(60)
now = dev.read_std_energy()
delta, restarted = RbAmp.std_energy_delta(prev, now)
if delta is not None:
    print(delta.act_import_wh, "Wh imported in this interval")

Corriente de arranque y configuración

Python
dev.get_start_current()     -> int    # µA, 0 = off
dev.set_start_current(ua)   -> None
dev.save_config()           -> None   # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch)    -> None   # set the module's clock
  • get_start_current() — la corriente de arranque de energía en µA (0 = desactivada).

  • set_start_current(ua): por debajo de esta corriente por canal, el módulo no cuenta la energía en importación/exportación; las lecturas en vivo (I, P, Q) no se ven afectadas. El valor se aplica de inmediato; llame a save_config() para conservarlo tras un reinicio. Un valor no admitido lanza RbAmpParamError antes de escribir nada en el bus. El valor debe ser 0 (desactivado) o un múltiplo de 10 µA dentro del rango admitido.

  • save_config() — persiste la configuración STD escribible. Bloqueante.

  • set_time(unix_epoch): fija el reloj del módulo a partir de una época Unix; una época anterior a 2020 lanza RbAmpParamError. Vuelva a fijar la hora tras un reinicio del módulo (read_std_health().time_valid es False hasta que se fija el reloj).

  • get_start_current() / set_start_current() lanzan RbAmpNotSupportedError en una imagen de módulo que no ofrece el ajuste de corriente de arranque; RbAmpStdConfig.start_ua_supported indica si lo ofrece.

Bancos de latch

Un módulo STD que notifica bancos de latch mantiene 8 bancos independientes. Un banco acumula mientras su bit esté activo en la máscara de armado; un latch toma la instantánea y la reinicia en el siguiente límite de ventana de medida, así que un periodo es el intervalo entre dos latches del mismo banco, medido con el reloj del maestro. Estas llamadas necesitan un módulo que notifique bancos y, si no, lanzan RbAmpNotSupportedError; un número de banco fuera de 0..7 lanza RbAmpParamError.

Python
dev.std_arm_banks(mask)                 -> None            # bit i = bank i accumulates
dev.std_latch(bank)                     -> None            # snapshot + reset; does not wait
dev.std_read_latch(bank)                -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
  • std_arm_banks(mask) — establece la máscara de armado. La máscara no se conserva tras un reinicio del módulo.

  • std_latch(bank) — hace latch de un banco. Léalo no antes de 300 ms después.

  • std_read_latch(bank) — devuelve la instantánea del banco. El indicador valid del módulo solo indica que el banco se ha hecho latch al menos una vez; no es un indicador de frescura, así que espere al menos una ventana (300 ms es una cota segura) tras std_latch(). Un banco que nunca se hizo latch lanza RbAmpStaleError. Un banco vacío que ya no está armado (el módulo se reinició) se vuelve a armar y se hace latch una vez para iniciar un periodo nuevo, y la llamada lanza RbAmpStaleError: descarte ese periodo y reinicie su propia referencia temporal.

  • RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF): convierte la energía de la instantánea a Wh en dt_ms del reloj del maestro. ch es un índice de canal, o 0xFF (por defecto) para el total del módulo. Devuelve (wh_import, wh_export); la exportación es cero o negativa. Lanza RbAmpStaleError para una instantánea sin muestras.

Python
class RbAmpStdLatch:
    bank:       int     # 0..7
    valid:      bool    # the bank has been latched at least once
    channels:   int
    p_avg, q_avg, s_avg: float     # average P (W), Q (var), S (VA) over the period
    max_p, max_i, max_u, min_u: float   # peak P (W), peak I (A), peak / minimum U (V)
    e_import_mws, e_export_mws: int     # energy, mW·samples (export <= 0)
    nsamp:      int     # samples in the period
    win_count:  int     # measurement windows in the period (0 = not armed / nothing elapsed)
    p_avg_ch:   list    # per-channel average P, W
    e_import_ch_mws, e_export_ch_mws: list   # per-channel energy, mW·samples

Contabilidad por periodos

Véase 01 · Descripción general para el panorama completo y el Paso 5 de 05 · Inicio rápido para una plantilla mínima.

En un módulo STD las mismas llamadas funcionan. begin() elige la fuente del periodo según lo que notifique el módulo:

El módulo informa Fuente del período Comando de latch
contadores de energía del propio dispositivo diferencia entre dos lecturas del contador en la programación del maestro ninguno
solo bancos de latch de latch a latch en el banco 0 (al menos 300 ms de estabilización) CMD_LATCH_PERIOD en el banco 0
ninguno — las llamadas de periodo lanzan RbAmpNotSupportedError

En la fuente de contadores el primer periodo empieza en begin(); latch_period() no hace nada; is_period_valid() es True una vez anclados los contadores; read_period_max_power() lanza RbAmpNotSupportedError (no hay pico), y read_period_avg_power(ch) existe solo en un módulo de un canal, tras haber leído un periodo. Un cambio de generación de contadores vuelve a anclar el periodo y lanza RbAmpStaleError; un reinicio del módulo dentro de un periodo se informa en snap.module_restarted (la energía no se mide mientras el módulo se reinicia). En la fuente de latch, una instantánea vacía lanza RbAmpStaleError; si el banco había perdido su armado (reinicio del módulo) se arma de nuevo primero. La instantánea incluye avg_p_total, wh_net y module_restarted. read_period_latch_ms() es solo de BASIC.

dev.latch_period() -> None

Escribe CMD_LATCH_PERIOD. No espera: el llamador debe respetar los 50 ms de estabilización y comprobar dev.is_period_valid() antes de leer.

Para la mayoría de tareas, use read_period_snapshot(): encapsula toda la secuencia.

dev.is_period_valid() -> bool

Lee el bit de instantánea lista. Devuelve True si la última instantánea es fresca.

dev.read_period_avg_power(ch=0) -> float

Potencia activa media en un canal durante el periodo cerrado. Debe llamarse tras latch_period() + 50 ms de estabilización + una comprobación de validez.

Resuelve todos los canales del módulo (ch = 0..channels-1), incluidos los canales 3 y siguientes de los módulos de 5 y 7 canales (UI5 / UI7). La instantánea de periodo y el acumulador de Wh también cubren todos los canales. dev.read_period_avg_p(ch) es un alias con el mismo comportamiento.

dev.read_period_max_power() -> float

Potencia instantánea máxima en el canal 0 durante el periodo cerrado. ch=0 solo en firmware v1.

dev.read_period_latch_ms() -> int

Duración del periodo desde la perspectiva del dispositivo, en ms.

Valor de diagnóstico.

El temporizador interno del módulo tiene una precisión limitada. Para la integración de energía, use master_dt_ms de RbAmpPeriodSnapshot, no este campo.

dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot

El punto de entrada recomendado para la contabilidad por periodo. La secuencia completa por debajo:

  1. Si skip_latch=True: se omite la escritura del comando de instantánea (para el patrón con varios módulos tras una serie manual de comandos de instantánea).

  2. En otro caso, escriba CMD_LATCH_PERIOD.

  3. Capture time.monotonic() para calcular master_dt_ms.
  4. time.sleep(settle_ms / 1000) — 50 ms por defecto.
  5. Compruebe el indicador de instantánea lista. Si vale 0, lance RbAmpStaleError (se conserva la marca de tiempo anterior, así que la siguiente instantánea correcta cubre el intervalo completo y los Wh siguen siendo exactos).

  6. Lea avg_p[0..channels-1] + max_p + latch_ms.

  7. Actualice la marca de tiempo y llame a energy.tick(snap) para integrar Wh (salvo que el acumulador esté desactivado mediante energy.disable()).
Parámetro Descripción
settle_ms Espera tras el comando de instantánea, en ms. Por defecto 50.
skip_latch Si es True: no envía el comando de instantánea, solo lee.

Lanza: RbAmpStaleError (instantánea obsoleta); RbAmpIOError (fallo de bus).

async dev.stream_period(interval_s=60.0, skip_stale=True)

Un generador asíncrono que produce RbAmpPeriodSnapshot con el intervalo interval_s. Funciona en asyncio de CPython y en uasyncio de MicroPython (MicroPython ≥ 1.20; import asyncio también funciona; en versiones anteriores use import uasyncio as asyncio).

Python
async for snap in dev.stream_period(interval_s=60.0):
    # snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
    print(snap.avg_p[0])
Parámetro Descripción
interval_s Periodo entre instantáneas (se recomiendan ≥ 30 s)
skip_stale True (por defecto): las instantáneas obsoletas se omiten automáticamente. False: se entregan con snap.valid=False, y su código debe comprobar if not snap.valid: continue por sí mismo
Seguridad

⚠ CPython: bloquea el bucle de eventos. Por dentro, stream_period() llama a la bloqueante read_period_snapshot(), que es síncrona: incluye un time.sleep(0.05) de estabilización y unos 50–100 ms de lecturas de un byte por el bus. En CPython esto bloquea todo el bucle de eventos de asyncio durante esos 100 ms: el resto de corrutinas (MQTT, HTTP, keepalive de Wi-Fi) no recibe CPU. En servidores de producción, envuélvalo en run_in_executor:

Python
import asyncio

async def stream_period_nonblocking(dev, interval_s=60.0):
    loop = asyncio.get_event_loop()
    while True:
        await asyncio.sleep(interval_s)
        snap = await loop.run_in_executor(None, dev.read_period_snapshot)
        if snap.valid:
            yield snap

En MicroPython el problema es menor: el planificador de uasyncio cede el control a otras tareas con menos frecuencia, y el I²C bloqueante se considera aceptable en patrones asíncronos embebidos. Si necesita un comportamiento no bloqueante, use un hilo aparte mediante _thread.start_new_thread (en ESP32 µPy).

Contabilidad de energía (acumulador del lado del master)

dev.energy — instancia de RbAmpEnergy

Un acumulador de Wh por canal. Se accede mediante una propiedad: el paquete es dueño de la instancia:

Python
dev.energy.wh(ch=0)         -> float    # current Wh total for the channel
dev.energy.reset(ch=0)      -> None     # zero a single channel
dev.energy.reset_all()      -> None     # zero all channels
dev.energy.is_enabled       -> bool     # True while auto-integration is active (default)
dev.energy.disable()        -> None     # turn off auto-integration
dev.energy.enable()         -> None     # turn it back on

El acumulador se actualiza automáticamente en cada dev.read_period_snapshot() correcto. Tiene signo: un valor negativo significa exportación neta.

Fórmula de integración:

Text
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
         [W]             [milliseconds]              → [Wh]

dev.energy.disable() es útil en escenarios de sueño profundo en los que el propio maestro gestiona la persistencia de Wh en la memoria RTC; véase 06 · Ejemplos, Escenario 9.

Configuración del sensor

Una secuencia de dos pasos. Para una guía detallada de selección de modelo, véase 03 · Selección del sensor de corriente.

dev.set_sensor_class(cls) -> None

Fija la clase del sensor de corriente y la guarda en la flash. Bloqueante, ~705 ms.

Python
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
Parámetro Descripción
cls Un enum RbAmpSensorClass o un int 0..3

Raises:

  • RbAmpParamError — cls fuera de 0..3
  • RbAmpModeError — el módulo está emparejado de fábrica (clase actual WIRED_CT / BUILTIN_CT) y cls difiere; cambiarlo borraría la calibración del sensor montado

  • RbAmpIOError: fallo de comunicación

Debe llamarse antes de set_ct_model*(). Escribir la misma clase que el módulo ya tiene es un no-op (sin escritura en el bus), porque escribir una clase borra en el dispositivo los modelos de CT por canal. Véase guarda de lectura previa a la escritura.

dev.read_sensor_class() -> int

Lee la clase de sensor fijada: 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (los valores de RbAmpSensorClass). Devuelve 0 en firmware donde el registro no existe.

dev.set_ct_model(code) -> None

La forma de un solo parámetro (heredada) — establece el modelo de pinza amperimétrica solo en el canal 0.

code Modelo
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060
Nota

El conjunto aceptado para la clase SCT_013 es {1, 2, 3, 4, 5, 6, 7}. La tabla completa de conjuntos aceptados por clase está en 03 · Selección del sensor de corriente.

Raises:

  • ValueError (y también RbAmpParamError) — code no está en el conjunto aceptado de la clase actual para REG_SENSOR_CLASS (para SCT_013 es {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — si no se llamó a set_sensor_class(), o el módulo está emparejado de fábrica (clase 2/3) y el código difiere (use set_ct_model_ch_force() en un contexto de servicio)

  • RbAmpIOError: fallo de comunicación

Fijar el modelo que el canal ya tiene es un no-op (guarda de lectura previa a la escritura).

Mensaje de RbAmpModeError (clase sin fijar):

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Equivale a dev.set_ct_model_ch(0, code).

dev.set_ct_model_ch(channel, code) -> None

La forma por canal. Establece el modelo de pinza amperimétrica en un canal concreto.

Por dentro: preparar REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) → 5 ms de estabilización → CMD_SAVE_USER_CONFIG (0x32) → 700 ms. Bloqueante, ~705 ms.

Nota

✅ v1.3: el orden de vinculación de canales no importa. En v1.3, escribir REG_CT_MODEL (0x05) prepara el valor, pero ya no lo aplica automáticamente a ch0. La aplicación se hace solo mediante CMD_SET_CT_MODEL_CHn. Puede configurar los canales en cualquier orden.

Python
dev.set_ct_model_ch(0, 1)  # any order is OK on v1.3
dev.set_ct_model_ch(1, 3)
dev.set_ct_model_ch(2, 6)

Raises:

  • RbAmpParamError — channel fuera de 0..dev.channels-1 o code fuera del conjunto aceptado por la clase (para SCT_013 — {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — no se llamó a set_sensor_class(), o el módulo está emparejado de fábrica y el código difiere

dev.set_ct_model_ch_force(channel, code) -> None

Variante de servicio de set_ct_model_ch() que omite la protección de lectura antes de escritura: escribe aunque el módulo esté emparejado de fábrica o ya tenga el código. Pensada para técnicos que vuelven a sensorizar una unidad. El módulo sigue validando el par (clase, código) y la llamada lanza RbAmpParamError si el par no es válido.

Protección de lectura antes de escritura

Escribir un modelo de pinza sustituye la calibración de ese canal por el preajuste genérico del modelo, por eso desde la 1.6.0 los métodos set comprueban primero:

Llamada El módulo ya tiene ese valor Módulo emparejado de fábrica (clase 2/3) En caso contrario
set_sensor_class(cls) sin operación, sin escritura en el bus RbAmpModeError si cls difiere escribe + guarda
set_ct_model(code) / set_ct_model_ch(ch, code) sin operación, sin escritura en el bus RbAmpModeError si el código difiere escribe + guarda
set_ct_model_ch_force(ch, code) escrituras escrituras escrituras

Espejos de verificación V2: CT_MODEL_CH0/1/2 (0x51-0x53)

Registros de solo lectura que reflejan el preajuste de pinza aplicado realmente en cada canal. El protocolo de escritura no cambia: las escrituras usan el mecanismo anterior. 0x51-0x53 son solo una lectura de vuelta para comprobar el estado y para patrones de leer-comparar-escribir:

Python
applied_ch0 = dev.read_ct_model_ch(0)   # what is actually applied
applied_ch1 = dev.read_ct_model_ch(1)
applied_ch2 = dev.read_ct_model_ch(2)

Corrección del cambio de calibre SCT-013

Los módulos SCT-013 se calibran en fábrica con un modelo de pinza de referencia. Cuando un canal cambia a otro modelo, una imagen de módulo que no se reescala por sí misma sigue aplicando la ganancia de referencia, así que la corriente y la potencia se leerían a la escala equivocada. Desde la 1.6.0 la biblioteca lo corrige automáticamente en módulos BASIC con clase de sensor SCT_013:

  • La corriente, la potencia y la energía derivada de la potencia (read_current, read_current_peak, read_power, read_period_avg_power, y por tanto la instantánea de periodo y dev.energy) se corrigen al modelo elegido, respecto a la ganancia que aplica realmente el módulo.

  • La tensión y el factor de potencia nunca cambian.

  • En el firmware del módulo hasta la 1.4.19, un cambio de modelo reinicia el módulo una vez (unos segundos); desde la 1.4.20 el módulo se corrige solo. La corrección por calificación del SCT escala corriente, potencia y energía, nunca tensión ni factor de potencia.
  • Los módulos cuyo firmware realiza esto por sí mismo se detectan y se dejan sin cambios (escala 1).

  • Los módulos emparejados de fábrica (clase 2/3) nunca se escalan.

  • La corrección se evalúa en begin() y de nuevo tras un reinicio que la biblioteca provoca (reset()) o tras uno detectado. En una situación (un modelo escrito durante el ciclo de alimentación actual) la biblioteca puede emitir un reinicio del módulo para leer la ganancia almacenada.
Python
dev.set_rating_correction(enabled: bool)  -> None   # default enabled
dev.rating_correction_enabled             -> bool
dev.ct_rating_scale(ch=0)                 -> float  # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0)                -> (action, detail) | None
dev.refresh_rating_correction()           -> None
  • set_rating_correction(enabled) — desactive la corrección para leer los valores crudos, sin corregir (o en un módulo cuyo firmware ya corrige). Recalcula de inmediato.

  • ct_rating_scale(ch) — la escala aplicada a la corriente, la potencia y la energía de un canal; 1.0 cuando no hay ninguna corrección activa.

  • ct_rating_status(ch): (action, detail) de la última evaluación de un canal, o None si el canal nunca se evaluó (por ejemplo, si no es un canal SCT). action es uno de "unity", "ok", "needs_reset", "warn_uncal", "warn_gain"; detail es texto. Las acciones warn_* indican que la biblioteca no pudo determinar una escala segura y dejó la lectura sin corregir.

  • refresh_rating_correction(): volver a evaluar tras un reinicio que la biblioteca no provocó (por ejemplo, un modelo guardado y el módulo reiniciado desde fuera).

Es una función de la ruta SCT-013 en todas las bibliotecas de rbAmp, no específica de Python.

dev.save_gains() -> None

Una escritura "pelada" de CMD_SAVE_GAINS (0x26): solo de fábrica.

Nota

⛔ BLOQUEADO en el firmware de producción (v1.3 devuelve DEV_ERR_PARAM; el dispositivo rechaza la escritura y un reinicio posterior revierte cualquier cambio en RAM). CMD_SAVE_GAINS está reservado para el modo de aprovisionamiento de fábrica y solo persiste las ganancias, NF y coeficientes de fase. Para la persistencia de cara al usuario de sensor_class / ct_model por canal, la dirección y la etiqueta, use dev.save_user_config() (o las llamadas por canal set_ct_model_ch() / set_sensor_class(), que ya emiten internamente CMD_SAVE_USER_CONFIG (0x32)).

Lanza: RbAmpModeError si el módulo no está en modo de aprovisionamiento de fábrica; RbAmpIOError ante un fallo de comunicación.

dev.prepare_address_change(new_addr) -> None

Paso 1 de 2 para cambiar la dirección I²C del módulo. Válido en producción con el firmware actual (commit en dos fases de v1.3).

Escenario: validación de rango → escribir el candidato en REG_I2C_ADDRESS (0x30) en RAM → escribir el magic 0xA5 en REG_ADDR_COMMIT_MAGIC (0x31): armado. El llamante debe llamar a commit_address_change() en un plazo de 5 segundos; si no, el armado caduca.

Raises:

  • RbAmpParamError: new_addr fuera de 0x08..0x77 o igual a la dirección actual

  • RbAmpIOError: fallo de comunicación

dev.commit_address_change() -> None

Paso 2 de 2. Debe llamarse en un plazo de 5 segundos tras prepare_address_change().

Escenario: comprobar la frescura del armado con magic → CMD_COMMIT_ADDR (opcode 0x30) → persistir en flash → CMD_RESET → ~300 ms hasta estar operativo tras el arranque → actualizar el campo interno de dirección. Tras el reinicio, REG_I2C_ADDRESS (0x30) (v1.3) devuelve la nueva dirección activa; esta es la verificación canónica.

Seguridad

⚠ Histórico: antes de las correcciones de la v1.3, el cambio de dirección se documentaba erróneamente como solo de fábrica. En la v1.3 es una operación de producción mediante confirmación en dos fases.

Un matiz adicional:

Seguridad

⚠ Reinicio y reenumeración tras la confirmación. Tras una confirmación correcta, el dispositivo se reinicia y se reenumera en la NUEVA dirección. Las llamadas posteriores en esta instancia del manejador usan la nueva dirección de forma transparente, pero cualquier OTRO maestro del bus (otro script Python, un componente de ESP-IDF, una sonda de depuración) seguirá creyendo que el dispositivo está en la dirección antigua hasta que su estado interno se actualice manualmente.

Raises:

  • RbAmpTimeoutError: la ventana de armado (5 s) expiró
  • RbAmpIOError: fallo de comunicación

dev.factory_reset() -> None

El comando CMD_FACTORY_RESET + una espera de 1500 ms.

Seguridad

⚠ Operación destructiva. Borra TODOS los parámetros de la flash (modelo de pinza, clase de sensor, coeficientes de calibración, dirección I²C). El módulo vuelve a los valores de fábrica: RbAmpSensorClass pasa a UNSET, REG_CT_MODEL pasa a 0. Cualquier configuración aplicada antes con set_sensor_class() / set_ct_model*() desaparece. El siguiente usuario DEBE volver a aplicar set_sensor_class() y set_ct_model*() antes de que la contabilidad vuelva a funcionar. No es un "reinicio suave": para un reinicio suave use reset(). factory_reset() está reservado para recuperarse de un estado conocido como defectuoso o para entregar el módulo a otro usuario / otra instalación.

Lanza: RbAmpIOError ante un fallo de comunicación.

dev.reset() -> None

El comando CMD_RESET + una espera de 100 ms. Un reinicio suave del dispositivo sin perder los parámetros de la flash.

Lanza: RbAmpIOError ante un fallo de comunicación.

Identificación y aprovisionamiento (v1.3)

Estos métodos permiten al maestro entender exactamente qué está conectado al bus (variante, mapa de bits de capacidades, UID, etiqueta) y preparar un módulo nuevo o recién flasheado para su funcionamiento (aprovisionamiento

  • guardar la configuración en flash).

dev.read_variant() -> int

Lee el registro HW_VARIANT (0x55) del módulo (el byte canónico de SKU de v1.3):

Código SKU Canales I Canal U
1 UI1 1 sí
4 I1 1 no
5 I2 2 no
6 I3 3 no

Esta es la vía recomendada para la autodetección: la vía de sondeo por NACK se ha eliminado (el firmware nunca responde con NACK a las lecturas; las direcciones no mapeadas devuelven 0x00).

dev.read_capability() -> int

Lee el mapa de funciones de 16 bits de los registros CAPABILITY (0x57/0x58), u16 en little-endian. El mapa incluye un indicador de la etapa de entrada de tensión. Úselo para detectar funciones (no heurísticas por versión).

dev.has_voltage() -> bool

Un auxiliar práctico sobre read_capability(): devuelve True si el módulo tiene un canal U. Se guarda en caché en el manejador en la primera llamada.

dev.read_product_id() -> int

Lee PRODUCT_ID (0x54): el byte identificador de la familia (rbAmp = 0x01). Lo usa el escáner de la flota para confirmar que el dispositivo en una dirección es realmente un rbAmp.

dev.read_uid() -> bytes

Lee el identificador único de 96 bits del MCU desde UID (0x5C..0x67) en una sola operación en ráfaga (devuelve un objeto bytes de longitud 12). El UID es único para cada módulo y no cambia al volver a grabar el firmware.

dev.read_label() -> str

Lee la etiqueta de usuario de 8 bytes desde LABEL (0x68..0x6F). ASCII, relleno con ceros; devuelve una cadena (sin NUL). Cadena vacía si no hay etiqueta.

dev.set_label(label: str) -> None

Escribe una etiqueta de 8 bytes. La cadena se trunca a 8 bytes o se rellena con ceros. La escritura es byte a byte (rbAmp no autoincrementa las escrituras; el paquete hace el bucle por byte automáticamente). Tras escribir, hace falta un dev.save_user_config() para que la etiqueta sobreviva a un reinicio.

Lanza: RbAmpIOError ante un fallo de comunicación.

dev.is_provisioned() -> bool

Comprueba si el módulo ha pasado el aprovisionamiento inicial. Verifica que REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD): el firmware pone 0xFB cuando el bloque de configuración de usuario está vacío o corrupto. Un módulo recién salido de fábrica devuelve False; hace falta un save_user_config() tras la primera configuración de modelo de pinza y dirección.

Nota

En v1.3 este código es normal en un módulo virgen (no es fatal). No aborte el aprovisionamiento por la primera aparición de 0xFB.

dev.save_user_config() -> None

Emite CMD_SAVE_USER_CONFIG (opcode 0x32): guarda en flash el bloque de configuración de usuario: SENSOR_CLASS, CT_MODEL por canal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. No guarda los parámetros de calibración de fábrica.

Bloquea el hilo unos ~700 ms (ciclo de borrado y escritura de la flash). Durante la llamada, no intente acceder al módulo desde otras tareas.

Lanza: RbAmpIOError / RbAmpTimeoutError.

Relectura ≠ persistencia

: confirmar que un valor se ha escrito en flash requiere un reinicio + relectura. Véase la sección "Modelo de errores v1.3" más abajo.

Modelo de errores v1.3: dos canales independientes

Los errores tienen dos canales independientes que funcionan de modos distintos. Entender la diferencia es fundamental para interpretar correctamente el estado del módulo.

Canal A: lado cliente, síncrono Canal B — lado del DUT, asíncrono y duradero
Dónde reside Validación dentro del paquete (_validate_ct_code, etc.) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Cuándo se dispara Antes de la transacción I²C (la biblioteca la intercepta) Tras aceptar el firmware una escritura y rechazarla
Lo que ve el maestro El setter lanza RbAmpParamError; REG_ERROR en el dispositivo se queda en 0x00 REG_ERROR = el código de rechazo de inmediato; bit3 se activa unos cientos de milisegundos después de la transacción
Persistente no (solo una excepción) Última escritura de REG_ERROR; bit3 pegajoso W1C
Ruta típica Un argumento fuera de los límites permitidos (channel ∉ {0,1,2}, code fuera del conjunto caracterizado, sensor_class fuera del enum) Una escritura de registro en bruto que el paquete no valida previamente (dev._io.write_reg() de bajo nivel con un byte no válido)

Canal A: validación en el cliente (setters del paquete)

Todos los métodos set del paquete (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels, etc.) comprueban primero los argumentos frente a los valores permitidos. Si un argumento está fuera de rango, el método lanza RbAmpParamError, sin realizar ninguna transacción I²C. Por tanto, REG_ERROR en el dispositivo queda sin tocar:

Python
from rbamp import RbAmp, RbAmpParamError

try:
    dev.set_ct_model_ch(99, 3)        # invalid channel
except RbAmpParamError as e:
    print(f"client-side guard: {e}")
    reg_err = dev.read_last_error()
    print(f"REG_ERROR on the device: 0x{reg_err:02X}")
    # → 0x00 (the package stopped it before the wire, REG_ERROR untouched)

Esto significa que, si quiere saber exactamente por qué falló un método set, la fuente fiable es la propia excepción (RbAmpParamError.args / str(e)). REG_ERROR en el dispositivo no le dice nada en este escenario.

Canal B: rechazo en el lado del DUT (asíncrono duradero)

Si una escritura llegó por I²C (la biblioteca no la interceptó porque el argumento parecía válido) pero el firmware la rechazó, entra en acción el segundo canal:

  • read_last_error() devuelve de inmediato la causa (por ejemplo, 0xFE = DEV_ERR_PARAM). Es el resultado de la última escritura: cualquier escritura posterior correcta lo sobrescribe. Debe leerlo inmediatamente después de su escritura, antes de cualquier otra transacción.

  • has_error(): el indicador pegajoso W1C de EVENT_FLAGS.bit3. No se activa al instante: en banco se midió un retardo de unos cientos de milisegundos entre la transacción rechazada y el ajuste de bit3.

Seguridad

⚠ No use has_error() para validar una escritura que acaba de hacer. Para el resultado de esa escritura concreta, solo read_last_error() es fiable, leído inmediatamente después de la escritura y antes de cualquier otra transacción (además de la excepción del setter). has_error() es el canal asíncrono para la monitorización por sondeo de «si algo falló entre dos comprobaciones», no para la validación síncrona.

Borrado de un error duradero: borre ambos (REG_ERROR y bit3)

bit3 lo vuelve a derivar el firmware cada pocos cientos de milisegundos a partir del estado actual de REG_ERROR. Por tanto, un simple clear_event_flags(1 << 3) no funcionará: bit3 queda activado de nuevo de inmediato desde el REG_ERROR que aún no se ha borrado. El orden correcto:

Python
dev.clear_error()                     # zero REG_ERROR
dev.clear_event_flags(1 << 3)         # reset sticky bit3

Si quiere atomicidad, no debe haber ninguna escritura rechazada entre ellas.

dev.read_last_error() -> int

Lee directamente el registro REG_ERROR (0x02) del dispositivo (una sola lectura por cable): el resultado de la última transacción aceptada con éxito en el bus (una escritura o un comando). No es pegajoso: cualquier escritura correcta posterior lo sobrescribe con su propio resultado. Se usa en el Canal B (rechazo en el lado del DUT) para el código de causa ampliado.

dev.has_error() -> bool

Ayudante de conveniencia sobre EVENT_FLAGS.bit3 (ERROR_OCCURRED). Devuelve True si bit3 está activo. Pegajoso W1C; no se borra hasta una limpieza explícita (con una advertencia: véase la sección «Borrar un error duradero» más arriba).

dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None

EVENT_FLAGS (0x2A) es un byte de indicadores pegajosos; los bits concretos se describen en la especificación (incluido ERROR_OCCURRED, bit3). El borrado es write-1-to-clear.

dev.clear_error() -> None

Emite CMD_CLEAR_ERROR (opcode 0x31): pone a cero REG_ERROR. Necesario para borrar un error duradero junto con clear_event_flags(1 << 3).

Configuración multicanal (v1.3)

En módulos multicanal (I2, I3), cada canal de corriente tiene su propio modelo de sensor CT. La utilidad atómica para la configuración en bloque es configure_channels().

dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None

Parameters:

  • cls — la clase de sensor (RbAmpSensorClass.SCT_013 para las pinzas SCT-013; WIRED_CT/BUILTIN_CT reservadas).

  • models — una secuencia de códigos de modelo de pinza (uno por canal).

  • n — la longitud (opcional; por defecto = len(models)).

Internamente, la función realiza:

  1. set_sensor_class(cls) una vez.
  2. Para cada canal: prepare REG_CT_MODEL = models[k] + CMD_SET_CT_MODEL_CHk.

  3. Un CMD_SAVE_USER_CONFIG final: es decir, un ciclo de borrado y escritura de la flash para toda la configuración.

Ajustado a la variante: si len(models) es mayor que el número de canales de la variante, los elementos sobrantes se ignoran.

Raises:

  • RbAmpParamError — cls o models[k] no válidos (validación en el cliente por clase; REG_ERROR en el dispositivo se mantiene en 0x00).

  • RbAmpIOError: error de bus.

  • RbAmpTimeoutError — tiempo de espera agotado al escribir en flash.
Nota

Códigos aceptados por clase: SCT_013 → {1, 2, 3, 4, 5, 6, 7}; un código fuera del conjunto lanza RbAmpParamError antes de tocar el bus. Véase 03 · Selección de sensor.

dev.read_ct_model_ch(ch: int) -> int

Lee el modelo de sensor CT aplicado (espejo de verificación) en un canal concreto desde el registro 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). Es una lectura de la RAM, no una confirmación de persistencia; para confirmar el guardado en flash, use dev.reset() + una nueva lectura del espejo.

RbAmpFleet: gestión de varios módulos

La clase RbAmpFleet es la superficie principal de alto nivel del paquete v1.3. Gestiona una colección de módulos en un bus I²C compartido: descubrimiento, aprovisionamiento, agregación de sondeos, agregación de errores e instantáneas síncronas mediante una difusión General-Call.

Cada flota está ligada a un único bus (normalmente SMBus(1) en CPython o I2C(0, ...) en MicroPython). El límite flexible de módulos es RBAMP_FLEET_MAX_MODULES = 16.

Ciclo de vida

Python
RbAmpFleet(bus, max_modules: int = 16)

Tras del fleet, todos los handles adoptados se liberan.

Descubrimiento: scan()

Python
fleet.scan(match_product: bool = True) -> int

Sondea el bus en el rango 0x08..0x77. Para cada dirección que responde con ACK:

  1. Comprueba la identidad (PRODUCT_ID, HW_VARIANT, CAPABILITY). Si match_product = True, exige una coincidencia con el PRODUCT_ID de rbAmp.

  2. Ejecuta el detector de conflictos. Las direcciones sospechosas pasan a la lista excluded, no a la flota.

Devuelve el número de módulos añadidos a la flota.

Lanza: RbAmpIOError si el bus está bloqueado (canario de bloqueo de nivel 2).

Acceso al módulo

Python
fleet.count                              # property: number of modules in the fleet
len(fleet)                                # equivalent to fleet.count
fleet[index]                              # a module by index
fleet.find(address) -> RbAmp | None       # a module by address
fleet.add(dev: RbAmp) -> None             # adopt an existing handle
for dev in fleet:                         # iteration
    ...
fleet.excluded -> tuple[int]              # addresses that ended up in excluded

Sondeo: poll_all()

Python
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]

Sondea todos los módulos de la flota en una sola llamada. Devuelve una lista de tuplas; para cada módulo:

  • un RbAmpSnapshot o None (si falla)
  • un POD RbAmpFleetPoll con los campos addr, ok, channels

Tolerante a fallos: un módulo silencioso no cancela el sondeo de los demás.

Agregación

Python
fleet.total_power() -> float              # W; summed over all channels
fleet.total_energy_wh() -> float          # W·h; per-handle accumulators
fleet.poll_errors() -> dict[int, bool]    # per-addr bit3 status

total_power suma la potencia activa de todos los canales de todos los módulos. Las variantes I no tienen potencia activa, así que aportan 0. En el canon, el 80% del resultado ≈ la potencia activa del módulo de red.

fleet.aligned_snapshot(group=0) -> list[dict]

Instantánea de periodo coherente de toda la flota en todos los canales de cada miembro: difunde una instantánea General-Call y después lee la potencia media de la instantánea de cada miembro sincronizado para cada canal (read_period_avg_p). Devuelve un diccionario por miembro, en el orden de la flota, con las claves addr, in_sync, period_valid, avg_p (lista, una entrada por canal; None si el miembro perdió el tick o no respondió). La instantánea alinea solo los promedios de periodo: las lecturas en vivo (I, P, PF) no pueden alinearse entre canales.

Direccionamiento y comprobación de conflictos

Python
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool   # collision detected?

assign_address reasigna la dirección de un módulo ya existente de la flota a una nueva dirección: internamente, confirmación en dos fases + reinicio; el manejador en la flota se actualiza automáticamente.

check_conflict es una comprobación de solo lectura, de mejor esfuerzo, para una dirección concreta. Para revisar todas las conocidas, recorra la flota.

Aprovisionamiento

Protocolo nativo

6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference)

⚠ En la versión actual de rbamp, el aprovisionamiento se hace mediante dev.prepare_address_change() + dev.commit_address_change() sobre un handle RbAmp(bus, 0x50) creado a mano, y luego fleet.add(dev). Véase el fragmento en 06 · Ejemplos, Escenario 2.

DEBE: exactamente un virgen en el bus en el momento del aprovisionamiento. Dos módulos en 0x50 a la vez son físicamente indistinguibles por I²C: no se pueden distinguir ni con hardware especial.

Sincronización GC de la flota: instantáneas síncronas en toda la flota

Python
fleet.enable_gc_all(group: int = 0) -> int
fleet.gc_latch(group: int = 0, tick: int | None = None,
               settle_ms: int = 50) -> int
fleet.check_sync(expected_tick: int) -> list[RbAmpFleetSync]

Para una sincronización de instantáneas ajustada (desfase < 1 ms en toda la flota) se usa una instantánea de difusión por llamada general I²C.

  1. enable_gc_all(group) activa el indicador GC_ENABLE de FLEET_CONFIG + GROUP_ID en todos los módulos de la flota, y emite CMD_SAVE_USER_CONFIG en cada uno (persistente). Un reinicio de los módulos es obligatorio tras activar; se hace automáticamente. Devuelve el número de módulos donde la activación tuvo éxito.

  2. gc_latch(group, tick, settle_ms) envía la trama GC A5 27 group tick_lo tick_hi a la dirección 0x00. Si tick=None, el tick se incrementa automáticamente con un contador interno. Devuelve el tick de la difusión.

  3. check_sync(expected_tick) lee GC_TICK (0x59) en cada módulo. Devuelve una lista de PODs RbAmpFleetSync con los campos:

Python
class RbAmpFleetSync:
    addr: int          # I²C address of the module
    gc_tick: int       # REG_GC_TICK; 0xFFFF = never received a GC
    in_sync: bool      # True if gc_tick == expected_tick
    reachable: bool    # False if the read NACKs / times out

Configuración de flota por dispositivo (v1.3)

Estos métodos funcionan directamente con un único módulo (sin flota).

dev.enable_gc(enable: bool = True) -> None

enable_gc(True) escribe 1 en el indicador GC_ENABLE de FLEET_CONFIG (0x27), guarda en flash y reinicia: el módulo empezará a aceptar instantáneas GC tras el arranque. enable_gc(False) borra el bit de forma simétrica de forma simétrica. Bloquea durante ~1 segundo (espera de SAVE_USER_CONFIG y de reinicio). Idempotente: no hace nada si el estado actual ya coincide con el solicitado.

dev.read_fleet_config() -> int

Lee el byte FLEET_CONFIG (0x27). Útil para confirmar la lectura de vuelta.

dev.set_group_id(group: int) -> None / dev.read_group_id() -> int

GROUP_ID (0x28) es un filtro de tramas GC: el módulo solo reacciona a tramas GC con un group_id coincidente. Por defecto = 0x00 (difusión).

dev.read_gc_tick() -> int

Lee GC_TICK (0x59): el último valor de tick recibido de una trama GC. 0xFFFF = el módulo no ha recibido nunca una trama GC desde el arranque.

RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool

Método estático. Un envío de bajo nivel de la trama GC A5 27 group tick_lo tick_hi directamente sobre bus (sin flota). Útil si aún no se ha creado una flota, o si quiere controlar manualmente el contador de tick.

RbAmp.broadcast_latch(bus) -> bool

Método estático. Un envoltorio heredado, equivalente a broadcast_latch_group(bus, group=0, tick=0). Para desarrollo nuevo se prefiere la forma explícita broadcast_latch_group con su propio tick para la verificación de testigos.

Precondición

: la capacidad de instantánea General-Call (CAP_GC_LATCH, informada por REG_CAPABILITY) debe estar presente en el firmware y GC debe estar activado en cada módulo (dev.enable_gc(True) o fleet.enable_gc_all() cambia el indicador GC_ENABLE de FLEET_CONFIG, por defecto DESACTIVADO). Un módulo nuevo con valores de fábrica no acepta GC: es intencionado, como protección frente a una difusión accidental en un bus de puesta en marcha. Si GC está desactivado en toda la flota, el bus rechaza la trama GC a nivel de NACK; esto es detectable, no una pérdida silenciosa. En un módulo heredado sin CAP_GC_LATCH, el envoltorio recurre a una instantánea secuencial por dispositivo.

Diagnóstico

dev.set_logger(log_callable) -> None

Un destino de diagnóstico opcional. log_callable recibe un único argumento str. Si se configura, el paquete registra brevemente los resultados de probe(), las instantáneas obsoletas y los rechazos de modo.

Uso típico:

Python
import logging
log = logging.getLogger("rbamp")
log.setLevel(logging.INFO)
log.addHandler(logging.StreamHandler())
dev.set_logger(log.info)

# Or, simplest of all — a plain print:
dev.set_logger(print)

dev.sanity_reject_count: int

Contador de valores en coma flotante rechazados por el filtro de validez (!isfinite(x) or |x| > 10000). En régimen estable — 0. Un valor distinto de cero tras la mitigación por reintentos suele indicar un artefacto poco frecuente de la pila I²C que superó la capa de reintentos.

Contadores de diagnóstico de MachineI2CBackend (solo MicroPython)

MachineI2CBackend (el backend interno en MicroPython) expone dos contadores:

  • backend.retry_exhaustion_count — cuántas veces se agotó el bucle de reintentos sin éxito (se lanzó un RbAmpIOError)

  • backend.retry_count_total: cuántas veces el bucle de reintentos se recuperó con éxito mediante un reintento silencioso

Se accede a estos contadores a través de la API avanzada:

Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)   # the address is a parameter of RbAmp, not the backend

# ...soak-test for an hour...
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)

SMBusBackend (CPython) no tiene capa de reintentos: el driver I²C del kernel de Linux no está sujeto al patrón de NACK.

dev.read_seq_digest() -> int

Lee el byte de secuencia del resumen (0..255). Cambia cada vez que el módulo confirma un nuevo conjunto de lecturas, así que dos lecturas que devuelven el mismo valor proceden de la misma confirmación; es útil como comprobación de coherencia en un sondeo por lotes. Es solo un marcador de cambio (no es una suma de control).

dev.reset_counters() -> None

Pone a cero todos los contadores (RbAmp y el backend si es un MachineI2CBackend). Úselo al inicio de una prueba de estrés prolongada.

Metadatos y constantes del protocolo

Python
rbamp.__version__              # "1.6.0" — PEP 440 version
rbamp.__protocol_version__     # 0x04  — RBAMP_PROTOCOL_VERSION (v1.3)
rbamp.RBAMP_REG_SCHEMA_CRC32   # CRC32 of the schema codegen contract

REGISTERS y COMMANDS son diccionarios generados automáticamente a nivel de protocolo:

Python
from rbamp import REGISTERS, COMMANDS

REGISTERS["U_RMS"]           # 0x86
REGISTERS["PERIOD_VALID"]    # 0x07
COMMANDS["LATCH_PERIOD"]     # 0x27
COMMANDS["SAVE_USER_CONFIG"] # 0x32  — user-facing persistence path
COMMANDS["SAVE_GAINS"]       # 0x26  — factory-only; BLOCKED in production
COMMANDS["FACTORY_RESET"]    # 0xAA

Se usa dentro del paquete. Se expone para usuarios avanzados que hagan tránsito directo a través de su propio backend; los usuarios habituales no lo tocan.

Detalles del protocolo de bus

Para portar o depurar con un analizador lógico.

Lecturas de registros — autoincremento

Una lectura en ráfaga + N bytes devuelve N bytes consecutivos empezando en addr. En CPython, mediante bus.read_i2c_block_data(addr, start_reg, N): una sola transacción.

Escrituras de registros: byte a byte (NO autoincrementa)

⚠ Las escrituras NO autoincrementan. Una ESCRITURA en ráfaga + N bytes solo deposita el primer byte.

Un registro de varios bytes se escribe byte a byte:

Python
# WRONG — data loss
label = b"MyMeter1"
bus.write_i2c_block_data(0x50, 0x68, list(label))   # only 'M' lands

# CORRECT — byte-at-a-time loop
for i, byte in enumerate(label):
    bus.write_byte_data(0x50, 0x68 + i, byte)

Afecta a los multibyte escribibles: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, condicionado a fábrica), NF (u16), THRESH (u16). Las lecturas admiten ráfaga.

Excepción: la trama de llamada general (GC, 5 bytes a la dirección 0x00) es una ruta de protocolo de cable independiente (recepción de llamada general), enviada como una única transacción I²C.

Detección de variante

El byte SKU autorizado es REG_HW_VARIANT (0x55) (dev.hw_variant):

valor SKU
0x01 UI1
0x02 UI2
0x03 UI3
0x04 I1
0x05 I2
0x06 I3

Instantánea de difusión por llamada general

Activación opcional por módulo mediante el indicador GC_ENABLE de REG_FLEET_CONFIG. Por defecto DESACTIVADO. Se activa con CMD_SAVE_USER_CONFIG + CMD_RESET. Tras el reinicio, el módulo escucha la trama de difusión en la dirección 0x00:

Text
addr=0x00 | A5 27   
  • A5: magic; 27: el opcode CMD_LATCH_PERIOD.
  • : 0x00 = all-call; en otro caso debe coincidir con REG_GROUP_ID (0x28).
  • : un contador de periodo de 16 bits.

Detección de modos de fallo (2 niveles, confirmado en hardware C.10):

  1. NACK en la dirección GC: si la llamada general está desactivada en toda la flota, bus.write_i2c_block_data(0x00, ...) lanza OSError (o el equivalente del backend). Es un error grave, no un descarte silencioso.
  2. Testigo por módulo: si no se produjo ningún NACK, lea REG_PERIOD_VALID (0x07) en cada módulo. 1 = la instantánea se tomó correctamente; 0 = GC desactivado en ese módulo o el periodo está vacío.

Modelo de errores (v1.3)

  • REG_ERROR (0x02): resultado de la última escritura, NO pegajoso. Léalo JUSTO DESPUÉS de la operación.
  • EVENT_FLAGS (0x2A) bit3: señal duradera (pegajosa W1C). Detección de errores canónica mediante bit3.
Python
# Canonical durable monitoring
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear

Referencias


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