11 · Registro de cambios
Historial de versiones del componente externo rbamp para ESPHome. Esta página refleja CHANGELOG.md del repositorio, que es la fuente canónica.
Las versiones públicas se reanudan con la v1.9.0; las versiones intermedias que aparecen más abajo se publicaron solo internamente.
Contents:
- v1.9.1 — 2026-11-01
- v1.9.0 — 2026-10-21
- v1.8.1 — 2026-10-18
- v1.8.0 — 2026-10-17
- v1.7.0 — 2026-09-30
- v1.6.0 — 2026-09-04
- v1.5.0: 2026-08 (solo interno)
- v1.4.0
- v1.3.0
- Política de obsolescencia
- Guía de actualización
v1.9.1 — 2026-11-01
Bancos de snapshot STD en el YAML, los modelos de pinza de 50 A y 100 A, y un mensaje claro cuando un módulo emparejado de fábrica rechaza una escritura de configuración.
Añadido
-
Bancos de instantáneas (
period_banks:) para los módulos que los anuncian (línea de 16 bits, imagen 0x7E y posteriores): potencia media por período, energía, picos y duración del período en cualquiera de los ocho bancos del módulo, tomados coninterval:y/o con la nueva acciónrbamp.latch_bank. Los valores de energía por período son por período (state_class: measurement), no contadores. La primera toma tras el arranque o el reinicio del módulo solo inicia el período. Ejemplo:example/std_banks.yaml. -
Pruebas en host de la lógica de bancos:
tests/host/test_std_bank.cpp(g++simple, sin framework). -
Registro de modelos de sensor: los códigos 11 (50 A, 33 Ω) y 13 (100 A, 20 Ω) ya están caracterizados y se aceptan sin la indicación de «reservado».
Fijo
- En firmware 1.4.22 y posteriores, un módulo emparejado de fábrica (clase
WIRED_CT/BUILTIN_CT) rechaza las escrituras de clase y modelo en funcionamiento normal, incluso conct_model_force: true(la forzada funciona solo en modo de fábrica). El componente ahora informa «módulo emparejado de fábrica: configuración bloqueada» en lugar de un error genérico de parámetro, y una escritura individual rechazada dect_model:ya no se persiste ni va seguida de la corrección de la potencia nominal.
v1.9.0 — 2026-10-21
Las versiones públicas se reanudan con esta versión; las versiones intermedias se publicaron solo internamente.
Cambio del rango del SCT sin perder la precisión de fábrica (línea de 8 bits), y las protecciones de la versión 1.8.x incorporadas en esta versión pública.
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.
-
Corrección por cambio de rango del SCT (módulos con la clase de sensor SCT-013, firmware ≤ 1.4.19). Cada módulo SCT se calibra en fábrica con el sensor -030; al seleccionar otro
ct_model:, la corriente, la potencia y la energía seguían en la escala del -030. Ahora el componente completa la escritura del modelo con el reinicio del módulo que exige el procedimiento (guardar → reiniciar → volver a sondear con comprobación de UID), lee la ganancia que el módulo aplica de verdad y escala la corriente, la potencia activa y reactiva y la integración de energía al rango del sensor seleccionado; la corrección de fábrica por unidad se conserva. La tensión y el factor de potencia no se ven afectados. Un reinicio del módulo (propio o externo) se detecta y la corrección se recalcula automáticamente. Si la ganancia aplicada queda fuera de ±5 % del valor del modelo de calibración, el componente avisa y no escala. No hace falta ningún cambio en YAML. -
El firmware 1.4.20+ realiza el cambio de rango en el propio dispositivo y lo anuncia: el componente lo detecta y deja las lecturas sin tocar (escritura de modelo simple, sin reinicio).
-
Prueba en host para la lógica de decisión de corrección:
tests/host/test_sct_rating.cpp(g++simple, sin framework).
v1.8.1 — 2026-10-18
Fijo
-
Protección de la calibración de fábrica para
sensor_class:/ct_model:(línea de 8 bits). El firmware borra los modelos de canal y las formas de linealidad en cualquier escritura de clase de sensor (incluso con un valor sin cambios) y vuelve a aplicar el preajuste genérico en cualquier escritura de modelo de CT: el componente ahora nunca escribe un valor que el dispositivo ya tiene, y rechaza los cambios de clase/modelo desde el YAML en un módulo calibrado en pareja con su sensor integrado (clasesWIRED_CT/BUILTIN_CT), con una línea de registro explícita. La nueva opción de servicioct_model_force: truevuelve a aplicar el preajuste de forma deliberada; el esquema la rechaza sin una clave de modelo, para que no pueda quedarse activada en el YAML. -
Lectura fuera de límites en módulos de 5/7 canales (UI5/UI7): el bucle de publicación de restauración en el arranque indexaba los arrays de exportación de 3 ranuras hasta el canal 6 y podía publicar un valor basura en el sensor contiguo. Corregido con el mismo control de canal que ya tenían el resto de puntos de exportación; los tamaños de los arrays ahora se fijan con aserciones de compilación.
-
Documentación y comentarios alineados con la ventana de medición de la familia de 100 ms (firmware v1.2+; 200 ms solo en imágenes antiguas).
v1.8.0 — 2026-10-17
Energía acumulada en el propio dispositivo para la línea de 16 bits.
Añadido
-
Energía desde contadores del propio dispositivo (módulos de mapa de 16 bits que los anuncian en el mapa de capacidades): el componente deja de integrar Wh por sí mismo y acumula los contadores propios del módulo; los totales sobreviven a reinicios tanto del ESP32 como del módulo, sin deriva de integración. Resolución micro (µWh/µvarh) en el firmware que la publica, y respaldo automático en grueso en caso contrario. Cada snapshot se lee en una única transacción I²C coherente, y las sumas publicadas se mantienen monótonas tras reinicios del módulo y reinicios de contador.
-
Nuevos sensores de total general:
energy_total,energy_exported_total,energy_net(importación − exportación, puede bajar),reactive_energy,reactive_energy_exported. -
start_current_ua:clave de configuración para la energía (0 = desactivado, 10..2540 en pasos de 10 µA): por debajo de esta corriente un canal no acumula energía; en vacío, la potencia medida es ruido de cualquier signo que, de otro modo, se colaría tanto en la importación como en la exportación. Las lecturas no se ven afectadas. Se valida con el esquema y se guarda en el dispositivo con un guardado verificado. -
Superficies trifásicas:
voltage_angle_b/voltage_angle_c(grados, respecto a la fase A) yphase_sequence(1 directa · 2 inversa · 3 anormal), publicados en firmware que los proporcione; «unknown» en caso contrario. -
Accesores lambda:
get_std_image_version(),get_phase_sequence_str(),read_start_current_ua().
v1.7.0 — 2026-09-30
Compatibilidad con la nueva línea de módulos de mapa de registros de 16 bits, detectada automáticamente con el mismo YAML.
Añadido
-
Soporte de doble línea: una sonda de identidad al arrancar detecta módulos de mapa de 16 bits y cambia el transporte (puntero big-endian, lecturas en ráfaga con autoincremento). El número de canales, la variante y las capacidades vienen del bloque de descubrimiento del dispositivo:
topology:y los recuentos de ranuras en el YAML ya no son necesarios para dimensionar la superficie de entidades. Los módulos de 8 bits se comportan exactamente como antes. -
Los sensores en tiempo real de la línea de 16 bits se publican desde los registros de punto fijo del dispositivo; la energía usa las instantáneas atómicas de cierre del dispositivo con integración del reloj del maestro y la misma persistencia NVS.
-
Las claves de configuración (
sensor_class:,ct_model:,new_address:) funcionan en la línea de 16 bits mediante su bloque de configuración por etapas, con un guardado verificado de forma síncrona. Losct_models:por canal en esta línea requieren que el dispositivo anuncie mapas persistentes por canal (bit de capacidad); el componente lo rechaza de forma explícita en lugar de perder la escritura en silencio. -
Recuperación automática tras un reinicio del módulo en plena ejecución: el componente detecta que el acumulador se ha desarmado, lo vuelve a armar y lo reinicia, saltando una ventana en lugar de dejar de acumular energía en silencio.
-
Volcado de NVS al apagarse limpiamente (reinicio/OTA ya no pierde hasta el último intervalo de guardado de energía).
v1.6.0 — 2026-09-04
ct_models: por canal para todos los canales (0..15), registro de modelos de sensor y corrección de persistencia. Firmware: se requiere v1.4.18+ para canales superiores 3+.
v1.5.0: 2026-08 (solo interno)
Añadido
- Soporte de los SKU de gama alta UI5/UI7: los canales 3–6 se leen mediante la ventana de acceso a canales (métricas en tiempo real y energía por período de cada canal), y las ranuras de energía NVS se amplían a 7 canales.
Añadido
-
Modelos de CT por canal en todos los canales.
ct_models:en el YAML acepta ahora hasta 16 entradas. La detección de la variante del módulo determina cuántas se aplican; las entradas adicionales generan una advertencia, no un fallo. -
Registro de modelos de sensor: la lista de modelos procede de un único registro. Las dos listas fijas en el código (el diccionario
CT_MODELS+CT_MODEL_ALLOWED_PER_CLASS) se sustituyen por una única consulta al registro. Añadir un nuevo SKU de CT es ahora una edición del registro, sin publicar una nueva versión de la biblioteca.
Fijo
- v1.6.0 añade GUARDAR tras el ciclo de aplicación. Las versiones anteriores usaban una ruta de persistencia bloqueada por fábrica para el modelo de CT y la clase de sensor: en un módulo de producción la vinculación se aplicaba a la RAM pero se perdía al reiniciar. La v1.6.0 persiste mediante
CMD_SAVE_USER_CONFIG(sin bloqueo). Los usuarios de versiones anteriores en producción perdieron en silencio la vinculación del modelo de CT en cada reinicio: actualice antes de enviar dispositivos.
v1.4.0
Detección de SKU de gama alta (variantes de 5/7 canales), ventana de acceso a canales para métricas en tiempo real y la clave opcional latch_interval:, que desacopla la cadencia de latch/energía de la cadencia de lectura (update_interval:). La energía se mantiene monótona y precisa: la integración usa el tiempo real de pared transcurrido entre eventos de latch.
v1.3.0
Primera versión pública. Flota de varios canales y varios módulos con sincronización de cierre por llamada general (fleet_gc_enable: + group_id:), confirmación de dirección en dos fases (lista para producción, sin modo de aprovisionamiento de fábrica), escritura de restauración leer-comparar-escribir en el arranque, detección de funciones condicionada por capacidad, superficie de identidad para lambdas (get_variant_str(), get_uid_hex(), ...) y persistencia de energía en NVS.
Política de obsolescencia
Lo que el componente promete no romper sin aviso, y lo que puede cambiar:
| Superficie | Estabilidad | Lo que prometemos |
|---|---|---|
Claves YAML del bloque rbamp: |
Estable | La eliminación o el cambio de nombre solo es posible en un salto de versión mayor. Aparece un aviso de obsolescencia en el registro antes de la eliminación. broadcast_latch: y topology: se mantienen en el esquema por compatibilidad con versiones anteriores. |
Claves YAML de sensor.platform: rbamp (ranuras) |
Estable | Mismas reglas. Los nombres voltage/current/power/energy/frequency/power_factor están fijados como contrato con el panel de energía de HA. |
El conjunto de entidades de HA y sus device_class / state_class |
Estable | No lo cambiaremos sin anunciarlo; afecta al entity_id en HA. |
Métodos RbAmpComponent::* accesibles desde lambda |
Inestable | Estos valores pueden cambiar en versiones menores. Si escribe acciones lambda contra ellos, fije la versión del componente (ref: en external_components:). |
| Formato de la estructura NVS | Versionado | Los cambios llevan aparejado un incremento de la versión de diseño: los datos antiguos se descartan, nunca se interpretan mal. |
Nombres y comportamiento del bloque i2c: |
Externo | Esto es el núcleo de ESPHome, no nuestro: siga la política aguas arriba. |
Guía de actualización
A v1.9.0 (desde cualquier versión anterior)
- Defina
ref: v1.9.0enexternal_components:. - No hace falta cambiar el YAML. El mismo YAML sirve para ambas líneas de módulos; el componente identifica el módulo conectado al arrancar.
topology:no es necesario. - Si quiere totales de energía de todos los canales en un módulo STANDARD (STD), añada
energy_total/energy_exported_total/energy_net(vea 09 §2.3). - Si su YAML define
sensor_class:oct_model:en un módulo suministrado calibrado junto con su sensor ajustado, el componente ahora rechaza el cambio y lo registra en el log. Elimine esas claves para tales módulos. - Si cambió la potencia nominal de la SCT mediante
ct_model:, las lecturas ahora se mantienen precisas; un reinicio del módulo durante el cambio es normal en firmware hasta 1.4.19. ct_model_force: truees solo una opción de servicio; el esquema lo rechaza si no hayct_model:/ct_models:.- Los valores de energía por canal en NVS se conservan al actualizar; los nuevos sensores de total general empiezan en 0 en el primer arranque y luego acumulan (su ranura NVS es independiente).
Desde v1.3 / v1.4
- Actualice
ref:. SCT_013_100(código 5) ySCT_013_060(código 7) son aceptados.- Opcionalmente añada
fleet_gc_enable:/group_id:para instantáneas sincronizadas en un despliegue de varios módulos (módulos BASIC).
Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/11_changelog.md (v1.9.1)