rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub (Edit on GitHub)

09 · Referencia del esquema YAML

Mapa de registros de rbAmp: espacio de direcciones de la página 0 (0x00..0xFF)

Snapshot atómico del periodo — una sola escritura cierra el periodo y abre el siguiente

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:

  1. Bloque de componente: rbamp:
  2. Plataforma de sensor: sensor.platform: rbamp
  3. Flujo de datos y temporización
  4. Ajustes del bus I²C

1. Bloque del componente — rbamp:

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.

YAML
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.

YAML
rbamp:
  id: kitchen_meter

address

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).

YAML
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

Atributo Valor
Tipo time (cadena de duración de ESPHome)
Predeterminado 60s
Obligatorio No

Con qué frecuencia se ejecuta update(). En cada llamada:

  1. 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).
  2. 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.

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

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).

YAML
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

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.

Nota

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.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

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.

YAML
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

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
Nota

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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
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.

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

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():

  1. Sondee la address actual. Si el módulo no responde ahí pero sí responde en new_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.
  2. 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.
  3. 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.
  4. Ruta heredada (v1.0-v1.2): escritura monofásica; requiere el modo de aprovisionamiento de fábrica en el lado del módulo.
  5. El componente cambia su dirección I²C interna mediante i2c::I2CDevice::set_i2c_address() a new_address y verifica que el módulo responde.
  6. 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.

Seguridad

⚠ 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.

YAML
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)

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:

Text
[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.

YAML
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)

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 defina group_id: 1 como 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.

YAML
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:

Text
[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.

YAML
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.

YAML
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

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

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.

YAML
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.

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

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.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

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:
Text
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.

YAML
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.

YAML
power_factor:
  name: "Power Factor"

reactive_power / reactive_power_1 / reactive_power_2

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.

YAML
reactive_power:
  name: "Reactive Power"
Nota

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.

YAML
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:

Text
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».

Nota

La validación de dependencias por fase no se aplica a los campos por fase (solo _SINGLE_SLOT_DEPS para monofásico).

Example:

YAML
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.

YAML
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.

YAML
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:

Text
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:

Text
`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

El flujo conceptual de un único ciclo update():

Text
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
Nota

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:

YAML
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.

Nota

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++

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

YAML
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

YAML
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

C++
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:

Text
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

C++
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

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:

YAML
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:

YAML
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

C++
// 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:

C++
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:

  1. Resuelva la causa (corrija el código de modelo de CT del YAML y el sensor_class).
  2. write_clear_error() — borra REG_ERROR + bit3 de EVENT_FLAGS.
  3. 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)