04 · Cableado
Este capítulo trata del cableado físico de rbAmp a un ESP32: selección de GPIO, reglas de pull-up, bus de varios módulos, alimentación, línea DRDY opcional y aprovisionamiento de direcciones.
Despliegue canónico: una flota de varios módulos en un solo bus. El 80 % de las instalaciones de campo consisten en 1× UI1 (red) + N× I2/I3 (submedidores) en un mismo bus I²C del ESP32, con los pull-ups configurados según la tabla siguiente. Véase 01_overview.md para la visión de la flota. Un módulo único es el caso mínimo, no el canon. Este capítulo cubre ambas topologías, pero el despliegue de varios módulos está marcado como «topología principal» en las secciones correspondientes.
Módulos STANDARD (STD). El cableado, las reglas de pull-up, la alimentación y la línea DRDY opcional son los mismos para los módulos BASIC y STANDARD, y el mismo YAML sirve para ambos: el componente identifica el módulo conectado al arrancar. new_address: funciona en ambas líneas de módulos. La sincronización de flota por llamada general (fleet_gc_enable: / group_id:) se aplica solo a los módulos BASIC; en un módulo STANDARD esas claves se ignoran con una línea de log.
PELIGRO: los terminales L/N llevan tensión de red. Corte la alimentación y bloquee el circuito antes de conectar; que un electricista cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro; abrace UN solo conductor con la pinza (L) y nunca deje la pinza de CT puesta en un conductor con el conector de CT desenchufado.
Cable y fusible. No hace falta un cable grueso para la conexión de tensión: basta con AWG26–22, porque el sensor de tensión consume muy poca corriente. Un fusible en la línea L es obligatorio, de hasta 0.1 A.
El lado de red de un vistazo. La L y la N de la red van a los dos terminales del módulo (dan la lectura de tensión); la pinza de CT se enchufa en la toma de CT y rodea solo el conductor L, con la flecha hacia la carga. Todo lo demás de este capítulo es el lado de baja tensión.
Pinout del lado de baja tensión
El lado de baja tensión del módulo expone cinco señales. Todas están aisladas galvánicamente de la red: el pin GND es el GND del ESP32, no el neutro de la red.
| Pin | Señal | Descripción |
|---|---|---|
VCC |
+4.5..+5.5 V CC | Alimentación del módulo. 5 V nominales; por debajo de 4.5 V las lecturas pueden volverse poco fiables. |
GND |
Común | Común con el maestro. Obligatorio. |
SDA |
Datos I²C | Lógica de 3.3 V; tolera 5 V. |
SCL |
Reloj I²C | Lógica de 3.3 V; tolera 5 V. |
DRDY |
Datos listos (opcional) | Salida de drenador abierto. Pulso LOW de ~10 µs cada ~100 ms tras actualizar los registros instantáneos. |
Selección de GPIO en el ESP32
Cualquier par de GPIO que soporte I²C funcionará. La matriz de periféricos del ESP32 le permite enrutar I²C a casi cualquier pin. Restricciones prácticas:
- GPIO0 y GPIO2 son pines de arranque. Un nivel bajo en ellos al encender bloquea el arranque. No los use.
- GPIO 6..11 están conectados a la flash integrada o a la PSRAM en la mayoría de los módulos ESP32-WROOM. No disponibles.
- GPIO 34..39 son solo de entrada. No son aptos para I²C (que necesita accionamiento bidireccional).
- No conecte ningún GPIO del ESP32 a una línea de reset del módulo: el módulo se reinicia con un comando I²C y no hacen falta pines de reset hardware en el lado del maestro.
Asignaciones predeterminadas recomendadas que funcionan en la mayoría de placas ESP32-DevKitC:
| Señal | GPIO | Nota |
|---|---|---|
| SDA | GPIO21 | Valor por defecto en todos los YAML de ejemplo |
| SCL | GPIO22 | Valor por defecto en todos los YAML de ejemplo |
| DRDY | GPIO15 | Opcional; vale cualquier pin con capacidad de entrada |
Si GPIO21/22 están ocupados, elija cualquier otro par válido y actualice el bloque i2c: del YAML.
Cableado de un solo módulo
El cableado completo del ESP32 aparece en el esquema de referencia de abajo.
No hacen falta resistencias de pull-up externas para un solo módulo: la placa rbAmp ya tiene pull-ups integrados de 4.7 kΩ en SDA y SCL a 3.3 V.
Bus de varios módulos (topología principal)
La mayoría de los despliegues de rbAmp son una flota de varios módulos en un único bus I²C del ESP32: un UI1 en la red y varios I2/I3 en subramales. Es la topología principal para la que se diseñó el componente, y la configuración de pull-ups de abajo está optimizada para ella.
Cuando dos o más módulos (u otros dispositivos I²C con sus propios pull-ups) comparten un bus, sus pull-ups se suman en paralelo. La resistencia combinada baja por debajo del mínimo efectivo, lo que provoca:
- Consumo excesivo del bus.
- Posible sobrecarga de las salidas de drenador abierto del ESP32 (normalmente ≤ 3 mA a 3.3 V).
- Mayor carga capacitiva en un bus largo.
La cara inferior de cada PCB de rbAmp tiene puentes de soldadura marcados como Pull-Up. Cortar la pista con una cuchilla afilada desconecta el par integrado de 4.7 kΩ de ese módulo.
| Módulos en el bus | Configuración de pull-up | R efectiva |
|---|---|---|
| 1 | Deje el par integrado. No hace falta ninguno externo. | ~4.7 kΩ |
| 2 | Deje solo la primera; corte la segunda. | ~4.7 kΩ |
| 3 | Corte en todos. Un par externo de 2.7..3.3 kΩ en el ESP32. | 2.7..3.3 kΩ |
| 4..6 | Corte en todos. Un par externo de 2.2..2.7 kΩ en el ESP32. | 2.2..2.7 kΩ |
| 7..16 | Corte en todos. Un par externo de 1.5..2.2 kΩ en el ESP32 + una comprobación de la capacidad del bus (vea abajo). | 1.5..2.2 kΩ |
| El ESP32 ya proporciona pull-ups | Corte en todos los módulos. Los pull-ups internos del ESP32 (≥50 kΩ) son débiles: un bus largo sigue necesitando externos de 2.2..4.7 kΩ. | igual que arriba |
Los valores externos son valores recomendados (calculados a partir de la especificación I²C: corriente de sumidero ≤ 3 mA a 3.3 V, capacidad del bus ≤ 400 pF). Conecte las resistencias de pull-up externas a 3.3 V (el nivel lógico del bus), no a la alimentación de 5 V VCC.
Lógica de selección: la R_pullup efectiva es la combinación en paralelo de todos los pull-ups activos. El rango objetivo es 1.5..4.7 kΩ (el mínimo lo limita la corriente de sumidero del ESP32 ≤ 3 mA a 3.3 V; el máximo, la constante de tiempo RC del bus). Fórmula: 1/R_eff = N/R_unit. Para el par integrado de 4.7 kΩ: 2 módulos = 2.35 kΩ, 3 = 1.57 kΩ, 4 = 1.18 kΩ; con 3 módulos el valor en paralelo es 1.57 kΩ, todavía dentro del rango, y un bus de 3 módulos de hasta 15 cm se mide como fiable (cables de 15 cm, 50 kHz), por lo que la tabla mantiene los puentes integrados con 2 y 3 módulos. A partir de 4 módulos, o antes en un bus más largo, los anula y pasa a un único par externo.
Comprobación de diagnóstico: mida la resistencia entre SDA y VCC con la alimentación apagada. El resultado debe estar en el rango 1.5..4.7 kΩ. Por debajo de 1.0 kΩ hay demasiados pull-up activos en paralelo; por encima de 10 kΩ no hay pull-up activo (revise los puentes).
Capacidad del bus (para ≥7 módulos o una longitud total de cableado superior a 50 cm): la especificación I²C limita la capacidad total C_b a ≤ 400 pF. Un bus corto con 2-3 módulos suele estar entre 50 y 100 pF; un bus de 1 m con 10 módulos puede subir a 300..400 pF. Cuando se acerque al límite, baje a frequency: 50kHz (si sigue en 100 kHz) o use un CI de pull-up activo (por ejemplo, el PCA9517).
Velocidad del bus
Defina frequency: 50kHz en el bloque i2c: de ESPHome. En el firmware actual esto es obligatorio para un funcionamiento fiable con ESP-IDF v5:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32 — ESP-IDF i2c_master driver interaction, see below
El módulo NACK periódicamente las lecturas de un ESP32 a 100 kHz (una proporción notable de transacciones) por la interacción entre el driver i2c_master de ESP-IDF v5 y la ventana de recuperación posterior a STOP del periférico I²C del módulo. A 50 kHz los NACK son mucho más raros, y el reintento por byte dentro del componente recupera más del 99 % de las lecturas válidas.
El firmware ha endurecido la ventana de recuperación I²C del módulo (incluida en v1.1 y v1.3), lo que redujo la contribución del lado del módulo; pero 50 kHz sigue siendo el ajuste recomendado en maestros basados en ESP-IDF, porque la interacción de temporización del driver persiste a 100 kHz. Considérelo la recomendación permanente para el ESP32, no un parche temporal a la espera de una corrección.
Otros maestros I²C ejecutan este módulo a 100 kHz sin problemas: STM32 HAL, RP2040 SDK, Raspberry Pi smbus2 (I²C del kernel de Linux) y Arduino no ESP32 (AVR / STM32duino). Tenga en cuenta que el eje es el controlador, no la placa: Arduino en un ESP32 usa el mismo controlador i2c_master de ESP-IDF, así que también necesita 50 kHz; solo Arduino no ESP32 funciona a 100 kHz.
Esquema de referencia — un ESP32 + un rbAmp
Notes:
- La resistencia de 10 kΩ en DRDY está en el lado del maestro (cerca del GPIO), no en el lado del módulo. DRDY es de drenador abierto, sin pull-up interno.
- La clavija de la CT debe estar insertada del todo; la pinza debe rodear por completo un único conductor con la flecha apuntando hacia la carga.
- La polaridad L/N en los terminales afecta al signo de P (véase 03_sensor_selection.md).
Potencia
Alimentación del módulo (VCC)
El módulo requiere de +4.5 a +5.5 V CC. Consumo de corriente:
| Modo | Típico |
|---|---|
| Medición en régimen estacionario | ~15 mA |
Escritura en flash (durante el aprovisionamiento de ct_model: / direcciones) |
~25 mA pico, ~700 ms |
| Calentamiento de arranque (~250 ms) | ~15 mA |
El pin de 5 V de un ESP32-DevKitC (normalmente conectado a VBUS de USB) puede alimentar el módulo directamente: el host USB debe suministrar la corriente combinada del ESP32 (~200 mA) + rbAmp (~15 mA de pico) = ~215 mA. En instalaciones donde el ESP32 se alimenta desde una SMPS externa de 5 V, conecte VCC al mismo raíl de 5 V.
Brownout del ESP32
El detector de brownout del ESP32 se activa a ~2.43 V en VDD. Cuando se activa, el bus I²C queda inactivo mientras el módulo sigue midiendo de forma autónoma (tiene su propia alimentación de 5 V). Cuando el ESP32 se recupera, setup() restaura la energía acumulada desde NVS antes del primer update(). Home Assistant no ve ni un hueco ni un reinicio en la gráfica de energía.
DRDY opcional
El pin DRDY del módulo es de drenador abierto. Emite un pulso a BAJO durante ~10 µs cada ~100 ms, justo después de la actualización del bloque de registros instantáneos. No se activa con la instantánea de período.
Con update_interval: 60s puede omitir DRDY: el componente comprueba el registro de estado al inicio de cada update() y omite la lectura si el módulo no está listo. El componente registra el pin DRDY; las lecturas las dirige un temporizador (update_interval).
Cableado DRDY
DRDY es de drenador abierto: baja a LOW pero no puede llevar a HIGH. Necesita un pull-up externo:
rbAmp DRDY ──────────────────┬── ESP32 GPIO (input)
|
[10K]
|
3.3V
10 kΩ a 3.3 V. No conecte DRDY a 5 V, aunque SDA/SCL toleren 5 V: DRDY es una señal independiente y el máximo absoluto en un GPIO de entrada del ESP32 es 3.6 V.
Declare el pin en el YAML:
rbamp:
id: meter1
drdy_pin: GPIO15
DRDY de varios módulos
Las señales DRDY de varios módulos pueden unirse en OR por cable en un único GPIO del ESP32 (las salidas de drenador abierto se combinan de forma natural). La señal compartida baja a LOW cuando cualquier módulo ha actualizado sus registros instantáneos. El componente solo registra el pin; no indica qué módulo disparó.
Si necesita señales separadas, lleve el DRDY de cada módulo a su propio GPIO y declare drdy_pin: en cada bloque rbamp: por separado.
Aprovisionamiento de direcciones en un bus de varios módulos
Todos los módulos rbAmp salen de fábrica con la dirección 0x50. Antes de conectar varios módulos a un bus, cada uno necesita una dirección única. En firmware v1.3 esto puede hacerse en producción sin modo de aprovisionamiento de fábrica, gracias al protocolo de commit en dos fases.
Confirmación de dirección en dos fases (v1.3+, listo para producción)
Con new_address: el componente ejecuta la siguiente secuencia:
-
Comprueba si el firmware soporta el commit en dos fases. Si es así, toma la ruta del modo de producción. Si no, recurre al respaldo monofásico heredado con control de aprovisionamiento de fábrica (firmware v1.0-v1.2).
-
Escribe la nueva dirección en
REG_I2C_ADDRESS(preparada, aún no activa). -
Escribe la «palabra mágica»
0xA5enREG_ADDR_COMMIT_MAGIC: una confirmación explícita de intención que protege contra una escritura accidental enREG_I2C_ADDRESS. -
Envía el opcode
CMD_COMMIT_ADDR: el módulo aplica de forma atómica la dirección preparada, la guarda en flash y realiza un reinicio suave. -
Tras ~700 ms el componente vuelve a vincular su manejador i2c_address a la nueva dirección y verifica la reenumeración con una lectura de sonda.
Si algún paso falla, el módulo vuelve a la dirección anterior, sin estado «a medias». Un viaje de ida y vuelta 0x50 → 0x60 → 0x50 vuelve a enumerarse en menos de un segundo.
Aprovisionamiento secuencial (flujo recomendado)
Varios módulos juntos en el bus antes del aprovisionamiento son una colisión de direcciones (todos en 0x50). Por eso el aprovisionamiento es secuencial, un módulo cada vez:
- Conecte solo el módulo 1 al ESP32 (solo en el bus).
-
Grabe la configuración de
example/address_change.yamlconaddress: 0x50ynew_address: 0x51. Al arrancar, el componente detecta la discrepancia → ejecuta el commit en dos fases (vea arriba). -
Confirme el éxito en los logs de ESPHome (reenumeración en la nueva dirección). Actualice el YAML:
address: 0x51, eliminenew_address:. -
Desconecte el módulo 1. Conecte el módulo 2 (todavía en la
0x50de fábrica). -
Repita para
0x52,0x53, etc. OBLIGATORIO: solo un módulo virgen en el bus cada vez; de lo contrario, ambos responden en 0x50 y se produce una contienda en el bus. -
Cuando todos los módulos tengan direcciones únicas, conéctelos todos al bus y configure los pull-ups según la tabla de Bus de varios módulos (2 módulos: mantenga un par; 3 o más: corte todos y añada un par externo).
Peligro de aprovisionamiento concurrente: si dos módulos vírgenes están ambos en 0x50, ambos confirman el byte de dirección y pelean por SDA en la fase de datos → contención del bus + datos indeterminados. Siempre un solo virgen a la vez.
YAML de ejemplo para varios módulos
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
- id: meter_solar
address: 0x51
update_interval: 60s
bidirectional: true
- id: meter_evcharger
address: 0x52
update_interval: 60s
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage: { name: "House Voltage" }
current: { name: "House Current" }
power: { name: "House Power" }
energy: { name: "House Energy" }
- platform: rbamp
rbamp_id: meter_solar
voltage: { name: "Solar Voltage", internal: true }
current: { name: "Solar Current" }
power: { name: "Solar Power" }
energy: { name: "Solar Energy" }
energy_exported: { name: "Solar Energy Exported" }
- platform: rbamp
rbamp_id: meter_evcharger
voltage: { name: "EV Charger Voltage", internal: true }
current: { name: "EV Charger Current" }
power: { name: "EV Charger Power" }
energy: { name: "EV Charger Energy" }
La versión completa con anotaciones está en example/multi_module.yaml.
Longitud del bus
I²C es un protocolo de corta distancia (~15 cm por defecto). Muchos usuarios conectan los módulos con cables de puente de baja calidad, que captan mucho ruido y pierden muchas transferencias, de ahí el límite corto. Longitudes recomendadas para rbAmp:
| Tipo de cable | Longitud máxima | Velocidad |
|---|---|---|
| JST estándar / plano de 4 hilos | 0.15 m | 50 kHz |
| Par trenzado (SDA+GND y SCL+GND en pares separados) | 1 m | 50 kHz |
| Par trenzado + buffer I²C (PCA9515 / TCA9617) | 3 m | 50 kHz |
| Bus diferencial (PCA9615 / LTC4332) | 100 m | 50 kHz |
Para más de 0.15 m, use par trenzado, y SDA y SCL deben ir en pares separados (por ejemplo, azul + blanco-azul para SDA, verde + blanco-verde para SCL). Si SDA y SCL comparten un par, el acoplamiento cruzado distorsiona los flancos incluso a 50 kHz.
⚠ Dentro de un armario eléctrico, apantalle el cable I2C. Los campos magnéticos intensos cerca de conductores de red, contactores y transformadores inducen ruido en un cable sin apantallar. Mantenga el cable lo más corto posible y alejado del cableado de red.
Modo de aprovisionamiento de fábrica (firmware antiguo v1.0-v1.2)
En firmware v1.3 un cambio de dirección no requiere el modo de aprovisionamiento de fábrica: se ejecuta en producción mediante el commit en dos fases (vea arriba). Esta sección se aplica solo al firmware heredado (v1.0-v1.2), donde el cambio de dirección monofásico requería un modo especial.
En firmware heredado algunas operaciones del módulo (cambiar la dirección I²C, restablecer los valores de fábrica) requerían que el módulo estuviera en modo de aprovisionamiento de fábrica: un modo especial para acciones de aprovisionamiento puntuales. Los módulos de producción estándar salían de fábrica con el modo de aprovisionamiento desactivado: un intento de cambiar su dirección devolvía un error, visible en los registros de ESPHome como un WARNING al arrancar.
Comportamiento de compatibilidad del componente v1.3:
-
Con
new_address:, el componente comprueba primero si el firmware admite la confirmación en dos fases. Sí → ruta de producción (dos fases, sin protección por aprovisionamiento de fábrica). -
Si no lo hace (firmware heredado v1.0–v1.2), se recurre a la escritura de una sola fase, que solo surte efecto en modo de aprovisionamiento de fábrica. El componente lo registra como
WARN_FACTORY_MODE_REQUIREDen el registro de arranque.
Si tiene un módulo con firmware heredado (el DUT se actualiza en el banco de fábrica, no mediante OTA en campo), consulte a su proveedor el procedimiento para activar temporalmente el modo de aprovisionamiento. En firmware v1.3 este problema no existe.
La configuración de la pinza de corriente (ct_model: / ct_models:) nunca requirió el modo de aprovisionamiento de fábrica: un módulo con cualquier firmware acepta directamente la escritura del modelo de CT (véase 03_sensor_selection.md).
Lo que viene después
- 05_quickstart.md — primera ejecución
- 06_examples.md — escenarios completos: UI1 / UI3 / varios módulos / aprovisionamiento de direcciones
- 10_troubleshooting.md: diagnóstico orientado a síntomas
Fuente e incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/04_hardware.md (v1.9.1)