09 · Referencia de API
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
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:
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
RbAmpsirve a los módulos BASIC y STANDARD (STD). La línea se detecta automáticamente enbegin()(véase Línea de módulos STD); nunca la elige usted. -
Basada en clases: la clase principal
RbAmplo 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 adev.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 Pythontry / except(nolast_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
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.
: 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:
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
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)
: 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.
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.
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
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
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()
02 · Inicialización y arranque (initialization) · ¿BASIC o STD? (initialization) · Ciclo de sondeo continuo (recomendado) (period-metering)
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:
-
Lee
REG_VERSION: lanzaRbAmpIOErrorante un NACK yRbAmpVersionErrorsi se devuelve0x00/0xFF. -
Almacena en caché la topología (en el firmware actual,
begin()no hace autosondeo; usa la pista del constructor). -
Lee
U_rmspara determinar si hay un sensor de tensión (umbral 1.0 V). -
Escribe
CMD_LATCH_PERIOD(cebado) y espera 50 ms. La primera instantánea tras el encendido se descarta. -
Guarda
time.monotonic()(otime.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
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
02 · Inicialización y arranque (initialization) · 3. DATA_VALID (0xCE) nunca pasa a 1 (troubleshooting) · 4 · Mapa de registros (producción v1.3) (api-reference)
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
¿BASIC o STD? (initialization) · Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
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.
Propiedades
Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F) (api-reference)
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:
dev.current # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak # _ChannelProxy
dev.power # _ChannelProxy
dev.power_factor # _ChannelProxy
Usage:
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)
Referencia de registros RT (realtime-polling) · Contabilidad bidireccional (period-metering)
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
Referencia de registros RT (realtime-polling) · Sondeo: un solo módulo (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
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)
⚠️ 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 acumuladordev.energyfuncionan en un módulo STD: véase «Contabilidad por periodos» más abajo. Los totales de vida propios del módulo sonread_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_msywait_readyson solo de BASIC: en un módulo STD lanzanRbAmpNotSupportedErrorantes de enviar nada al bus.
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
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).validesFalseen 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. LanzaRbAmpNotSupportedErroren 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 lanzanRbAmpNotSupportedError(en BASIC esta biblioteca no expone la potencia reactiva). -
read_std_totals(k): bloque de totalesk;k=0es 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_restartedesTruecuandonow.uptime_s < prev.uptime_s.-
deltaes unRbAmpStdEnergycon el incremento de cada campo, oNonecuando el contadorgenerationha 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;
netes 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.
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
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 asave_config()para conservarlo tras un reinicio. Un valor no admitido lanzaRbAmpParamErrorantes de escribir nada en el bus. El valor debe ser0(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 lanzaRbAmpParamError. Vuelva a fijar la hora tras un reinicio del módulo (read_std_health().time_validesFalsehasta que se fija el reloj). -
get_start_current()/set_start_current()lanzanRbAmpNotSupportedErroren una imagen de módulo que no ofrece el ajuste de corriente de arranque;RbAmpStdConfig.start_ua_supportedindica 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.
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) trasstd_latch(). Un banco que nunca se hizo latch lanzaRbAmpStaleError. 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 lanzaRbAmpStaleError: 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 endt_msdel reloj del maestro.ches un índice de canal, o0xFF(por defecto) para el total del módulo. Devuelve(wh_import, wh_export); la exportación es cero o negativa. LanzaRbAmpStaleErrorpara una instantánea sin muestras.
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
04 · Medición por periodo y contabilidad tarifaria (medición por periodo) · Calibración y precisión (solución de problemas)
Lee el bit de instantánea lista. Devuelve True si la última instantánea es fresca.
dev.read_period_avg_power(ch=0) -> float
Registros de instantánea de período (period-metering) · 4.11 Bloque de período V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + período ch0 (0xD0..0xE3, compilación de producción) (api-reference)
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
Registros de instantánea de período (period-metering) · 4.12 V03 Q + período ch0 (0xD0..0xE3, compilación de producción) (api-reference)
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
13. Deriva del reloj entre módulos en pruebas largas (troubleshooting) · 4.13 dt de diagnóstico en el chip (0xEC) (api-reference)
Duración del periodo desde la perspectiva del dispositivo, en ms.
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
Ciclo de sondeo continuo (recomendado) (medición por periodos) · Calibración y precisión (solución de problemas) · 4.11 Bloque de periodo V03 (0xBE..0xCF) (referencia de la API)
El punto de entrada recomendado para la contabilidad por periodo. La secuencia completa por debajo:
-
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). -
En otro caso, escriba
CMD_LATCH_PERIOD. - Capture
time.monotonic()para calcularmaster_dt_ms. time.sleep(settle_ms / 1000)— 50 ms por defecto.-
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). -
Lea
avg_p[0..channels-1]+max_p+latch_ms. - Actualice la marca de tiempo y llame a
energy.tick(snap)para integrar Wh (salvo que el acumulador esté desactivado medianteenergy.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).
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 |
⚠ 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:
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
Algoritmo en el lado del maestro (period-metering) · 7 · Semántica (api-reference)
Un acumulador de Wh por canal. Se accede mediante una propiedad: el paquete es dueño de la instancia:
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:
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
Configuración de la clase de sensor y del modelo de CT (inicialización) · 4.3 Sistema (0x20..0x25) (api-reference) · 6.2 Vinculación del modelo de CT — preparación pura + CMD por canal (api-reference)
Fija la clase del sensor de corriente y la guarda en la flash. Bloqueante, ~705 ms.
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—clsfuera de 0..3-
RbAmpModeError— el módulo está emparejado de fábrica (clase actualWIRED_CT/BUILTIN_CT) yclsdifiere; 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 |
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énRbAmpParamError) —codeno está en el conjunto aceptado de la clase actual paraREG_SENSOR_CLASS(paraSCT_013es{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— si no se llamó aset_sensor_class(), o el módulo está emparejado de fábrica (clase 2/3) y el código difiere (useset_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):
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
Configuración de la clase de sensor y del modelo de CT (initialization) · 6.2 Asociación del modelo de CT: preparación pura + CMD por canal (api-reference)
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.
✅ 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.
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—channelfuera de 0..dev.channels-1ocodefuera del conjunto aceptado por la clase (paraSCT_013—{1, 2, 3, 4, 5, 6, 7})RbAmpModeError— no se llamó aset_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:
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 ydev.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.
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.0cuando no hay ninguna corrección activa. -
ct_rating_status(ch):(action, detail)de la última evaluación de un canal, oNonesi el canal nunca se evaluó (por ejemplo, si no es un canal SCT).actiones uno de"unity","ok","needs_reset","warn_uncal","warn_gain";detailes texto. Las accioneswarn_*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.
⛔ 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
Cambio de dirección (inicialización) · 4.5 Dirección (0x30..0x31) (api-reference) · 6.1 Cambio de dirección — commit en dos fases (apto para producción) (api-reference)
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_addrfuera de 0x08..0x77 o igual a la dirección actual -
RbAmpIOError: fallo de comunicación
dev.commit_address_change() -> None
Cambio de dirección (inicialización) · 4.5 Dirección (0x30..0x31) (api-reference) · 6.1 Cambio de dirección — commit en dos fases (apto para producción) (api-reference)
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.
⚠ 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:
⚠ 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.
⚠ 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
Autodetección de la variante del módulo (initialization) · Referencia del protocolo de cable de rbAmp (v1.3) (api-reference) · 3.6 Algoritmo de detección canónico (api-reference)
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
Autodetección de la variante del módulo (inicialización) · 3.2 CAPABILITY (registros 0x57/0x58, u16 LE, solo lectura) (api-reference) · 8 · Ejemplos de traza de bus (api-reference)
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
3.5 PRODUCT_ID (0x54, u8, solo lectura) (api-reference) · 4.8 Identidad (0x54..0x6F) (api-reference)
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.
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
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference) · 8.6 Aprovisionamiento con firmware nuevo (api-reference)
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.
: 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:
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 deEVENT_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.
⚠ 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:
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
3. DATA_VALID (0xCE) nunca pasa a 1 (troubleshooting) · Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 4 · Mapa de registros (producción v1.3) (api-reference)
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
4.4 Configuración de flota (0x27..0x2F) (api-reference) · 8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
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
Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperación del estado de error: árbol de decisión (api-reference)
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_013para las pinzas SCT-013;WIRED_CT/BUILTIN_CTreservadas). -
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:
set_sensor_class(cls)una vez.-
Para cada canal: prepare
REG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. -
Un
CMD_SAVE_USER_CONFIGfinal: 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—clsomodels[k]no válidos (validación en el cliente por clase;REG_ERRORen el dispositivo se mantiene en0x00). -
RbAmpIOError: error de bus. RbAmpTimeoutError— tiempo de espera agotado al escribir en flash.
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
4.7 Espejos de verificación del modelo de CT (0x51..0x53) (api-reference) · 8.10 Relectura del espejo de verificación del modelo de CT (comprobación posterior a la vinculación) (api-reference)
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
RbAmpFleet(bus, max_modules: int = 16)
Tras del fleet, todos los handles adoptados se liberan.
Descubrimiento: scan()
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling) · Problemas multimódulo (troubleshooting)
fleet.scan(match_product: bool = True) -> int
Sondea el bus en el rango 0x08..0x77. Para cada dirección que responde con ACK:
-
Comprueba la identidad (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Simatch_product = True, exige una coincidencia con el PRODUCT_ID de rbAmp. -
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
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()
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling)
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
RbAmpSnapshotoNone(si falla) - un POD
RbAmpFleetPollcon los camposaddr,ok,channels
Tolerante a fallos: un módulo silencioso no cancela el sondeo de los demás.
Agregación
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
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
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
General Call (difusión en la dirección 0x00) (initialization) · Multimódulo: instantánea simultánea (period-metering) · 6.3 Instantánea por difusión GC: sincronización de flota opcional (api-reference)
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.
-
enable_gc_all(group)activa el indicadorGC_ENABLEde FLEET_CONFIG +GROUP_IDen todos los módulos de la flota, y emiteCMD_SAVE_USER_CONFIGen 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. -
gc_latch(group, tick, settle_ms)envía la trama GCA5 27 group tick_lo tick_hia la dirección0x00. Sitick=None, el tick se incrementa automáticamente con un contador interno. Devuelve el tick de la difusión. -
check_sync(expected_tick)leeGC_TICK (0x59)en cada módulo. Devuelve una lista de PODsRbAmpFleetSynccon los campos:
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
Llamada general (difusión en la dirección 0x00) (inicialización) · 4.4 Configuración de flota (0x27..0x2F) (api-reference)
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.
: 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:
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ó unRbAmpIOError) -
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:
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
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:
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 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 solo deposita el primer byte.
Un registro de varios bytes se escribe byte a byte:
# 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:
addr=0x00 | A5 27
A5: magic;27: el opcodeCMD_LATCH_PERIOD.:0x00= all-call; en otro caso debe coincidir conREG_GROUP_ID (0x28).: un contador de periodo de 16 bits.
Detección de modos de fallo (2 niveles, confirmado en hardware C.10):
- NACK en la dirección GC: si la llamada general está desactivada en toda la flota,
bus.write_i2c_block_data(0x00, ...)lanzaOSError(o el equivalente del backend). Es un error grave, no un descarte silencioso. - 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.
# 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
- 05 · Inicio rápido — su primer script funcional
- 06 · Ejemplos: escenarios de trabajo
-
10 · Solución de problemas — interpretación de errores y solución de problemas habituales
-
Fuente:
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/09_api_reference.md (v1.6.1)