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) yGPIO22(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á paract_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.
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:
- 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.
- Entorno virtual de CLI local: para desarrollo e CI. Instálelo con
pip install esphomeen un venv de Python 3.11–3.13.
Configuración de un venv (solo ruta CLI)
# 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:
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)
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:
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/:
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ 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).
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"
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):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Paso 3: compilación
# from the example/ directory with the venv active
esphome compile ui1.yaml
Qué ocurre:
- ESPHome descomprime
external_componentsy carga el paquete Pythonrbampdesde../components. - 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.
- El componente C++ compila y enlaza. Una finalización correcta tiene este aspecto:
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/ttyUSB0o/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Para la ruta del complemento de HA:
- Abra Home Assistant → Ajustes (Settings) → Complementos (Add-ons) → ESPHome.
- Abra la interfaz web del complemento ESPHome.
- 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
4.7 Espejos de verificación del modelo de CT (0x51..0x53) (api-reference) · 8.10 Relectura del espejo de verificación del modelo de CT (comprobación posterior a la vinculación) (api-reference)
Ejecute esphome logs para seguir el arranque en tiempo real:
esphome logs ui1.yaml --device COM6
Un primer arranque sano produce aproximadamente estas líneas (los valores y los tiempos son aproximados):
[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:
[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:
- HA muestra una notificación: Nuevos dispositivos descubiertos.
- Ajustes → Dispositivos y servicios → ESPHome [Settings → Devices & Services → ESPHome] (o pulse la notificación).
- Seleccione el nodo nuevo (p. ej.
rbamp-ui1). - 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. - 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: energystate_class: total_increasingunit_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
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
-
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).
-
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.
-
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
[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
6.3 Instantánea de difusión GC: sincronización de flota por adhesión voluntaria (api-reference) · 8.4 Instantánea de difusión GC + respaldo testigo (api-reference)
Con UI1@0x50 + I2@0x51 + I3@0x52 y fleet_gc_enable: true:
[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
- Configuración de tres canales: 06_examples.md: YAML de UI3 con tres canales de corriente independientes y todas las magnitudes derivadas.
- Varios módulos en un bus: 06_examples.md — la sección de varios módulos.
- Análisis en profundidad del panel de energía de HA: 08_has_integrations.md.
- Integraciones DIY (Grafana, MQTT, automatizaciones): 07_diy_integrations.md.
- Referencia completa de configuración: 09_api_reference.md.
- Diagnóstico de problemas durante la primera ejecución con rbAmp: 10_troubleshooting.md.
Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/05_quickstart.md (v1.9.1)