02 · Niveles de módulo
rbAmp se distribuye en dos líneas de módulos: BASIC y STANDARD (STD). Cada nivel es una combinación completa de revisión de hardware y compilación de firmware, no solo un indicador en el firmware. Pasar de un nivel a otro requiere sustituir físicamente el módulo, no una actualización de firmware.
El componente ESPHome funciona con las dos líneas de módulos desde un solo YAML: el esquema es común, y el componente identifica automáticamente la línea de módulo conectada (BASIC o STANDARD (STD)) al arrancar. Las diferencias están en qué datos exporta realmente el módulo y qué claves YAML tienen sentido en cada línea.
Niveles
BASIC: nivel de entrada
El firmware mantiene una medición de consumo unidireccional: la potencia activa media en un período nunca puede ser negativa; los segmentos inversos dentro de la ventana se ponen a cero antes de integrar. En la práctica se parece a un contador mecánico de disco clásico.
- La energía se integra en el ESP32 a partir de la potencia media del periodo que devuelve el módulo tras cada snapshot, y se guarda en la flash del ESP32 (NVS).
- El sensor
energy_exportedexiste en el esquema YAML (por compatibilidad de configuración), pero en BASIC siempre publica0. - Los sensores de energía de total general (
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported) validan pero nunca publican en BASIC. - Aplicaciones típicas: apartamentos sin generación propia, submedición de cargas concretas (calentadores de agua, motores, electrodomésticos, HVAC).
STANDARD (STD): bidireccional, energía en el propio dispositivo
STANDARD (STD) es la línea de módulos actual. Mide importación y exportación por separado y mantiene sus propios contadores de energía acumulada dentro del módulo.
- El mismo YAML. El componente reconoce un módulo STANDARD (STD) al arrancar y toma del módulo el número de canales, la variante y las funciones disponibles. No se define ningún nivel y no necesita
topology:. - Energía desde los contadores del módulo. El componente acumula los contadores del módulo en lugar de integrar la potencia por sí mismo, de modo que los totales sobreviven a los reinicios tanto del ESP32 como del módulo, se mantienen monótonos entre reinicios del módulo y reinicios de contadores, y no derivan. Los valores se guardan además en la flash del ESP32 (NVS) cada 5 minutos y en un apagado limpio (reinicio / OTA).
- Sensores nuevos:
energy_total,energy_exported_total,energy_net(importación − exportación, puede disminuir),reactive_energy,reactive_energy_exported— totales generales de todos los canales; en las variantes de tres tensiones tambiénvoltage_angle_b,voltage_angle_cyphase_sequence. - Energía
energyyenergy_exportedpor canal (conbidirectional: true) proceden de los mismos contadores. start_current_ua:fija una corriente de arranque por debajo de la cual un canal no cuenta energía, de modo que el ruido en vacío no se cuele en los contadores.- Casos típicos: viviendas con generación solar o eólica, almacenamiento con baterías, cargadores de VE, cualquier instalación en la que la importación y la exportación deban medirse por separado y en la que los totales de energía deban sobrevivir a los reinicios.
En un módulo STD, la energía procede de los contadores propios del módulo; latch_interval se aplica solo a BASIC.
Las claves que existen solo para la línea de módulos BASIC (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: para la ruta de energía del lado del maestro) se ignoran en un módulo STANDARD, con una línea de registro.
Matriz de capacidades
| Capacidad | BASIC | STANDARD |
|---|---|---|
| Tensión RMS | sí | sí |
| Corriente RMS (1..3 canales, más en variantes de más canales) | sí | sí |
| Potencia activa (float con signo) | sí | sí |
| Factor de potencia | sí | sí |
| Potencia reactiva (leída del módulo, canales 0..2; sin signo, calculada como √(S² − P²), incluye distorsión; sin precisión declarada) | sí | sí |
| Potencia aparente (solo CH0) | sí (U × I[0], calculado en el ESP32) |
sí (desde el módulo) |
| Frecuencia de la red | sí | sí |
Sensor energy (importación en Wh), guardado en NVS |
sí (integrado en el ESP32) | sí (desde los contadores del dispositivo) |
Sensor energy_exported (necesita bidirectional: true) |
siempre 0 | sí |
| La energía sobrevive a los reinicios del ESP32 y del módulo | solo ESP32 | sí |
Totales generales: energy_total, energy_exported_total, energy_net |
no | sí |
Energía reactiva: reactive_energy, reactive_energy_exported |
no | sí |
start_current_ua: |
no | sí |
voltage_angle_b/_c, phase_sequence (variantes de tres tensiones) |
no | sí |
ct_models: por canal |
sí | solo si el módulo almacena modelos por canal; si no, se rechaza con una línea de log |
fleet_gc_enable: / group_id: sincronización por llamada general |
sí (firmware v1.3+) | ignorado |
El componente solo lee lo que declaran los sensores: nunca se solicita un registro no declarado.
Claves YAML por nivel
bidirectional: (predeterminado false)
Activa los sensores de energía exportada por canal (energy_exported, energy_exported_1, energy_exported_2).
rbamp:
id: solar_meter
address: 0x51
bidirectional: true # meaningful on STANDARD; on BASIC the export sensors read 0
En STANDARD la energía exportada se toma de los contadores del módulo. En BASIC la clave la acepta el esquema sin error, pero energy_exported siempre devuelve 0. Los sensores de total general energy_exported_total y energy_net no necesitan esta clave.
sensor_class:: fijar la familia del sensor
rbamp:
id: meter1
sensor_class: SCT_013 # default SCT_013
Admitido en ambas líneas de módulos. 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 rechaza escribir el modelo si la clase no está definida. Un valor que el módulo ya tiene no se vuelve a escribir.
Valores de enumeración: SCT_013 (pinzas SCT-013 de núcleo partido, por defecto), WIRED_CT y BUILTIN_CT (módulos suministrados calibrados junto con su propio sensor integrado). En un módulo emparejado en fábrica de este tipo, un cambio de clase o de modelo desde el YAML se rechaza con una línea de registro, para proteger la calibración individual.
ct_model: / ct_models: — modelo de pinza CT
Un único perfil global para todos los canales:
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
O un perfil por canal (para UI3 con pinzas mixtas):
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
Aceptado en ambas líneas de módulos, mutuamente excluyentes. En firmware v1.2 o posterior el módulo carga automáticamente los coeficientes de fábrica del modelo seleccionado: no hacen falta pasos de calibración adicionales. En firmware anterior el valor se guarda como marcador de modelo.
- Cambiar la potencia nominal de la SCT mantiene la precisión de fábrica: el componente completa el cambio (un reinicio del módulo en el flujo es normal en firmware hasta 1.4.19; el firmware más nuevo lo corrige en el módulo) y escala las lecturas al sensor seleccionado.
- Guardas de escritura: un valor igual no se escribe; en un módulo emparejado de fábrica el cambio se rechaza con una línea de log.
ct_model_force: true(opción de servicio, válida solo junto conct_model:/ct_models:) lo anula de forma deliberada. - Los
ct_models:por canal en un módulo STANDARD necesitan que el módulo almacene modelos por canal; si no, el componente lo rechaza de forma explícita (advertencia, claves ignoradas): usect_model:.
Para más sobre la selección de modelo, vea 03_sensor_selection.md.
new_address:: aprovisionamiento de dirección I²C único
rbamp:
id: meter1
address: 0x50
new_address: 0x51 # one-shot; remove after a successful boot
Admitido en ambas líneas de módulos. En firmware v1.3+ el cambio de dirección es listo para producción: el componente usa un protocolo de confirmación en dos fases (preparar → armar → confirmar → reiniciar) sin modo especial. En firmware heredado (v1.0-v1.2) la ruta de una sola fase requiere el modo de aprovisionamiento de fábrica; consulte la documentación del módulo o a su proveedor para activarlo. El modo de aprovisionamiento de fábrica sigue siendo necesario en todas las versiones de firmware para las operaciones de calibración (saveGains) y restablecimiento de fábrica.
Ejecución a lo largo de un único arranque: el componente consulta la dirección actual, escribe la nueva dirección y la guarda en flash, reinicia el módulo y verifica la respuesta en la nueva dirección. Tras el éxito, actualice el YAML a address: 0x51 y elimine new_address:. Si el componente encuentra que la dirección antigua está muda y la nueva responde, se adapta automáticamente con un aviso en el registro (por si un arranque anterior ya aplicó el cambio).
fleet_gc_enable: / group_id: — snapshot síncrono para un bus de varios módulos
rbamp:
- id: meter1
fleet_gc_enable: true # v1.3 production path — recommended
group_id: 1 # cluster id (modules in the same group snapshot together)
Cuando está activado, el componente envía un fotograma de llamada general de 5 bytes a la dirección de difusión I²C, sincronizando la instantánea del período en todos los módulos del mismo group_id en una sola transacción.
En el firmware BASIC v1.3, el snapshot de llamada general es opcional y depende de la capacidad. El componente comprueba al arrancar si el firmware lo anuncia y activa la ruta automáticamente cuando la clave del YAML y el firmware coinciden. En firmware antiguo (v1.0..v1.2) no se anuncia; el componente recurre a un snapshot secuencial para cada módulo por separado y registra una línea informativa. En un módulo STANDARD estas claves se ignoran con una línea de log.
La clave heredada broadcast_latch: sigue aceptándose en el esquema por compatibilidad con versiones anteriores, pero no tiene efecto. Use fleet_gc_enable: + group_id:.
El desfase entre módulos en un bus de 50 kHz es del orden de ~540 µs × N, menos del 0.003 % de un período de 60 segundos. En los totales diarios de HA esta irregularidad es imperceptible.
topology: — indicación de topología
rbamp:
id: meter1
topology: SINGLE # SINGLE / SPLIT_PHASE / THREE_PHASE
Opcional y no necesario en módulos STANDARD, donde el número de canales y la variante proceden del propio módulo. En los módulos BASIC, el componente deduce el número de canales a partir de las ranuras de sensor declaradas (si se declara current_1, hay al menos 2 canales). La clave es cosmética y aparece en la línea de log dump_config.
drdy_pin: — interrupción opcional de datos listos
rbamp:
id: meter1
drdy_pin: GPIO15
Admitido en ambas líneas de módulos. Se conecta a la salida DRDY opcional de drenador abierto del módulo. El pin se configura y se registra, pero los registros instantáneos se sondean con update_interval de todos modos. Con un update_interval: 60s típico, la clave puede omitirse.
Requiere una resistencia de pull-up de 10 kΩ en el GPIO del maestro a 3.3 V (la salida es de drenador abierto; no hay pull-up interno en el lado del módulo). Véase 04_hardware.md.
Tabla resumen: clave YAML × línea de módulo
| Clave YAML | BASIC | STANDARD | Notas |
|---|---|---|---|
address: |
sí | sí | — |
update_interval: |
sí | sí | Mínimo 1s |
latch_interval: |
sí | n/a | Desacopla la cadencia de instantánea/energía de la cadencia de lectura; STANDARD lee sus contadores en cada update() |
drdy_pin: |
sí | sí | Opcional, necesita un pull-up de 10 kΩ; no se usa como disparador de lectura |
topology: |
sí | no necesario | Indicación informativa |
sensor_class: |
sí | sí | No se reescribe si es igual; se rechaza en módulos emparejados de fábrica |
ct_model: / ct_models: |
sí | sí | Mutuamente excluyentes; la lista por canal en STANDARD necesita un módulo que la almacene |
ct_model_force: |
sí | sí | Opción de servicio; el esquema exige una clave de modelo |
bidirectional: |
aceptado (la exportación lee 0) | funciona | Necesario para los sensores por canal energy_exported* |
start_current_ua: |
se ignora con una advertencia | funciona | 0 o 10..2540 en pasos de 10 |
new_address: |
sí | sí | Listo para producción en firmware BASIC v1.3+; de una sola vez |
fleet_gc_enable: / group_id: / broadcast_latch: |
sí | ignorado | La sincronización por llamada general es una función de la línea BASIC |
Sensor energy_exported |
siempre 0 | funciona | Necesita bidirectional: true |
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] |
nunca publicar | funciona | Totales generales desde los contadores del dispositivo |
voltage_angle_b/_c, phase_sequence |
nunca publicar | funciona en variantes de tres tensiones con un firmware que las proporcione | Véase 09 §2.2–2.3 |
Sensores por fase (voltage_a/b/c, current_a/b/c, …) |
sin valores | publicar para los canales que informa el módulo | Detalles en 09 §2.2 |
Qué sigue
- 03_sensor_selection.md: elegir una pinza de CT y el comportamiento de
ct_model:/ct_models: - 04_hardware.md — cableado físico, selección de GPIO
Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/02_tiers.md (v1.9.1)