rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

05 · Inicio rápido: de cero a Home Assistant

Unos 5 minutos de trabajo práctico, más el tiempo de compilación y grabación (la primera compilación también descarga la cadena de herramientas del ESP32, hasta ~15 minutos con una conexión lenta), le llevan desde un ESP32 sin preparar y un módulo rbAmp hasta sensores activos en Home Assistant.

Lo que necesitará

Hardware

  • Placa ESP32: funciona cualquier placa con dos pines I²C libres. Los ejemplos usan GPIO21 (SDA) y GPIO22 (SCL), los valores estándar del DevKitC. Si su placa es diferente, ajuste los números de pin en el YAML.
  • Módulo rbAmp: cualquier SKU UI o I. Para una primera ejecución, UI1 es lo más sencillo: una entrada de tensión y una de corriente, el menor número de cables.
  • Alimentación de 5 V para rbAmp: el módulo funciona con 4.5..5.5 V. La alimentación USB del ESP32 funciona si la placa expone el raíl de 5 V.
  • Pinza de CT: pinza de corriente SCT-013 de núcleo partido conectada al conector de CT del módulo. Lea su rango en la etiqueta (p. ej. SCT-013-030 = 30 A); lo necesitará para ct_model: más abajo.
  • Cableado (lado de baja tensión): VCC → +5 V, GND → GND, SDA → GPIO21, SCL → GPIO22. No se necesitan resistencias de pull-up externas para un solo módulo (las de 4.7 kΩ integradas ya están en la placa). Para el esquema completo, véase 04_hardware.md.
  • Cableado (lado de red): la L y la N de la red van a los terminales L/N del módulo (para la lectura de tensión), y la pinza de CT rodea solo el conductor L, con la flecha apuntando hacia la carga. Vea 04_hardware.md y 03_sensor_selection.md.
DANGER

los terminales L/N llevan tensión de red. Desenergice y bloquee el circuito antes de conectar; que una persona cualificada haga el cableado de red y cualquier trabajo dentro de un cuadro; pince UN solo conductor (L) y nunca deje la pinza de CT en un conductor con la clavija de CT desenchufada.

  • Cable USB del ESP32 al ordenador para grabar.

Software

Requisito Nota
ESPHome ≥ 2025.3.0 El componente usa la sintaxis moderna ota: (lista de plataformas) y el hash de object-id de ESPHome 2025.x. Verificado hasta ESPHome 2026.5 y versiones posteriores.
Python 3.11..3.13 para la CLI La capa interna de PlatformIO de ESPHome (penv) no acepta Python 3.14. Si usa el complemento de HA, este punto no le afecta.
Home Assistant Cualquier versión reciente. El descubrimiento automático funciona mediante mDNS (Avahi / Bonjour).

Dos rutas de compilación:

  1. Complemento ESPHome de HA (recomendado para la mayoría de usuarios): deje el YAML en el directorio de configuración del complemento y pulse Compilar. No hace falta un entorno Python local.
  2. Entorno virtual de CLI local: para desarrollo e CI. Instálelo con pip install esphome en un venv de Python 3.11–3.13.

Configuración de un venv (solo ruta CLI)

Shell
# Windows PowerShell — adjust the Python path to your 3.11 / 3.13
& "C:\Python311\python.exe" -m venv .venv-esphome
.\.venv-esphome\Scripts\Activate.ps1
pip install esphome
esphome version          # should print 2025.3.0 or newer

En Linux / macOS:

Shell
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version

Paso 1 — Localizar el componente

Hay dos formas para el bloque external_components: elija una según su entorno.

Forma A — github (predeterminada, funciona en el complemento de HA)

YAML
external_components:
  - source: github://rb-amp/rbamp-esphome@v1.9.0   # pin a release tag
    components: [rbamp]
    refresh: 1d   # 1 day for production. If you track @main during
                  # development, change this to `0s`, otherwise ESPHome will
                  # cache the copy and ignore new commits.

Esta forma es la única que funciona en el complemento ESPHome de HA (el complemento no tiene acceso de shell a directorios hermanos). También resulta práctica para la CLI: no hace falta clonar nada en local.

Forma B — ruta local (para desarrollo)

Si clonó rb-amp/rbamp-esphome y trabaja directamente con las fuentes del componente, apunte ESPHome a una ruta local:

YAML
external_components:
  - source:
      type: local
      path: /absolute/path/to/rbamp-esphome/components
    components: [rbamp]

En example/ui1.yaml el bloque ya está configurado con una ruta relativa (../components), que funciona cuando ejecuta esphome compile desde el directorio example/:

