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

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 en begin(): 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 lanza RbAmpNotSupportedError. 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ñade avg_p_total, wh_net y module_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) (un RbAmpStdLatch: P/Q/S, picos, energía en mW·muestras, energía y potencia media por canal) y RbAmp.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 ahora RbAmpNotSupportedError en 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 devuelve RbAmpModeError («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

Nota

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 lanzan RbAmpNotSupportedError en 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 valor RbAmpStdEnergy/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.channels devuelve 5 o 7; todas las lecturas en vivo y por periodo funcionan de forma uniforme para ch 0..channels-1.

  • Modelo de pinza por canal, cualquier canal: dev.set_ct_model_ch(channel, code) y dev.read_ct_model_ch(channel) aceptan ahora channel 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_ACCEPTED ya 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 mediante CMD_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 MQTT home/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 flexible RBAMP_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 bytes A5 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_ms de diagnóstico del módulo (un temporizador de diagnóstico, no para energía). En CPython use time.monotonic(); en MicroPython use time.ticks_ms() + time.ticks_diff(). En una lectura obsoleta (PERIOD_VALID = 0) la biblioteca lanza RbAmpStaleError y 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 lance RbAmpParamError antes de cualquier operación I²C. REG_CT_MODEL es 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 de set_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 magic 0xA5 de 5 segundos; commit_address_change() emite CMD_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() lee REG_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 devuelven 0x00).

  • 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 SMBusBackend expone un reintento genérico ante NACK (retry_attempts=3, retry_gap_ms=2) con los diagnósticos retry_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: MachineI2CBackend mantiene 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)