11 · Registro de cambios
Esta página refleja CHANGELOG.md del repositorio.
1.6.1 — 2026-11-01
La medición por periodos funciona ahora en módulos STD con las mismas llamadas que en BASIC; se añaden las llamadas de banco de latch, y las llamadas exclusivas de BASIC se rechazan limpiamente en módulos STD.
Añadido
- Medición por periodo en módulos STD (
read_period_snapshot,read_period_avg_power/read_period_avg_p,read_period_max_power,is_period_valid,latch_period,dev.energy). La fuente se decide una vez enbegin(): un módulo con contadores en el dispositivo usa la diferencia de dos lecturas de contadores según la programación del maestro (no se envía comando de latch); un módulo solo con bancos de latch hace latch del banco 0 (de latch a latch, con al menos 300 ms de asentamiento); un módulo sin ninguno lanzaRbAmpNotSupportedError. Un cambio de generación de contadores, o un banco que perdió su armado tras un reinicio del módulo, se vuelve a anclar y ese periodo se omite (RbAmpStaleError). La instantánea de periodo añadeavg_p_total,wh_netymodule_restarted. Un periodo basado en contadores no tiene potencia pico, y un promedio por canal solo en un módulo de un canal. - Llamadas de banco de latch, disponibles siempre que el módulo notifique bancos:
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank)(unRbAmpStdLatch: P/Q/S, picos, energía en mW·muestras, energía y potencia media por canal) yRbAmp.std_latch_wh(snap, dt_ms, ch). El indicador de válido de un banco es pegajoso, no es un indicador de frescura: lea un banco al menos 300 ms después de haberlo capturado. - Los modelos de sensor 11 (50 A) y 13 (100 A) de la clase de pinza están caracterizados, con sus límites nominal / escala completa / pico. El modelo 12 (80 A) no cambia.
Fijo
- Las llamadas que existen solo en el mapa de registros BASIC (configuración de clase de sensor / modelo de CT, reinicio y cambio de dirección, registros de identidad, canal de errores y eventos, ayudantes de flota y de llamada general,
read_period_latch_ms,wait_ready) lanzan ahoraRbAmpNotSupportedErroren un módulo STD, en lugar de leer o escribir la dirección equivocada. set_ct_model_ch_force()en un módulo emparejado de fábrica devuelveRbAmpModeError(«módulo emparejado de fábrica: configuración bloqueada») cuando el firmware rechaza la escritura. La vía forzada solo funciona en modo de fábrica.
1.6.0 — 2026-10-22
Las versiones públicas se reanudan con esta versión; las versiones intermedias (1.4.x, 1.5.x) se publicaron solo internamente.
Añade la línea de módulos STD (mapa de registros de 16 bits) junto a los módulos existentes, energía de periodo por canal en módulos de 5/7 canales y una corrección de cambio de calibre para SCT-013. Una sola clase RbAmp sirve a ambas líneas de módulo; el tipo de módulo se detecta automáticamente en begin().
Añadido
- Se aceptan SCT-013-060 y -100 (antes se rechazaban en el cliente por estar reservados); los límites de recorte del modelo de sensor se actualizaron a los valores medidos.
- Línea de módulos STD (mapa de 16 bits), detectada automáticamente. Las lecturas comunes (
voltage,current,power,power_factor,frequency) funcionan en todos los módulos; las llamadas exclusivas de STD lanzanRbAmpNotSupportedErroren un módulo que no las ofrece. - Energía en el propio dispositivo:
dev.read_std_energy()(activa importación/exportación/neta + reactiva, Wh/mWh/µWh, por canal);RbAmp.std_energy_delta(prev, now)(seguro ante cortes de alimentación). - Multifase:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch),dev.read_apparent(ch). - Corriente de arranque:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). dev.read_std_voltage/channel/totals/config/health(),dev.set_time(),dev.is_std; objetos de valorRbAmpStdEnergy/Voltage/Channel/Config/Health;RbAmpNotSupportedError.- Validado en CPython (
smbus2); la ruta de 16 bits de MicroPython está implementada pero aún no validada en hardware. - Energía del periodo por canal en módulos de 5/7 canales:
dev.read_period_avg_power(ch)resuelve todos los canales; la instantánea de periodo y el acumulador de Wh los cubren todos. - Corrección por calificación del cambio de SCT-013: cuando un canal se cambia a un modelo de sensor distinto, corriente, potencia y energía se corrigen al modelo elegido respecto a la ganancia que aplica el módulo; el factor de potencia y la tensión no cambian. Automático;
dev.set_rating_correction(),dev.ct_rating_scale(ch),dev.ct_rating_status(ch). El firmware que realiza esto por sí mismo se detecta y se deja sin cambios. - Guarda de lectura previa a la escritura en las escrituras de clase de sensor / modelo de CT;
dev.set_ct_model_ch_force(),dev.read_sensor_class().
Fijo
- La instantánea de periodo en módulos de 5/7 canales ya no daba error en los canales posteriores al tercero.
1.5.0 — 2026-09-04
Asignación de modelo de CT por canal para todos los canales, soporte de SKU superiores (UI5/UI7), registro de modelos de sensor y corrección de la persistencia. Firmware: v1.4.18+.
Añadido
-
Soporte UI5 / UI7 (SKU superiores): detección automática mediante
REG_TOPOLOGY+REG_HW_VARIANT;dev.channelsdevuelve 5 o 7; todas las lecturas en vivo y por periodo funcionan de forma uniforme parach 0..channels-1. -
Modelo de pinza por canal, cualquier canal:
dev.set_ct_model_ch(channel, code)ydev.read_ct_model_ch(channel)aceptan ahorachannel 0..channels-1. Los canales 0-2 usan la ruta de registros plana; los canales 3 y superiores usan la ventana de acceso por canal (campo 15). -
Validación de modelos basada en el registro: el registro de modelos es ahora la única fuente de códigos de modelo de pinza. Se genera automáticamente en
rbamp/_sensor_models.py; el antiguo diccionario mantenido a mano_CT_ACCEPTEDya no existe. -
RbAmpWindowField.CT_MODEL = 15(enum público). RbAmpFleet.aligned_snapshot()rellena listas por canal para todo el ancho de canales del módulo.
Fijo
- El modelo de pinza / clase de sensor ahora persiste en producción. Las versiones anteriores lo guardaban mediante
CMD_SAVE_GAINS, que está restringido a fábrica: en un módulo de producción el guardado no hacía nada y no se notificaba, así que la asociación se aplicaba en RAM pero se perdía al reiniciar. Ahora persiste medianteCMD_SAVE_USER_CONFIG(sin restricción). Los usuarios de versiones anteriores en producción perdían en silencio la asociación del modelo de pinza en cada reinicio: actualice antes de enviar dispositivos.
1.4.0 — 2026-08-19
Soporte de SKU superiores (UI5/UI7), métricas de tiempo real de canales superiores, instantáneas alineadas con la flota para módulos multicanal.
1.3.1 — 2026-07-30
Modificado
- Se actualizaron los ejemplos de múltiples módulos (
examples_cpython/03_multi_module_broadcast.py,examples_upy/03_multi_module.py) y los ejemplos de balance energético de toda la vivienda (examples_cpython/07_home_energy_balance.py,examples_upy/08_home_energy_balance.py) a la captura coherente General-Call de v1.3 (CAP_GC_LATCH):RbAmpFleet.enable_gc_all()→gc_latch()→check_sync(), que sustituye a la captura secuencial por dispositivo de versiones anteriores a la v1.3. El ejemplo de la vivienda completa publica ahora además el tema MQTThome/energy/sync/in_sync. Parche solo de ejemplos: la API de la biblioteca no cambia.
1.3.0 — Flota + protocolo v1.3
El paquete rbamp Python se alineó con el contrato de cable de rbAmp v1.3 y con el modelo de referencia multiplataforma (Arduino / ESP-IDF / ESPHome / STM32 HAL). Suite de pruebas simuladas: 179/179 PASS.
Añadido
-
RbAmpFleet— gestor de múltiples módulos en el host:scan()(con detección de conflictos y canario de bloqueo de Tier-2),add(),find(),count, iteración;poll_all()por lotes (aislado ante fallos, resistente a MISS);total_power()/total_energy_wh()/poll_errors()en toda la flota; sincronización General-Call (enable_gc_all()/gc_latch()/check_sync());assign_address()/check_conflict(). Límite flexibleRBAMP_FLEET_MAX_MODULES = 16. -
Estructuras POD:
RbAmpFleetPoll(resultado de sondeo por miembro),RbAmpFleetSync(testigo de sincronización GC por miembro). -
Identidad / capacidad:
read_variant()(byte HW_VARIANT 0x55, 1..6 = UI1/UI2/UI3/I1/I2/I3),read_capability()(mapa de funciones u16 LE; ramifique por bits, no por heurísticas de versión),read_product_id()(0x01 = familia de sensores rbAmp),read_uid()(12 bytes),read_label()/set_label()(ASCII de 8 bytes mediante escritura byte a byte). -
Canal de eventos / errores (modelo de dos canales v1.3):
read_last_error()(byte REG_ERROR del dispositivo, una lectura por cable),read_event_flags(),clear_event_flags(mask),has_error()(auxiliar sticky de bit3),clear_error()(CMD_CLEAR_ERROR). -
Configuración de CT por canal:
configure_channels(class, models, n)(en lote, un único guardado final en flash; ajustado a la variante; validación cliente por clase_validate_ct_code);read_ct_model_ch(ch)(lectura del espejo del modelo aplicado desde 0x51-0x53). -
Primitivas de flota por dispositivo:
enable_gc(enable=True)(RMW del indicador REG_the GC_ENABLE de FLEET_CONFIG + guardar + reinicio; ~1 s bloqueante; no-op idempotente si ya es correcto),read_fleet_config(),set_group_id()/read_group_id(),read_gc_tick()(testigo u16; 0xFFFF = nunca recibido),RbAmp.broadcast_latch_group(bus, group, tick)estático (trama GC de 5 bytesA5 27 g tl th). -
Jerarquía de excepciones: base
RbAmpError+RbAmpIOError,RbAmpTimeoutError,RbAmpStaleError,RbAmpParamError,RbAmpModeError,RbAmpVersionError.
Modificado
-
La energía se integra contra el reloj de pared del maestro, nunca contra el
latch_msde diagnóstico del módulo (un temporizador de diagnóstico, no para energía). En CPython usetime.monotonic(); en MicroPython usetime.ticks_ms()+time.ticks_diff(). En una lectura obsoleta (PERIOD_VALID = 0) la biblioteca lanzaRbAmpStaleErrory NO reinicia el ancla; la siguiente instantánea válida cubre el intervalo completo, y el firmware conserva el acumulador, así que la integración sigue siendo exacta, sin doble conteo ni infraconteo. -
Los códigos de modelo de CT son un conjunto aceptado por clase (
SCT_013 {1,2,3,4,5,6,7},WIRED_CT {1,2,3},BUILTIN_CT ∅); un código fuera del conjunto de su clase hace que la biblioteca lanceRbAmpParamErrorantes de cualquier operación I²C.REG_CT_MODELes solo preparación: la vinculación se hace mediante un comando por canal, y las vinculaciones multicanal son independientes del orden en el firmware v1.3 (en v1.x heredado se conserva el patrón defensivo descendente en el ciclo deset_ct_model_ch). -
El cambio de dirección es una confirmación mágica en dos fases apta para producción; no se requiere modo de fábrica.
prepare_address_change()arma el candidato + la ventana magic0xA5de 5 segundos;commit_address_change()emiteCMD_COMMIT_ADDR+ reinicio. La biblioteca garantiza que el estado de armado se borra mediante try/finally si falla a medias; una ventana caducada →RbAmpTimeoutError. Compatible con firmware heredado v1.x mediante un recurso condicionado por capacidad. -
Detección de variante:
read_variant()leeREG_HW_VARIANT(el byte SKU canónico de v1.3). La vía de sondeo por NACK se ha eliminado (el firmware nunca responde con NACK a las lecturas; las lecturas no mapeadas devuelven0x00). -
Escritura de varios bytes byte a byte.
set_label()de la biblioteca escribe los 8 bytes de LABEL con un bucle por byte automáticamente (rbAmp no autoincrementa las escrituras).
Robustez en banco (Etapa 1B)
-
CPython
SMBusBackendexpone un reintento genérico ante NACK (retry_attempts=3,retry_gap_ms=2) con los diagnósticosretry_count_total+retry_exhaustion_count. Se usa en todas las operaciones de cable (las escrituras de configuración siguen la misma disciplina que las lecturas; de lo contrario, una escritura de configuración descartada en silencio en un bus disputado sería invisible). -
MicroPython en ESP32:
MachineI2CBackendmantiene la disciplina de sondeo de i2c_master de IDF a 50 kHz (reintento ante NACK con una espera corta entre intentos, para que un bus disputado no descarte una escritura en silencio). Véase 09 · Referencia de la API → «Detalles del protocolo de cable» para el contrato completo.
Notas
- Bus marginal / hosts basados en ESP32: el mismo driver IDF i2c_master que se usa en proyectos nativos de ESP-IDF puede bloquearse con el bus retenido, por debajo del nivel de la biblioteca. Recomendamos pull-ups externas de ~4.7 kΩ, sin NRST del depurador en producción y un watchdog de tareas a nivel de aplicación en la tarea de sondeo como postura de recuperación. Véase el capítulo 10 · Solución de problemas.
1.1.0 — instantánea de periodo ampliada
Instantánea de periodo ampliada (potencia P máxima, diagnóstico latch_ms), contabilidad de Wh en el lado del maestro.
1.0.0 — Versión inicial
Medición RT de un único dispositivo (U / I / P / PF / frecuencia eficaces RMS), integración de energía por periodo (Wh), configuración de CT-model y sensor-class, y cambio de dirección I²C. Doble backend (CPython smbus2 / machine.I2C de MicroPython).
Fuente e incidencias: rb-amp/rbamp-python · esta página en el repositorio: docs/11_changelog.md (v1.6.1)