Shell
cd rbamp-esphome/example
esphome compile ui1.yaml
Seguridad

⚠ Una ruta local no funciona en el complemento de HA: el complemento guarda el YAML en /config/esphome/ sin acceso de shell al resto del sistema de archivos. Los usuarios del complemento eligen la forma A.

Paso 2: cree el YAML

Copie example/ui1.yaml como punto de partida (usa la forma B de ruta local; el listado de abajo usa la forma A, que también funciona en el complemento). Ábralo en cualquier editor e introduzca sus credenciales WiFi y el nombre del dispositivo. El archivo completo se muestra abajo con comentarios línea a línea.

Regla: power, energy, power_factor, reactive_power y apparent_power necesitan voltage Y current declarados en el mismo bloque sensor: (añada internal: true a un sensor que no quiera como entidad de Home Assistant); si no, esphome config se detiene con «power requires current to also be declared». Lo mismo se aplica a los sensores de canal numerados (power_1 necesita current_1 y voltage).

YAML
esphome:
  name: rbamp-ui1          # node name — sets the mDNS hostname (rbamp-ui1.local)

esp32:
  board: esp32dev           # your board (e.g. nodemcu-32s, lolin_d32)
  framework:
    type: arduino           # arduino or esp-idf — both work with the component

logger:
  level: DEBUG              # DEBUG shows I²C reads; after the first run you can use INFO

wifi:
  ssid: !secret wifi_ssid   # see secrets.yaml below
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"    # fallback AP if the connection fails
    password: !secret ap_password

captive_portal:             # config page on the fallback AP

api:                        # Home Assistant native API on port 6053
  # encryption:
  #   key: "BASE64_KEY"     # optional — see 08_has_integrations.md

ota:
  - platform: esphome       # over-the-air updates

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz          # IMPORTANT: 100 kHz causes intermittent NACKs from the module;
                            # 50 kHz reduces them ~5-10x (see 10 · troubleshooting → NACK-discipline)
  scan: true                # logs every I²C address found at boot

external_components:
  - source: github://rb-amp/rbamp-esphome@v1.9.0   # works in the HA Add-on and the CLI
    components: [rbamp]
    # Working from a local clone instead? Use Form B above.

rbamp:
  id: meter1
  address: 0x50             # factory default address
  update_interval: 60s      # how often to close the period and publish sensors
                            # minimum 1 s (v1.3); below this → cv.Invalid
  ct_model: SCT_013_030     # CT clamp model — change it to match yours
                            # (SCT_013_005 / _010 / _020 / _030 / _050 / _060 / _100)

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"  # entity ID in HA: sensor.rbamp_ui1_mains_voltage
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"   # state_class: total_increasing — ready for the Energy dashboard
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"
Nota

La clave ct_model: carga los coeficientes de fábrica del modelo de pinza elegido. Si no tiene una SCT-013-030, cámbielo al modelo que sí tenga. Para más información sobre la elección, véase 03_sensor_selection.md.

secrets.yaml

Cree secrets.yaml en el mismo directorio que el YAML (está excluido en .gitignore de forma predeterminada en example/.gitignore, para que las credenciales no se filtren a un commit):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Paso 3: compilación

Shell
# from the example/ directory with the venv active
esphome compile ui1.yaml

Qué ocurre:

  1. ESPHome descomprime external_components y carga el paquete Python rbamp desde ../components.
  2. PlatformIO descarga la plataforma ESP32 en la primera ejecución (~1–2 GB, en caché). Es el paso más lento: hasta 15 minutos con una conexión lenta.
  3. El componente C++ compila y enlaza. Una finalización correcta tiene este aspecto:
Text
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin

Si la compilación falla con Error: Failed to install Python dependencies, lo más probable es que el host ejecute Python 3.14. Use el complemento de HA o un venv con 3.11 / 3.13 (vea «Lo que necesitará»). Es una incompatibilidad entre el resolvedor uv de PlatformIO y ciertos modelos de CPU, no un error del componente.

Paso 4: primera carga

esphome upload graba el binario por USB. Primero localice el puerto correcto:

  • Windows: Administrador de dispositivos → Puertos (COM y LPT). Normalmente COM3–COM9.
  • Linux / macOS: ls /dev/tty* — normalmente /dev/ttyUSB0 o /dev/ttyACM0.
Shell
esphome upload --device COM6 ui1.yaml             # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml     # Linux

