09 · Referencia del esquema YAML
Este capítulo es la referencia completa del esquema YAML del componente externo rbamp para ESPHome. Si una clave no aparece aquí, no existe en el esquema.
Un solo YAML para ambas líneas de módulos. Al arrancar, el componente identifica qué línea de módulos está conectada (BASIC o STANDARD (STD)) y se adapta automáticamente: el número de canales, la variante y las funciones disponibles vienen del propio módulo, así que no hacen falta la clave topology: ni cambiar de nivel en el YAML. Las claves que se aplican a una sola generación están marcadas abajo; una clave que el módulo conectado no puede atender se ignora con una línea de log, nunca con un fallo fatal.
Contents:
- Bloque de componente:
rbamp: - Plataforma de sensor:
sensor.platform: rbamp - Flujo de datos y temporización
- Ajustes del bus I²C
1. Bloque del componente — rbamp:
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling) · Problemas multimódulo (troubleshooting)
El bloque rbamp: de nivel superior registra una instancia del componente. Hereda de PollingComponent (que proporciona update_interval) y de i2c.I2CDevice (que proporciona address y el manejador del bus I²C). MULTI_CONF: True significa que puede haber cualquier número de bloques rbamp: en un mismo YAML, cada uno referenciando su propio esclavo I²C.
rbamp:
id: meter1
address: 0x50
update_interval: 60s
drdy_pin: GPIO4
sensor_class: SCT_013
ct_model: SCT_013_030
# or, for a UI3 with mixed clamps:
# ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
bidirectional: false
new_address: 0x51
fleet_gc_enable: false
group_id: 0
latch_interval: 60s
start_current_ua: 400 # STANDARD only, see below
# ct_model_force: true # service option, see below
Todas las claves son opcionales. topology: y broadcast_latch: se siguen aceptando por compatibilidad con versiones anteriores (vea sus entradas).
id
| Atributo | Valor |
|---|---|
| Tipo | id (identificador de ESPHome) |
| Predeterminado | Generado automáticamente |
| Obligatorio | No |
Asigna un identificador estable a la instancia. Los sensores lo referencian mediante rbamp_id: meter1. Con varios bloques rbamp:, es obligatorio un id explícito.
rbamp:
id: kitchen_meter
address
02 · Inicialización y arranque (initialization) · 3.6 Algoritmo canónico de detección (api-reference) · 6 · Secuencias de protocolo (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | i2c_address (7 bits, 0x08..0x77) |
| Predeterminado | 0x50 |
| Obligatorio | No |
La dirección I²C actual del módulo rbAmp. La dirección de fábrica por defecto es 0x50. Tras aplicar un cambio de dirección (mediante new_address), actualice esta clave al nuevo valor y elimine new_address.
Rango válido: 0x08..0x77 (se excluyen las direcciones I²C reservadas de 7 bits).
rbamp:
address: 0x52 # three modules on the bus: 0x50, 0x51, 0x52
Referencia cruzada: el protocolo del bus I²C en la referencia de la API; cambio de dirección en ejecución para cambiar la dirección tras el arranque.
update_interval
04 · Medición por período y contabilidad tarifaria (period-metering) · Ciclo de sondeo continuo (recomendado) (period-metering) · Registros de instantánea de período (period-metering)
| Atributo | Valor |
|---|---|
| Tipo | time (cadena de duración de ESPHome) |
| Predeterminado | 60s |
| Obligatorio | No |
Con qué frecuencia se ejecuta update(). En cada llamada:
- Envía el comando de instantánea y programa un tiempo de espera no bloqueante de 50 ms para leer la instantánea del período (módulos BASIC; en los módulos STANDARD la energía procede de sus propios contadores, véase
energy_total). - Comprueba el registro de estado; si el módulo está listo, publica todos los sensores instantáneos enlazados.
El valor por defecto de 60 s es razonable: el módulo actualiza internamente su potencia media de período aproximadamente cada ~100 ms, pero integrar la energía en el lado del maestro requiere una ventana lo bastante larga para ser correcta. Con 60 s y una carga media de 60 W, una instantánea perdida pierde ≤ 1 Wh.
El valor mínimo permitido es 1s: el esquema rechaza cualquier valor menor, y esphome config informa de un diagnóstico. Valores por debajo de 5-10 s no aportan nada para una sincronización estrecha y solo saturan el bus.
rbamp:
update_interval: 30s # more frequent dashboard updates, more traffic
latch_interval
Ciclo de sondeo continuo (recomendado) (period-metering) · 4.11 Bloque de período V03 (0xBE..0xCF) (api-reference) · 6.4 Sincronización de período: dos estrategias (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | time (cadena de duración de ESPHome) |
| Predeterminado | Igual que update_interval |
| Obligatorio | No |
| Desde | v1.4 |
Con qué frecuencia el componente envía el comando de instantánea e integra una muestra de Wh. Cuando se define, desacopla el ciclo de instantánea de la cadencia de lectura en tiempo real: update_interval: sigue controlando con qué frecuencia se leen y publican los registros V/I/P/PF/Q, mientras que latch_interval: controla con qué frecuencia se toma la instantánea del acumulador de período y se integra Wh.
La integración de energía no añade error propio más allá de la precisión de potencia activa del módulo, con independencia de la relación: la integración en el maestro usa el dt de reloj de pared real entre eventos de instantánea sucesivos, así que intervalos de instantánea más largos solo producen pasos de integración más gruesos.
Debe ser >= update_interval (definirlo más corto se rechaza en la validación de la configuración: los snapshots extra no producirían datos observables).
Si no se define, el snapshot se ejecuta en cada llamada a update() (comportamiento de cadencia única de la v1.3, compatible con versiones anteriores).
rbamp:
update_interval: 3s # RT V/I/P/PF refreshed every 3 s
latch_interval: 60s # snapshot + Wh integration once a minute
Útil cuando importan la carga del bus o la competencia de CPU en el maestro: flotas de varios módulos, hosts ESP8266 (un solo núcleo; las ISR de WiFi compiten por la CPU durante las transacciones I²C) o buses I²C compartidos con otros dispositivos.
drdy_pin
01 · Conexión de hardware (hardware-connection) · 03 · Sondeo en tiempo real (realtime-polling)
| Atributo | Valor |
|---|---|
| Tipo | gpio_input_pin_schema |
| Predeterminado | Ninguno (opcional) |
| Obligatorio | No |
Conecta la salida de drenador abierto DRDY del módulo a un GPIO del ESP32. Cuando se especifica, el pin se configura en setup() al arrancar.
El pin aparece en dump_config, pero no se usa como disparador de lectura: los registros instantáneos se sondean con update_interval. Declarar el pin no cambia el comportamiento.
rbamp:
drdy_pin: GPIO4
sensor_class
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)
| Atributo | Valor |
|---|---|
| Tipo | enum (SCT_013, WIRED_CT, BUILTIN_CT) |
| Predeterminado | SCT_013 |
| Obligatorio | No |
Fija la familia del sensor de corriente en el lado del módulo. En firmware v1.2+ el valor se escribe en flash y se convierte en una condición previa para escribir el modelo de CT: el módulo rechazará escribir el modelo si la clase no está definida. En firmware anterior el esquema acepta el valor y se aplica automáticamente al actualizar.
| Valor | Significado |
|---|---|
SCT_013 |
Pinzas SCT-013 de núcleo partido — el valor por defecto |
WIRED_CT |
Módulo suministrado calibrado junto con su propio sensor ajustado |
BUILTIN_CT |
Módulo suministrado calibrado junto con su propio sensor integrado |
Guarda de escritura. El componente nunca escribe una clase que el módulo ya tiene (un arranque repetido no escribe nada). En un módulo que se calibró como pareja con su sensor ajustado (WIRED_CT / BUILTIN_CT), un cambio de clase o modelo desde el YAML se rechaza con una línea de log explícita: la escritura sustituiría la calibración individual por un ajuste genérico. Deje sensor_class: y ct_model: fuera del YAML para estos módulos, o vea ct_model_force.
rbamp:
sensor_class: SCT_013 # default; may be omitted
Para más información sobre cómo elegir la pinza y la familia, véase 03_sensor_selection.md.
ct_model
Configuración de la clase de sensor y del modelo de CT (initialization) · 6.2 Enlace del modelo de CT: preparación pura + CMD por canal (api-reference) · 8.6 Aprovisionamiento de firmware nuevo (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | enum (SCT_013_005, _010, _020, _030, _050) |
| Predeterminado | Ninguno (opcional) |
| Obligatorio | No |
Escribe el identificador del modelo de pinza de CT en la flash del módulo. En firmware v1.2+ esto carga automáticamente los coeficientes de fábrica del modelo elegido: no hacen falta pasos de calibración adicionales. Un valor igual al que ya tiene el módulo no se escribe.
| Valor YAML | Código | Corriente nominal | Estado v1.3 |
|---|---|---|---|
SCT_013_005 |
1 | 5 A | producción |
SCT_013_010 |
2 | 10 A | producción |
SCT_013_020 |
6 | 20 A | producción (nuevo en v1.3) |
SCT_013_030 |
3 | 30 A | producción (SKU predeterminado) |
SCT_013_050 |
4 | 50 A | producción |
El conjunto de códigos aceptados por clase para SCT_013 es {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 es el código 5, SCT_013_060 es el código 7; el orden de los códigos no es el orden de los rangos). Los valores no coincidentes se rechazan en esphome config mediante cv.Invalid. Para más información, véase 03 · Selección del sensor de corriente.
rbamp:
ct_model: SCT_013_030
Se aplica una vez en setup(). Cada escritura va acompañada de una escritura en flash de ~700 ms (el módulo hace NACK a todas las operaciones I²C durante ese tiempo; el componente alimenta el watchdog automáticamente).
Cambiar el rango del SCT mantiene la precisión. Cada módulo SCT se calibra en fábrica con el SCT-013-030. Al seleccionar otro rango, la corriente, la potencia y la energía siguen siendo correctas: en firmware hasta la 1.4.19 el componente completa la escritura del modelo con un reinicio del módulo (forma parte del flujo normal y aparece en el registro) y después escala las lecturas al sensor seleccionado; los firmware más nuevos hacen el cambio en el propio módulo y el componente deja las lecturas sin tocar. La tensión y el factor de potencia no se ven afectados. Para esto no hace falta ningún cambio en YAML.
Protección de escritura. Nunca se escribe un valor igual, y en un módulo emparejado en fábrica (sensor_class: WIRED_CT / BUILTIN_CT) la escritura se rechaza con una línea de registro: véase sensor_class.
Mutuamente excluyentes con ct_models: — solo puede usarse uno de los dos por bloque rbamp:.
Para más información, vea 03_sensor_selection.md. Referencia cruzada: la referencia de ct_model.
ct_models
| Atributo | Valor |
|---|---|
| Tipo | lista de 1–16 valores enumerados |
| Predeterminado | Ninguno (opcional) |
| Obligatorio | No |
Modelos de pinza de CT por canal, para módulos con pinzas mixtas en distintos canales. Acepta los mismos valores de enumeración que ct_model:. El esquema acepta de 1 a 16 entradas; la posición en la lista es el índice del canal. El componente aplica tantas entradas como canales tenga el módulo (1 para UI1, 2 para UI2, 3 para UI3, y así sucesivamente); las entradas sobrantes se ignoran con un aviso.
rbamp:
id: ui3_meter
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby loads (maximum resolution),
# CH1=30A for main household loads,
# CH2=20A for a water heater / medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)
En firmware v1.2+ cada canal tiene su propio conjunto de coeficientes de fábrica, de forma independiente. El tiempo total de configuración al arrancar es de ~2-3 segundos (~700 ms de escritura en flash por canal).
Módulos STANDARD. Los modelos por canal solo los guardan los módulos que anuncian almacenamiento persistente por canal. En un módulo que no lo hace, el componente lo rechaza de forma explícita (una advertencia de que ct_models: no está soportado por este dispositivo, claves ignoradas) en lugar de escribir un valor que se revertiría en silencio tras un corte de alimentación: use allí el ct_model: único.
Se aplican las mismas guardas de escritura que para ct_model: (los valores iguales no se escriben; los módulos emparejados de fábrica rechazan el cambio).
Mutuamente excluyente con ct_model:.
ct_model_force
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predeterminado | false |
| Obligatorio | No |
Opción de servicio. Anula la protección de escritura: el componente aplica entonces el preajuste ct_model: / ct_models: aunque el módulo esté emparejado en fábrica o ya tenga el mismo valor. Esto sustituye la calibración individual del módulo por el preajuste genérico de ese modelo, así que úselo solo de forma deliberada, ejecútelo una vez y elimínelo.
El esquema rechaza ct_model_force: true a menos que también esté presente ct_model: o ct_models:, así que el indicador no puede quedar armado en el YAML esperando una línea de modelo posterior.
rbamp:
ct_model: SCT_013_030
ct_model_force: true # one-off; remove both lines after the operation
start_current_ua
| Atributo | Valor |
|---|---|
| Tipo | entero, microamperios |
| Valores permitidos | 0 (desactivado) o 10..2540 en pasos de 10 |
| Predeterminado | Ninguno (se aplica el valor por defecto del propio módulo) |
| Obligatorio | No |
| Se aplica a | Módulos STANDARD con contadores de energía en el dispositivo; se ignoran con un aviso en el resto |
Corriente de arranque para la contabilidad de energía. Mientras la corriente de un canal esté por debajo de este valor, el módulo no cuenta energía en ese canal. Sin ella, en vacío la potencia medida es ruido de cualquier signo que se cuela lentamente tanto en el contador de importación como en el de exportación. Las lecturas instantáneas (corriente, potencia, ...) no se ven afectadas: solo los contadores de energía.
Los valores fuera del conjunto permitido (por ejemplo 15 o 3000) los rechaza el esquema, así que un valor no válido nunca llega al bus. El ajuste se guarda en el módulo y se verifica tras la escritura; un valor igual al guardado no se vuelve a escribir.
rbamp:
start_current_ua: 400
Puede leer de vuelta el valor guardado desde un lambda con id(meter1).read_start_current_ua() (devuelve 65535 si no está disponible).
period_banks
| Atributo | Valor |
|---|---|
| Tipo | lista de entradas de banco |
| Entradas por lista | 1..8, cada bank: (0..7) listado una vez |
| Predeterminado | Ninguna |
| Obligatorio | No |
| Se aplica a | Módulos STANDARD que anuncian bancos de snapshot (imagen 0x7E y posteriores); en cualquier otro módulo las entradas siguen no disponibles y el log lo indica una vez al arrancar |
El módulo mantiene ocho bancos de instantáneas independientes. Cada entrada mide un período: el tiempo entre dos tomas del mismo banco, medido con el reloj del ESP32, y publica los promedios, picos y energía del período. Úselo para «energía por hora», «corriente máxima desde la última pulsación» y preguntas similares que los totales acumulados no responden.
| Clave | Significado |
|---|---|
bank |
Número de banco de 0 a 7. El banco 0 está libre en los módulos con contadores de energía en el dispositivo; en un módulo sin contadores el componente usa el propio banco 0 y la entrada se ignora con un aviso. |
interval |
Cadencia automática opcional de la toma, de al menos 1s. Sin ella, el banco solo se toma con la acción rbamp.latch_bank. |
power, reactive_power, apparent_power |
Media del periodo. |
energy, energy_exported |
Wh importados / exportados en el periodo (no contadores: llevan state_class: measurement). |
max_power, max_current, max_voltage, min_voltage |
Extremos dentro del periodo. |
period_length |
La duración del periodo en segundos, medida por el ESP32. |
channels |
Lista opcional, una entrada por canal de corriente (la primera entrada = canal 0), cada una con power, energy, energy_exported. |
El primer latch de un banco tras el arranque, o tras reiniciarse el módulo, solo inicia el periodo; sus valores se descartan y los sensores publican desde el siguiente latch. Los latches de bancos distintos se mantienen separados al menos 150 ms.
rbamp:
id: meter1
period_banks:
- bank: 1
interval: 1h
power: {name: "Hour average power"}
energy: {name: "Hour energy"}
max_current: {name: "Hour peak current"}
- bank: 2 # latched by hand
energy: {name: "Energy since last press"}
period_length: {name: "Since last press, s"}
button:
- platform: template
name: "Latch bank 2"
on_press:
- rbamp.latch_bank:
id: meter1
bank: 2
Hay un ejemplo completo en example/std_banks.yaml.
bidirectional
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predeterminado | false |
| Obligatorio | No |
Activa la ruta de energía exportada por canal (energy_exported, energy_exported_1, energy_exported_2). Con true, la energía exportada se acumula por separado de la importada.
En un módulo STANDARD la energía exportada procede de los contadores del propio módulo, así que sobrevive a los reinicios y es monótona. En un módulo BASIC la línea es unidireccional: los sensores energy_exported_* los acepta el esquema pero publican 0.
Declare energy_exported (o _1 / _2) bajo sensor.platform: rbamp solo cuando esté definido bidirectional: true. Los sensores de total general energy_exported_total y energy_net no necesitan esta clave.
rbamp:
bidirectional: true # needed for the per-channel energy_exported* sensors
new_address
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)
| Atributo | Valor |
|---|---|
| Tipo | i2c_address (0x08..0x77) |
| Predeterminado | Ninguno (opcional) |
| Obligatorio | No |
Dispara un cambio de dirección I²C único al arrancar. Debe ser distinta de address: el validador lanza un error si son iguales.
En firmware v1.3 se usa una confirmación en dos fases: listo para producción sin protección por aprovisionamiento de fábrica. Comportamiento de compatibilidad:
| Firmware | Comportamiento |
|---|---|
| Anuncia la confirmación de dirección en dos fases (v1.3+) | Ruta de producción: escritura en fase de preparación, confirmación explícita, commit, reenumeración. |
| No lo anuncia (v1.0-v1.2 heredado) | Ruta heredada: escritura de una sola fase, requiere el modo de aprovisionamiento de fábrica. Registra WARN_FACTORY_MODE_REQUIRED si no está en modo de aprovisionamiento. |
Los módulos STANDARD también admiten new_address:; el componente la aplica y se vuelve a enlazar con la nueva dirección del mismo modo.
El flujo completo se ejecuta una vez en setup():
- Sondee la
addressactual. Si el módulo no responde ahí pero sí responde ennew_address, el componente se adapta a la nueva dirección con una advertencia (suponiendo que un arranque anterior ya aplicó el cambio) y omite la escritura. - Compruebe si el firmware anuncia la confirmación en dos fases. Sí → ruta de producción (véase más abajo). No → ruta heredada con la comprobación del modo de aprovisionamiento.
- Ruta de producción (v1.3): prepare la nueva dirección, confirme, ejecute el commit → espere ~700 ms → vuelva a sondear
new_address. No se requiere ningún control del modo de fábrica. - Ruta heredada (v1.0-v1.2): escritura monofásica; requiere el modo de aprovisionamiento de fábrica en el lado del módulo.
- El componente cambia su dirección I²C interna mediante
i2c::I2CDevice::set_i2c_address()anew_addressy verifica que el módulo responde. - Si el módulo no responde tras el cambio, el componente llama a
mark_failed()y se detiene.
Tras un cambio correcto: actualice el YAML a address: y elimine new_address:. Si en el siguiente arranque el módulo está en la nueva dirección pero new_address: sigue en el YAML, la sonda de arranque de la dirección antigua falla, la sonda de la nueva dirección tiene éxito, el componente se adapta con un aviso y no se vuelve a escribir nada.
⚠ Solo en modo de fábrica en firmware antiguo (v1.0-v1.2).
Los módulos de producción estándar con firmware antiguo se entregaron con el modo de aprovisionamiento desactivado. Escribir new_address: en un módulo así sin modo de fábrica se rechazará (aviso WARN_FACTORY_MODE_REQUIRED). En firmware v1.3 esta restricción desaparece: el componente detecta la ruta de producción automáticamente.
⚠ Reenumeración tras el commit. Tras un commit correcto el módulo se reinicia y se reenumera en la nueva dirección. Las llamadas posteriores dentro del mismo setup() se dirigen a la nueva dirección de forma transparente, pero cualquier otro maestro del bus (una herramienta I²C en bruto, una sonda de depuración, otro ESP32) sigue considerando el módulo en la dirección antigua hasta que actualice su propio estado.
rbamp:
address: 0x50
new_address: 0x51 # remove this line after the first successful boot
Recuperación: si se aplicó el cambio de dirección pero el módulo no responde, vea 10_troubleshooting.md → «Dirección cambiada, pero el módulo no responde».
Referencia cruzada: la referencia del cambio de dirección en tiempo de ejecución.
fleet_gc_enable (NUEVO en v1.3)
Llamada general (broadcast en la dirección 0x00) (inicialización) · Varios módulos — snapshot simultáneo (medición por periodos) · 4.4 Configuración de flota (0x27..0x2F) (referencia de la API)
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predeterminado | false |
| Obligatorio | No |
| Se aplica a | Módulos BASIC con soporte de snapshot de llamada general (firmware v1.3+); se ignora con una línea de log en STANDARD |
Opcional: activa la recepción del broadcast de snapshot de llamada general desde el maestro. Cuando el ESP32 emite una trama GC de 5 bytes a la dirección 0x00, todos los módulos con fleet_gc_enable: true (y un group_id: coincidente) toman de forma atómica un snapshot de sus acumuladores de periodo en un único instante del bus. Esto proporciona sincronización estrecha entre submedidores.
Comportamiento de capacidad: al arrancar el componente comprueba si el firmware anuncia el snapshot de llamada general. Si no lo anuncia → advertencia + omisión sin aplicar:
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).
Persistencia: al aplicar, el componente escribe REG_FLEET_CONFIG.bit0, guarda en flash mediante CMD_SAVE_USER_CONFIG y REINICIA el dispositivo: el modo GC se configura en la inicialización, no es conmutable en vivo. Mediante lectura-comparación-escritura esto ocurre una sola vez en el primer arranque; los arranques posteriores lo omiten.
rbamp:
- id: mains
fleet_gc_enable: true # opt-in, capability-gated
group_id: 1 # see below
- id: boiler
fleet_gc_enable: true
group_id: 1 # same group → synchronized
Referencia cruzada: la referencia de Group-Commit de la flota, 04_hardware.md Bus de varios módulos.
group_id (NUEVO en v1.3)
Llamada general (broadcast en la dirección 0x00) (inicialización) · Varios módulos — snapshot simultáneo (medición por periodos) · 4.4 Configuración de flota (0x27..0x2F) (referencia de la API)
| Atributo | Valor |
|---|---|
| Tipo | uint8_t (0..255) |
| Predeterminado | 0 |
| Obligatorio | No |
| Se aplica a | Módulos BASIC; se ignoran con una línea de registro en STANDARD |
Un identificador de clúster para la instantánea GC selectiva. El módulo acepta un fotograma GC solo si el campo de grupo del fotograma coincide con este group_id O es igual a 0x00 (llamada general).
Casos de uso:
-
Multiinquilino: un ESP32 controla varios grupos independientes de módulos (p. ej., 3 viviendas en un mismo cuadro). Grupo 1 =
group_id: 1, grupo 2 =group_id: 2. El maestro emite un fotograma GC con group=1 → solo el grupo 1 toma la instantánea. -
Un solo inquilino: deje
group_id: 0(llamada general a todos) o definagroup_id: 1como etiqueta: el comportamiento es idéntico, todos los módulos toman un snapshot.
Persistencia: se escribe en REG_GROUP_ID y se guarda en flash mediante leer-comparar-escribir. Cambiarlo requiere un arranque.
rbamp:
- id: apt1_mains
group_id: 1
- id: apt2_mains
group_id: 2
broadcast_latch (obsoleto, legado v0.4.0)
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predeterminado | false |
| Obligatorio | No |
| Estado | Obsoleto: sustituido por fleet_gc_enable: (v1.3+). |
Un alias heredado del instantáneo de difusión por llamada general. En v1.3 la clave la acepta el esquema como no-op (para migrar sin romper desde YAML v0.4.0), pero no tiene efecto. Para código nuevo, use fleet_gc_enable:: está condicionada por capacidad y funciona en firmware v1.3.
Se eliminará en una futura versión menor; aparece una advertencia de obsolescencia en el log:
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.
Referencia cruzada: la referencia de confirmación de grupo de flota.
topology
| Atributo | Valor |
|---|---|
| Tipo | enum (SINGLE, SPLIT_PHASE, THREE_PHASE) |
| Predeterminado | SINGLE |
| Obligatorio | No |
Indicación opcional, mantenida por compatibilidad con versiones anteriores. No es necesaria en los módulos STANDARD: el componente lee del propio módulo el número de canales, la variante y las capacidades, y dimensiona el conjunto de entidades a partir de ello. En los módulos BASIC, el número de canales se deduce de las ranuras current[_1/_2] que declare, y topology: solo cambia la línea que imprime dump_config.
rbamp:
topology: SINGLE # cosmetic; may be omitted
2. Plataforma de sensor: sensor.platform: rbamp
Cada bloque sensor: declara un conjunto de sensores con nombre vinculados al componente padre rbamp:. La única clave obligatoria del bloque es rbamp_id.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
Todos los campos del bloque sensor: son opcionales, con una regla: power, energy, power_factor, reactive_power y apparent_power necesitan voltage Y current declarados en el mismo bloque (los sensores de canal numerados power_N, energy_N, power_factor_N, reactive_power_N necesitan current_N y voltage); si no, esphome config falla con «power requires current to also be declared». Añada internal: true a un sensor obligatorio que no quiera como entidad de Home Assistant. Declare solo las magnitudes que necesite su escenario: el componente lee solo los registros que corresponden a los sensores declarados.
rbamp_id
| Atributo | Valor |
|---|---|
| Tipo | use_id(RbAmpComponent) |
| Obligatorio | Sí |
Hace referencia al bloque rbamp: al que está vinculado este grupo de sensores.
2.1 Campos individuales
Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F) (api-reference)
Se usa para módulos de tensión única (UI1, UI2, UI3, I1, I2, I3 y variantes de más canales). Todos los campos son opcionales. Mezclarlos con campos por fase (voltage_a, voltage_angle_b, etc.) provoca un error de validación.
Hay ranuras para hasta siete canales de corriente: current y current_1 ... current_6, y del mismo modo power, energy y power_factor con los mismos sufijos (power_3, energy_5, ...). energy_exported existe para los canales 0..2 (energy_exported, energy_exported_1, energy_exported_2). Una ranura más allá del número de canales que informa el módulo nunca publica. reactive_power existe solo para los canales 0..2 (reactive_power, reactive_power_1, reactive_power_2); reactive_power_3 ... reactive_power_6 los acepta el esquema pero nunca publican.
Cada campo acepta las subclaves estándar de ESPHome sensor.sensor_schema: name, id, filters, unit_of_measurement, accuracy_decimals, icon, etc.
voltage
Referencia de registros en tiempo real (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
| Atributo | Valor |
|---|---|
| Unidad | V |
device_class |
voltage |
state_class |
measurement |
accuracy_decimals |
1 |
| Fuente | Tensión RMS de red (registro instantáneo del módulo) |
Tensión RMS de red. Se lee en cada update() una vez que el módulo está listo. El float de 4 bytes se lee con reintento por byte (3 intentos × 5 ms) y pasa una comprobación std::isfinite() más |val| < 10000.
El cero es un valor válido para publicar: un evento de corte o caída de tensión produce U ≈ 0 V y pasa a HA sin filtrar; el filtro de cordura solo descarta NaN/Inf, no los ceros legítimos.
voltage:
name: "Mains Voltage"
filters:
- sliding_window_moving_average:
window_size: 3
send_every: 1
current / current_1 ... current_6
| Atributo | Valor |
|---|---|
| Unidad | A |
device_class |
current |
state_class |
measurement |
accuracy_decimals |
3 |
Corriente RMS de los canales 0, 1, 2, ... El canal 0 es la pinza de CT principal; los canales 1 y 2 están presentes en las variantes UI2 / UI3 e I2 / I3, los canales 3..6 en variantes de más canales.
En un módulo BASIC, el número de canales activos se deduce del número de ranuras declaradas: si solo se declara current, el componente usa 1 canal; con current y current_1, 2; añadir current_2 da 3. En un módulo STANDARD, el número de canales viene del propio módulo; las ranuras declaradas por encima de ese número simplemente no publican nunca.
current:
name: "Phase Current"
current_1:
name: "Load 1 Current"
current_2:
name: "Load 2 Current"
power / power_1 ... power_6
Referencia de registros en tiempo real (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
| Atributo | Valor |
|---|---|
| Unidad | W |
device_class |
power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dependencias | power requiere current + voltage; power_N requiere current_N + voltage |
Potencia activa en vatios, con signo. Valores negativos = flujo inverso (inyección a la red) en módulos STANDARD. En BASIC, los valores instantáneos negativos dentro de la ventana del período se fijan a 0 a nivel de firmware: la media del período es ≥ 0. La potencia activa instantánea puede seguir leyéndose negativa en el momento de la generación.
Declarar power sin current + voltage provoca un error de validación: power requires current to also be declared.
power:
name: "Active Power"
energy / energy_1 ... energy_6
Algoritmo en el lado del maestro (period-metering) · 7 · Semántica (api-reference)
| Atributo | Valor |
|---|---|
| Unidad | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dependencias | energy requiere current + voltage; energy_N requiere current_N + voltage |
Energía consumida (importación) acumulada en Wh para el canal.
- Módulos STANDARD — el componente acumula los contadores de energía propios del módulo. Los totales sobreviven a reinicios tanto del ESP32 como del módulo y son monótonos (no retroceden cuando el módulo se reinicia o un contador se pone a cero).
- Módulos BASIC — calculado en el ESP32 a partir de la potencia media del periodo que devuelve el módulo tras cada snapshot:
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600
En ambos casos el valor se guarda en la flash del ESP32 (NVS) cada 5 minutos y al apagarse limpiamente (reinicio / OTA), y se restaura antes del primer publish_state al arrancar: así el panel de energía de HA no interpreta un 0 instantáneo como reinicio de contador. En BASIC, un corte de alimentación repentino pierde como máximo los últimos 5 minutos de energía (≈ 5 Wh con una media de 60 W). Cuando cambia el diseño de NVS (un cambio de versión), el contador empieza en 0.
state_class: total_increasing es obligatorio para el panel de energía de HA. El valor sube de forma monótona; no disminuye en funcionamiento normal.
energy:
name: "Mains Energy"
energy_exported / energy_exported_1 / energy_exported_2
| Atributo | Valor |
|---|---|
| Unidad | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dependencias | Requiere current + voltage + bidirectional: true |
Energía exportada (generación) en Wh para los canales 0..2, acumulada por separado de energy. Defina bidirectional: true en el bloque rbamp: al declarar estos sensores. En módulos STANDARD los valores proceden de los contadores del módulo (persistentes, monótonos). En módulos BASIC los sensores se aceptan, pero publican 0.
power_factor / power_factor_1 ... power_factor_6
| Atributo | Valor |
|---|---|
| Unidad | (dimensionless) |
device_class |
power_factor |
state_class |
measurement |
accuracy_decimals |
3 |
| Dependencias | Requiere current + voltage para la ranura correspondiente |
Factor de potencia en el rango −1..+1. Un FP negativo indica una carga adelantada o retrasada; la convención de signo la define el firmware. El filtro de cordura (§B.5) descarta los valores fuera de |pf| > 10000; no hay límite inferior.
power_factor:
name: "Power Factor"
reactive_power / reactive_power_1 / reactive_power_2
4.12 V03 Q + periodo ch0 (0xD0..0xE3, compilación de producción) (referencia de la API)
| Atributo | Valor |
|---|---|
| Unidad | VAr |
device_class |
reactive_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dependencias | Requiere current + voltage para la ranura correspondiente |
Potencia reactiva en var. Sin signo (≥ 0), calculada como √(S² − P²), incluye distorsión; sin precisión declarada. No distingue cargas inductivas de capacitivas. Se lee del módulo en cada ciclo update(); se publica solo para los canales 0..2 (reactive_power_3 ... reactive_power_6 los acepta el esquema pero nunca publican). No se declara precisión para la potencia reactiva.
reactive_power:
name: "Reactive Power"
Nota sobre device_class: reactive_power — ESPHome lo acepta (la constante DEVICE_CLASS_REACTIVE_POWER) y el valor pasa a Home Assistant. Sin embargo, la lista oficial de device_class de Home Assistant ha cambiado con el tiempo: en algunas versiones reactive_power está disponible en la interfaz y funciona con la unidad VAr, mientras que en otras se muestra como un sensor genérico sin icono ni conversión de unidad específicos. Los datos se publican siempre (son un state); lo único que cambia es cómo HA presenta el sensor en Lovelace. Si el sensor aparece como desconocido en su versión de HA, es un tema cosmético, no una regresión funcional. Elimine la clave reactive_power: del YAML si no usa el sensor.
apparent_power
| Atributo | Valor |
|---|---|
| Unidad | VA |
device_class |
apparent_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Fuente | Calculado en el maestro: S = V_rms × I_rms[0] |
| Dependencias | Requiere current + voltage |
Potencia aparente en VA. La calcula el componente a partir de los valores U_rms e I0_rms leídos en el mismo ciclo update(): no se lee ningún registro aparte. Ambas lecturas deben tener éxito en el mismo ciclo; si falla incluso una (se agotan los reintentos), no se publica ningún estado en ese ciclo y se conserva el último valor en HA.
apparent_power está en SHARED_FIELDS y funciona con cualquier topología, pero depende de voltage y current para el cálculo V × I.
apparent_power:
name: "Apparent Power"
2.2 Campos con fases (variantes de varias tensiones)
Para los módulos con más de una entrada de tensión (variantes bifásicas y trifásicas) los sensores se declaran por fase. El esquema acepta el grupo con fases en cualquier módulo; una ranura solo publica cuando el módulo conectado informa realmente del canal correspondiente; en caso contrario queda sin valor.
Los campos individuales y con fases son mutuamente excluyentes dentro de un mismo bloque sensor:. El validador genera un error:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).
Todos los campos con fases comparten los valores por defecto de sensor_schema de sus equivalentes monofásicos (las mismas unidades, device_class, state_class, accuracy_decimals).
| Campo | Unidad | device_class |
|---|---|---|
voltage_a / _b / _c |
V | tensión |
current_a / _b / _c |
A | corriente |
power_a / _b / _c |
W | potencia |
power_total |
W | potencia |
energy_a / _b / _c |
Wh | energía |
energy_exported_a / _b / _c |
Wh | energía |
power_factor_a / _b / _c |
— | power_factor |
reactive_power_a / _b / _c |
VAr | reactive_power |
voltage_angle_b / _c |
° | — |
voltage_angle_b y voltage_angle_c publican el ángulo de fase de las tensiones B y C en grados, respecto a la fase A (la fase A es la referencia de 0°, por eso no existe voltage_angle_a). Necesitan firmware del módulo que proporcione los ángulos; en firmware anterior el componente registra un aviso al arrancar y los sensores nunca publican. Mientras no se pueda determinar el ángulo, el valor es «unknown».
La validación de dependencias por fase no se aplica a los campos por fase (solo _SINGLE_SLOT_DEPS para monofásico).
Example:
rbamp:
id: panel_meter
address: 0x50
sensor:
- platform: rbamp
rbamp_id: panel_meter
voltage_a:
name: "Phase A Voltage"
voltage_b:
name: "Phase B Voltage"
voltage_c:
name: "Phase C Voltage"
current_a:
name: "Phase A Current"
current_b:
name: "Phase B Current"
current_c:
name: "Phase C Current"
power_total:
name: "Total Active Power"
voltage_angle_b:
name: "Phase B Angle"
voltage_angle_c:
name: "Phase C Angle"
2.3 Campos compartidos (independientes de la topología)
Estos campos funcionan en cualquier grupo de topología, incluido el caso en que no se declara ningún sensor de corriente monofásico o con fases (un despliegue solo de tensión o solo de frecuencia).
frequency
| Atributo | Valor |
|---|---|
| Unidad | Hz |
device_class |
frequency |
state_class |
measurement |
accuracy_decimals |
0 |
Frecuencia de la red. Los valores no plausibles (el módulo informa de «aún no medido») se descartan sin publicar, lo que evita una transición «Unknown» → 0 Hz → 50 Hz en la entidad de HA durante el calentamiento.
frequency:
name: "Mains Frequency"
apparent_power
Vea la entrada bajo los campos individuales anteriores. apparent_power requiere current y voltage, por lo que debe ir en un bloque de sensor monofásico.
energy_total / energy_exported_total / energy_net
| Sensor | Unidad | state_class |
Significado |
|---|---|---|---|
energy_total |
Wh | total_increasing |
Energía importada, todos los canales del módulo |
energy_exported_total |
Wh | total_increasing |
Energía exportada, todos los canales del módulo |
energy_net |
Wh | total |
Importación menos exportación. Puede disminuir. |
Totales generales de todos los canales del módulo, tomados de los contadores de energía propios del módulo (módulos STANDARD). Sobreviven a reinicios del ESP32 y del módulo, son monótonos tras reinicios del módulo y reinicios de contador (salvo energy_net, que es la diferencia de dos valores monótonos), y además se guardan en NVS cada 5 minutos y al apagarse limpiamente. No necesitan la clave bidirectional: ni la declaración complementaria de current/voltage.
En un módulo sin contadores de energía en el dispositivo (BASIC), estas claves validan pero nunca publican; el componente registra un aviso al arrancar. Use ahí los sensores energy por canal.
sensor:
- platform: rbamp
rbamp_id: meter1
energy_total:
name: "Energy Imported"
energy_exported_total:
name: "Energy Exported"
energy_net:
name: "Energy Net"
reactive_energy / reactive_energy_exported
| Atributo | Valor |
|---|---|
| Unidad | varh |
state_class |
total_increasing |
accuracy_decimals |
3 |
Energía reactiva (importación / exportación) de todos los canales, desde los mismos contadores del dispositivo y con la misma persistencia que energy_total. Solo módulos STANDARD; en los demás las claves validan pero nunca publican.
phase_sequence
| Atributo | Valor |
|---|---|
| Unidad | — |
accuracy_decimals |
0 |
Rotación de fases de un módulo de tres tensiones: 1 = directa, 2 = inversa, 3 = anómala. «Desconocido» mientras no se pueda determinar (menos de tres entradas de tensión activas). Requiere un firmware de módulo que lo proporcione; si no, el componente registra una advertencia al arrancar y el sensor nunca publica. En un lambda, id(meter1).get_phase_sequence_str() devuelve "forward", "reverse", "abnormal", "n/a" o "unavailable".
2.4 Reglas de validación del esquema
El validador Python _validate_topology_consistency aplica dos clases de reglas durante esphome config / en la compilación, antes de que se ejecute ningún código C++.
Exclusión mutua de topología
Los campos de una sola fase (voltage, current, current_1, etc.) y los campos con fases (voltage_a, voltage_b, etc.) no pueden coexistir en un mismo bloque sensor:. Si los mezcla:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.
El grupo con fases incluye voltage_angle_b / voltage_angle_c.
Requisitos complementarios por ranura (solo monofásico)
Cada campo derivado requiere los campos de entrada que necesita el módulo para calcularlo:
| Campo declarado | Complementos obligatorios |
|---|---|
power / _1 ... _6 |
current (o _1 ... _6, mismo sufijo) + voltage |
energy / _1 ... _6 |
current (o _1 ... _6, mismo sufijo) + voltage |
power_factor / _1 ... _6 |
current (o _1 ... _6, mismo sufijo) + voltage |
reactive_power / _1 / _2 |
current (o _1 ... _6, mismo sufijo) + voltage |
apparent_power |
current + voltage |
energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* y phase_sequence no tienen requisitos de sensor complementario en el esquema.
Si falta un complemento, aparece:
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.
Otras reglas a nivel del bloque rbamp:
| Regla | Descripción |
|---|---|
ct_model: ↔ ct_models: son mutuamente excluyentes |
Solo puede usarse uno de los dos por bloque rbamp:; si no, error de validación. |
new_address ≠ address |
Si coinciden: cv.Invalid. |
address en el rango 0x08..0x77 |
Se aplica cv.i2c_address. |
update_interval ≥ 1s |
Los intervalos más cortos se rechazan. |
latch_interval ≥ update_interval |
Una cadencia de instantánea más corta se rechaza. |
ct_models: tiene de 1 a 16 entradas |
Las listas más largas se rechazan. |
group_id es de 0..255 |
Los valores fuera de rango se rechazan. |
start_current_ua es 0 o 10..2540 en pasos de 10 |
Cualquier otro valor se rechaza. |
ct_model_force: true requiere ct_model: o ct_models: |
Rechazada por sí sola. |
period_banks: — cada bank una vez, interval ≥ 1s |
Un banco duplicado, un banco fuera de 0..7 o un intervalo más corto se rechazan. |
El código de modelo de CT es válido para el sensor_class fijado |
Un código no permitido para la clase se rechaza y se muestra la lista de valores permitidos. |
Todos los errores de validación se notifican durante esphome compile con un mensaje legible que señala la clave infractora. No hace falta grabar el hardware para encontrar un error de configuración.
3. Flujo de datos y temporización
Sondeo — un solo módulo (sondeo en tiempo real) · 3. DATA_VALID (0xCE) nunca pasa a 1 (resolución de problemas) · 4 · Mapa de registros (producción v1.3) (referencia de la API)
El flujo conceptual de un único ciclo update():
Module (autonomous) ESP32 (ESPHome component)
───────────────────────────────── ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
↓ (~100 ms per cycle)
Atomically publishes the block update() fires every update_interval (60 s)
of instantaneous registers ↓
↓ phase 1 — snapshot:
write the snapshot command
Closes the period accumulator, 50 ms timeout (non-blocking)
opens a new one ↓ (main loop keeps running)
↓
wait 50 ms phase 2 — period snapshot:
read the valid flag
read per-channel average powers
E_Wh[ch] += avg_P × dt_s / 3600
save to NVS if 5 minutes elapsed
↓
phase 3 — instantaneous values:
read the status register
read U_rms, I[0..n]_rms, P[0..n],
PF[0..n], Q[0..n], frequency
publish all bound sensors
↓
Push state to HA over the native API
El diagrama muestra el flujo basado en instantáneas de BASIC. Un módulo STANDARD mantiene sus propios contadores de energía: en cada update() el componente lee los valores instantáneos y la instantánea del contador (una sola transacción coherente) y suma la diferencia a sus totales acumulados, de modo que el paso de instantánea no se usa para la energía.
Tiempos característicos:
| Evento | Cadencia |
|---|---|
| Confirmación interna del bloque instantáneo por el módulo | ~100 ms |
Llamada a update() |
update_interval (60 s por defecto) |
| Tiempo de espera de asentamiento tras el comando de instantánea | 50 ms (no bloqueante) |
| Guardar en NVS | Cada 5 minutos |
| Pausa entre reintentos por byte | 5 ms, hasta 3 intentos |
| Ventana de escritura en flash al grabar el modelo | ~700 ms (el módulo responde NACK todo el tiempo) |
El tiempo de espera de estabilización del snapshot no bloquea: el planificador cooperativo de ESPHome sigue atendiendo WiFi, la API y otros componentes durante la espera de 50 ms. Las fases restantes de update() (lectura de los registros instantáneos) se ejecutan de inmediato tras volver de la fase de snapshot.
El aviso [W][component:522]: rbamp took a long time for an operation (XXX ms) es esperable e inofensivo cuando aparece. En firmware v1.3 el componente lee el bloque de valores instantáneos con una sola lectura en ráfaga (READ con autoincremento), de modo que un ciclo sano queda muy por debajo de 30 ms. El aviso aparece cuando la ruta en ráfaga recurre a lecturas registro a registro (4 transacciones por float, hasta 36 transacciones a 50 kHz, más reintentos), normalmente por un bus marginal o un firmware antiguo sin la capacidad de ráfaga READ.
4. Ajustes del bus I²C
El componente rbamp hereda el bus I²C configurado en el bloque i2c: de nivel superior. Ajustes recomendados en el firmware actual:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
scan: true # optional: logs the addresses found at boot
Velocidad del bus: use 50kHz en maestros basados en ESP-IDF (ESP32 con ESPHome o Arduino). El módulo hace NACK periódicamente a 100 kHz (una proporción notable de transacciones) por una interacción conocida con el driver i2c_master de ESP-IDF (confirmada en esp-idf issue #9426, marcada como «Won't Do» por Espressif). El firmware v1.1/v1.3 endureció el lado del módulo, pero la interacción con el driver persiste: 50 kHz es la recomendación permanente. La mitigación en tres capas del componente (reintento + cordura + 50 kHz) reduce la tasa efectiva de lecturas malas por debajo del 1 %.
Resistencias de pull-up: se recomiendan 4.7 kΩ a 3.3 V en SDA y SCL. Valores mayores (10 kΩ) aumentan el tiempo de subida y elevan la tasa de NACK a 100 kHz.
Varios dispositivos: el bus I²C del ESP32 admite hasta 112 dispositivos en direcciones distintas de 7 bits. Use address: y new_address: para asignar una dirección única a cada módulo. scan: true en el bloque i2c: registra cada dirección que responde al arrancar: compruebe que se detecta cada módulo antes de activar la medición por periodos.
El mapa de registros completo a nivel de cable y el conjunto de comandos del módulo están en la página pública de referencia de la API. Para el usuario típico del esquema YAML este capítulo basta: cada registro queda oculto tras la interfaz declarativa del componente.
5. Superficie de identidad (NUEVO en v1.3) — métodos públicos C++
Detección automática de la variante del módulo (inicialización) · 3. DATA_VALID (0xCE) nunca pasa a 1 (resolución de problemas) · Códigos de error (REG_ERROR = 0x02) (resolución de problemas)
El componente v1.3 expone getters de identidad y diagnóstico accesibles desde un lambda: del YAML y a través de la plataforma template. Todos los métodos devuelven un std::string (por compatibilidad con text_sensor) o tipos primitivos; no se lanza ninguna excepción, todo se obtiene del estado en caché.
| Método | Tipo de retorno | Fuente | Descripción |
|---|---|---|---|
get_variant_str() |
std::string |
REG_HW_VARIANT (0x55) |
«UI1»/«UI2»/«UI3»/«I1»/«I2»/«I3»/«UNK»: la variante del módulo |
get_capability_hex() |
std::string |
registro de capacidades | «0xNNNN»: el mapa de bits de capacidades de 16 bits, para diagnóstico |
get_uid_hex() |
std::string |
REG_UID (0x5C × 12 bytes) |
24 caracteres hexadecimales (UID del chip de 96 bits) |
get_last_error_str() |
std::string |
REG_ERROR (0x02) |
"OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC" |
get_event_flags() |
uint8_t |
REG_EVENT_FLAGS (0x03) |
bits persistentes: bit3=ERR_LATCH, bit5=ADDR_CHANGED, etc. |
get_firmware_version() |
uint8_t |
REG_VERSION (0x01) |
el byte de versión del módulo (p. ej. 0x04 en el firmware BASIC v1.3) |
get_std_image_version() |
uint32_t |
Solo STANDARD | Versión de imagen del módulo en ejecución; 0 = desconocida o BASIC |
get_phase_sequence_str() |
std::string |
Solo STANDARD | "forward"/"reverse"/"abnormal"/"n/a"/"unavailable" |
read_start_current_ua() |
uint16_t |
Solo STANDARD | Lectura reciente de la corriente de arranque almacenada en µA; 65535 = no disponible |
read_gc_tick_received() |
uint16_t |
REG_GC_LAST_TICK (0x58) |
último valor del tick capturado del fotograma GC |
get_capability_cached() |
uint16_t |
mapa de bits de capacidades en caché | el mapa de bits leído al arrancar, sin transacción en el bus |
Caché: variant / capability / uid / firmware_version se leen una vez en setup() y se guardan en caché; las llamadas repetidas no van al bus. last_error_str() / event_flags() / gc_tick se leen en cada llamada para tener datos frescos.
Uso mediante un template text_sensor
text_sensor:
- platform: template
name: "Mains variant"
update_interval: 30s
lambda: 'return id(mains_meter).get_variant_str();'
# → entity_id: sensor.mains_variant, value: "UI1"
- platform: template
name: "Mains capability"
update_interval: 30s
lambda: 'return id(mains_meter).get_capability_hex();'
# → the capability bitmap as hex, "0xNNNN" (diagnostics only)
- platform: template
name: "Mains UID"
update_interval: 30s
lambda: 'return id(mains_meter).get_uid_hex();'
- platform: template
name: "Mains last error"
update_interval: 30s
lambda: 'return id(mains_meter).get_last_error_str();'
- platform: template
name: "Mains firmware version"
update_interval: 30s
lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'
Estos text_sensor aparecen en HA como sensor.mains_variant y similares: útiles para paneles de inventario, escenarios de seguimiento de activos y verificación tras grabar.
Uso mediante lambda: en automatizaciones
sensor:
- platform: rbamp
rbamp_id: mains
energy: { name: "Mains Energy" }
# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
on_boot:
then:
- lambda: |-
ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());
6. Sincronización de flota y GC (v1.3 NUEVO)
transmit_gc_frame(): emisión programática de GC
bool transmit_gc_frame();
Emite un fotograma de instantánea de llamada general de 5 bytes a la dirección de bus 0x00. El byte de grupo es el group_id: de la instancia y el tick es un contador autoincremental; el método devuelve true cuando la escritura en el bus tiene éxito. Solo módulos BASIC: en un módulo STANDARD registra un aviso y no hace nada:
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP
Todos los módulos con fleet_gc_enable: true + un group_id: coincidente (o group_id: 0) toman una instantánea de sus acumuladores de período de forma síncrona en un único instante de cable. Cada módulo guarda el valor del tick para verificar la sincronización (read_gc_tick_received()).
Emisión automática: el componente emite una trama GC automáticamente en update() si fleet_gc_enable: true y el firmware anuncia el snapshot de llamada general. Se necesita una emisión manual solo para una sincronización extra (por ejemplo, con un disparador de evento en HA).
Comprobación de capacidad: si el firmware no anuncia la instantánea de llamada general, se emite una advertencia y no se envía nada.
fleet_apply_now() — fuerza una nueva aplicación de lectura-comparación-escritura
bool fleet_apply_now();
Repite a la fuerza el ciclo leer-comparar-escribir de los ajustes de la flota: vuelve a leer la configuración de flota del módulo y el ID de grupo, los compara con fleet_gc_enable: / group_id: del YAML y escribe la diferencia. Devuelve false (y no hace nada) en un módulo STANDARD.
Caso de uso: tras restablecer un módulo a los valores de fábrica con una herramienta de depuración, o para verificar tras la OTA que la configuración de la flota se aplicó.
7. Servicios nativos de la API (v1.3 NUEVO): automatizaciones de recuperación
Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperación del estado de error: árbol de decisión (api-reference)
El componente v1.3 no registra servicios automáticamente: lo hace el YAML. Pero los métodos públicos write_clear_error() / write_reset() / transmit_gc_frame() están pensados para usarse mediante el patrón api: services:. Recetas canónicas:
api:
port: 6053
services:
# Recovery: clear REG_ERROR + EVENT_FLAGS bit3
- service: mains_clear_error
then:
- lambda: 'id(mains).write_clear_error();'
# Maintenance: soft reset (preserves flash)
- service: mains_reset
then:
- lambda: 'id(mains).write_reset();'
# Fleet: manual GC snapshot (beyond the auto-emit in update())
- service: fleet_latch_now
then:
- lambda: 'id(mains).transmit_gc_frame();' # group = this instance's group_id, tick auto-increments
# Maintenance: force fleet-config re-apply (post-OTA verify)
- service: mains_fleet_apply
then:
- lambda: 'id(mains).fleet_apply_now();'
Después, HA puede llamar a los servicios desde las automatizaciones:
automation:
- alias: "Auto-clear meter error on detection"
trigger:
platform: state
entity_id: sensor.mains_last_error
from: "OK"
action:
- delay: 60s # wait one update_interval to confirm a persistent error
- service: esphome._mains_clear_error
- condition: state
entity_id: sensor.mains_last_error
state: "ERR_PARAM"
- service: persistent_notification.create
data:
title: "Meter parameter error"
message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."
8. Error y recuperación (v1.3) — REG_ERROR frente a bit3 de EVENT_FLAGS
En la v1.3 el módulo tiene dos canales de error independientes:
| Canal | Registro | Semántica del latch | Borrado |
|---|---|---|---|
| Sincronización (última escritura) | REG_ERROR (0x02) |
gana el último escrito, sobrescrito por la siguiente operación | write_clear_error() o la siguiente operación correcta |
| Asíncrono y duradero | bit3 de REG_EVENT_FLAGS (0x03) |
persistente: vuelve a activarse durante unos cientos de milisegundos si no se resuelve la causa raíz | write_clear_error() (una sola operación borra ambos) |
Patrón de lectura
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str(); // "ERR_PARAM" / "OK" / ...
// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;
Semántica de recuperación
Borrar solo REG_ERROR no basta si el firmware vuelve a activar el bit3:
id(mains).write_clear_error(); // clears REG_ERROR + EVENT bit3
delay(300); // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
// Root cause not resolved — firmware re-latched bit3
ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}
Para una recuperación completa:
- Resuelva la causa (corrija el código de modelo de CT del YAML y el sensor_class).
write_clear_error()— borra REG_ERROR + bit3 de EVENT_FLAGS.- Compruebe con
get_event_flags()tras ~300 ms que el bit3 no se vuelve a activar.
Véase 10_troubleshooting.md §6 Error y recuperación.
Fuente e incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/09_api_reference.md (v1.9.1)