rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

02 · Niveles de módulo

Las dos líneas de módulos rbAmp, BASIC y STANDARD (STD), y dónde se calcula la energía en cada una.

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_exported existe en el esquema YAML (por compatibilidad de configuración), pero en BASIC siempre publica 0.
  • 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én voltage_angle_b, voltage_angle_c y phase_sequence.
  • Energía energy y energy_exported por canal (con bidirectional: 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.

Contabilidad de energía en BASIC (el maestro integra la potencia media del periodo) frente a STANDARD (el maestro lee los contadores acumulados del módulo).

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
Nota

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

YAML
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

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

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

O un perfil por canal (para UI3 con pinzas mixtas):

YAML
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 con ct_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): use ct_model:.

Para más sobre la selección de modelo, vea 03_sensor_selection.md.

new_address:: aprovisionamiento de dirección I²C único

YAML
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

YAML
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

YAML
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

YAML
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


Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/02_tiers.md (v1.9.1)