Para la ruta del complemento de HA:

  1. Abra Home Assistant → Ajustes (Settings) → Complementos (Add-ons) → ESPHome.
  2. Abra la interfaz web del complemento ESPHome.
  3. Busque su dispositivo (o pulse «New Device») → Instalar → Conectar a este ordenador [Install → Plug in to this computer].

La herramienta de grabación (esptool.py interno) reinicia el ESP32 automáticamente tras la escritura. El tiempo total de grabación suele ser de 30–60 segundos.

Paso 5 — Qué esperar en el log de arranque

Ejecute esphome logs para seguir el arranque en tiempo real:

Shell
esphome logs ui1.yaml --device COM6

Un primer arranque sano produce aproximadamente estas líneas (los valores y los tiempos son aproximados):

Text
[D][i2c]: Found i2c device at address 0x50
[C][rbamp]: Setting up rbAmp at 0x50 ...
[C][rbamp]:   Firmware version: 0x04
[C][rbamp]:   Variant:         UI1
[C][rbamp]:   UID:             0x1A2B3C4D5E6F708192A3
[C][rbamp]:   sensor_class:    matches → skipped (nothing to write)
[C][rbamp]:   ct_model[0]:     matches → skipped (nothing to write)
[C][rbamp]: rbAmp:
[C][rbamp]:   Address: 0x50
[C][rbamp]:   Firmware version: 1.3
[C][rbamp]:   Topology: SINGLE, channels: 1, voltage: yes
[C][rbamp]:   Bidirectional: NO
[C][rbamp]:   Wh persistence: NVS every 300s
[C][component]: Setup rbamp took 67ms

La línea i2c: scan: true aparece antes de las líneas del componente y confirma que el módulo es visible físicamente en el bus. Si falta Found i2c device at address 0x50, vea la sección «Qué hacer si» más abajo.

Dentro de un update_interval (60 s por defecto) aparecen las publicaciones de sensores: espere unos 60 s, o ponga update_interval: 5s durante las pruebas:

Text
[D][sensor]: 'Mains Voltage': Sending state 226.70 V
[D][sensor]: 'Mains Current': Sending state 0.755 A
[D][sensor]: 'Mains Power': Sending state 92.80 W
[D][sensor]: 'Mains Power Factor': Sending state 0.542
[D][sensor]: 'Mains Frequency': Sending state 50.0 Hz
[D][sensor]: 'Mains Energy': Sending state 0.026 Wh

Valores de referencia en el banco de pruebas con un SKU UI1 y una carga inductiva: U ≈ 225 V, I ≈ 0.78 A, P ≈ 110 W, FP ≈ 0.62. Los valores exactos dependen de la carga conectada.

Paso 6: descubrimiento en Home Assistant

mDNS (automático)

HA encuentra por sí mismo los nodos ESPHome con un bloque api: configurado dentro del mismo segmento de red local. En los 30–60 segundos posteriores al primer arranque del ESP32:

  1. HA muestra una notificación: Nuevos dispositivos descubiertos.
  2. Ajustes → Dispositivos y servicios → ESPHome [Settings → Devices & Services → ESPHome] (o pulse la notificación).
  3. Seleccione el nodo nuevo (p. ej. rbamp-ui1).
  4. Introduzca la IP local del dispositivo (visible en los registros como [I][wifi]: IP: 192.168.0.xxx) si HA no la encontró por sí mismo.
  5. Add.

Todos los sensores se registran de inmediato. El entity ID sigue el patrón sensor._ (los espacios se sustituyen por guiones bajos y todo en minúsculas). Para el YAML anterior: sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy, etc.

Adición manual (si mDNS está bloqueado)

Ajustes → Dispositivos y servicios → Añadir integración → ESPHome → dirección IP y puerto de la API (6053). Si hay una clave definida en api: encryption: key:, introdúzcala cuando se le pida.

Panel de energía

El sensor energy ya está configurado para Energía de HA:

  • device_class: energy
  • state_class: total_increasing
  • unit_of_measurement: Wh

Ajustes → Paneles → Energía → Añadir consumo → seleccione «Mains Energy». HA empieza de inmediato a registrar el consumo acumulado.

Paso 7: ampliación a una flota (despliegue canónico de varios módulos)

Un único UI1 en la red da totales de toda la vivienda. Para obtener un desglose por subramales (caldera, aire acondicionado, VE), añada módulos I2/I3 en el mismo bus I²C. Es el despliegue canónico del 80 % (vea 01_overview.md).

Extensión mínima del YAML

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

# external_components: ... as in Step 1

rbamp:
  - id: mains_meter
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true       # NEW v1.3 — capability-gated GC snapshot
    group_id: 1                  # cluster id

  - id: boiler_meter             # I2 sub-meter, address 0x51 after provisioning
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]   # 20A boiler + 10A washing machine
    fleet_gc_enable: true
    group_id: 1                  # same group → synchronized snapshots

  - id: panel_meter              # I3 sub-meter, address 0x52
    address: 0x52
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]   # mixed CT sizes
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: mains_meter
    voltage: { name: "Mains Voltage" }
    current: { name: "Mains Current" }
    power:   { name: "Mains Power" }
    energy:  { name: "Mains Energy" }
  - platform: rbamp
    rbamp_id: boiler_meter
    current:   { name: "Boiler Current" }       # SCT_013_020 channel 0
    current_1: { name: "Washer Current" }       # SCT_013_010 channel 1
  - platform: rbamp
    rbamp_id: panel_meter
    current:   { name: "Lighting Current" }     # SCT_013_005 channel 0
    current_1: { name: "Appliances Current" }   # SCT_013_030 channel 1
    current_2: { name: "Sub-panel Current" }    # SCT_013_020 channel 2

Qué hacer antes del primer arranque

  1. Aprovisionamiento de direcciones — todos los módulos salen de fábrica en 0x50. Vea 04_hardware.md Commit de dirección en dos fases para el procedimiento secuencial (un solo virgen en el bus a la vez).

  2. Pull-ups: siga la tabla de pull-up de 04_hardware.md, Bus de varios módulos. Para 3 módulos: corte los puentes de pull-up de todos ellos y añada un par externo de 2.7–3.3 kΩ (SDA y SCL a 3.3 V) en el ESP32.

  3. Alimentación externa de 5 V — 3 módulos × ~15 mA = ~45 mA + ESP32 ~200 mA. El VBUS de USB suele bastar para la puesta en marcha; para un despliegue en producción use una SMPS de 5 V independiente.

Qué esperar en el log tras el arranque

Text
[D][i2c]: Found i2c device at address 0x50
[D][i2c]: Found i2c device at address 0x51
[D][i2c]: Found i2c device at address 0x52
[C][rbamp]: rbAmp 0x50: variant=UI1, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x51: variant=I2,  fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x52: variant=I3,  fleet_gc=on, group=1
[I][rbamp]: GC latch enabled fleet-wide: 3 modules in group 1

Comprobación de sincronización

Con UI1@0x50 + I2@0x51 + I3@0x52 y fleet_gc_enable: true:

Text
[D][rbamp]: GC frame emit: group=1, tick=42, all 3 modules ACK'd
[D][rbamp]: check_sync(tick=42) → 3/3 in_sync   ; fleet in sync

Vea la sección de Flota de 09_api_reference.md para la emisión programática y la verificación de sincronización mediante los servicios nativos de la API.

Qué hacer si

Síntoma Causa probable Qué hacer
Falta Found i2c device at address 0x50 Módulo sin alimentación o mal cableado, pines GPIO incorrectos Compruebe VCC (debe ser de 4.5–5.0 V), GND, SDA / SCL; asegúrese de que los puentes de pull-up del módulo están intactos
Probe failed at 0x50 en los logs El módulo es visible en el escaneo pero no responde a las lecturas de registro Compruebe frequency: 50kHz en el YAML; asegúrese de que el módulo no esté en mitad de una escritura en flash (~700 ms)
Los sensores leen 0 o NaN El módulo sigue arrancando; durante los primeros ~250 ms tras encender los registros leen 0 Espere al primer ciclo de update_interval; el componente omite la lectura hasta que el registro de estado esté listo
HA no encuentra el dispositivo mDNS bloqueado por el router / VLAN; falta el bloque api: Añada api:; pruebe la adición manual por IP
Aviso update() took 406ms El componente pasó de la ruta de lectura en ráfaga de v1.3 a lecturas registro a registro (4 transacciones × 9 floats a 50 kHz) No es un problema: compruebe que la versión del firmware es 0x04 y que los pull-ups del bus siguen la tabla de 04_hardware.md (llevados a 3.3 V limpios); un ciclo v1.3 sano se mantiene por debajo de 30 ms
Vuelve al modo punto de acceso SSID o contraseña incorrectos; punto de acceso fuera de alcance Compruebe secrets.yaml; acérquese al punto de acceso; 2.4 GHz frente a 5 GHz

Para problemas que no aparecen en esta lista, véase 10_troubleshooting.md.

Lo que viene después


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