04 · Cablagem
Este capítulo trata da cablagem física do rbAmp a um ESP32: seleção de GPIO, regras de pull-up, barramento com vários módulos, alimentação, linha DRDY opcional e provisionamento de endereços.
Implementação canónica — uma frota multi-módulo num único barramento. 80% das instalações no terreno são constituídas por 1× UI1 (rede) + N× I2/I3 (sub-contadores) num único barramento I²C do ESP32, com os pull-ups definidos conforme a tabela abaixo. Ver 01_overview.md para a visão geral da frota. Um único módulo é o caso mínimo, não o canónico. Este capítulo cobre as duas topologias, mas o multi-módulo está assinalado como a "topologia principal" nas secções relevantes.
Módulos STANDARD (STD). A cablagem, as regras de pull-up, a alimentação e a linha DRDY opcional são iguais para os módulos BASIC e STANDARD, e o mesmo YAML funciona para ambos — o componente identifica o módulo ligado no arranque. new_address: funciona nas duas linhas de módulos. A sincronização de frota por General Call (fleet_gc_enable: / group_id:) aplica-se apenas aos módulos BASIC; num módulo STANDARD essas chaves são ignoradas com uma linha de log.
PERIGO: os terminais L/N transportam tensão da rede. Desligue e bloqueie o circuito antes de ligar, faça com que um técnico qualificado trate da cablagem da rede e de qualquer trabalho dentro de um quadro, prenda APENAS UM condutor (L) e nunca deixe a pinça de CT num condutor com a ficha de CT desligada.
Fio e fusível. Não é necessário um fio grosso para a ligação de tensão: AWG26–22 chega, porque o sensor de tensão consome muito pouca corrente. Um fusível na linha L é obrigatório, de calibre até 0.1 A.
O lado da rede num relance. A L e a N da rede ligam aos dois terminais do módulo (fornecem a leitura de tensão); a pinça CT encaixa na tomada CT e envolve apenas o condutor L, com a seta apontada para a carga. Tudo o resto deste capítulo é o lado de baixa tensão.
Pinout do lado LV
O lado de baixa tensão do módulo expõe cinco sinais. Todos estão isolados galvanicamente da rede — o pino GND é o GND do ESP32, não o neutro da rede.
| Pino | Sinal | Descrição |
|---|---|---|
VCC |
+4.5..+5.5 V DC | Alimentação do módulo. 5 V nominais; abaixo de 4.5 V as leituras podem tornar-se pouco fiáveis. |
GND |
Comum | Comum com o mestre. Obrigatório. |
SDA |
Dados I²C | Lógica de 3.3 V; tolerante a 5 V. |
SCL |
Relógio I²C | Lógica de 3.3 V; tolerante a 5 V. |
DRDY |
Dados prontos (opcional) | Saída open-drain. Impulso LOW de ~10 µs a cada ~100 ms após a atualização dos registos instantâneos. |
Seleção de GPIO no ESP32
Qualquer par de GPIOs que suporte I²C funciona. A matriz de periféricos do ESP32 permite encaminhar o I²C para quase qualquer pino. Restrições práticas:
- GPIO0 e GPIO2 são pinos de bootstrap. Um nível baixo neles na alimentação bloqueia o arranque. Não usar.
- Os GPIO 6..11 estão ligados à flash ou PSRAM incorporada na maioria dos módulos ESP32-WROOM. Indisponíveis.
- GPIO 34..39 são apenas de entrada. Não são adequados para I²C (que precisa de condução bidirecional).
- Não ligue nenhum GPIO do ESP32 a uma linha de reset do módulo — o módulo é reposto com um comando I²C, e não são necessários pinos de reset físicos do lado do mestre.
Atribuições predefinidas recomendadas que funcionam na maioria das placas ESP32-DevKitC:
| Sinal | GPIO | Nota |
|---|---|---|
| SDA | GPIO21 | Predefinição em todos os YAML de exemplo |
| SCL | GPIO22 | Predefinição em todos os YAML de exemplo |
| DRDY | GPIO15 | Opcional; qualquer pino com capacidade de entrada funciona |
Se os GPIO21/22 estiverem ocupados, escolha qualquer outro par válido e atualize o bloco i2c: no YAML.
Ligar um módulo único
A cablagem completa do ESP32 está indicada no esquema de referência abaixo.
Resistências de pull-up externas não são necessárias para um único módulo — a placa rbAmp já tem pull-ups integrados de 4.7 kΩ em SDA e SCL para 3.3 V.
Barramento com vários módulos (topologia principal)
A maioria das implementações rbAmp é uma frota de vários módulos num único barramento I²C do ESP32: uma UI1 na rede mais várias I2/I3 em sub-ramais. Esta é a topologia principal para que o componente foi concebido, e a configuração de pull-up abaixo está otimizada para ela.
Quando dois ou mais módulos (ou outros dispositivos I²C com os seus próprios pull-ups) partilham um barramento, os pull-ups somam-se em paralelo. A resistência combinada desce abaixo do mínimo efetivo — o que leva a:
- Consumo excessivo do barramento.
- Possível sobrecarga das saídas open-drain do ESP32 (tipicamente ≤ 3 mA a 3.3 V).
- Carga capacitiva mais elevada num barramento longo.
Na face inferior de cada PCB rbAmp existem jumpers de soldadura marcados Pull-Up. Cortar a pista com uma lâmina afiada desliga o par de 4.7 kΩ integrado desse módulo.
| Módulos no barramento | Configuração de pull-up | R efetivo |
|---|---|---|
| 1 | Mantenha o par integrado. Não é necessário externo. | ~4.7 kΩ |
| 2 | Deixe apenas no primeiro; corte o segundo. | ~4.7 kΩ |
| 3 | Corte em todos. Um par externo de 2.7..3.3 kΩ no ESP32. | 2.7..3.3 kΩ |
| 4..6 | Corte em todos. Um par externo de 2.2..2.7 kΩ no ESP32. | 2.2..2.7 kΩ |
| 7..16 | Corte em todos. Um par externo de 1.5..2.2 kΩ no ESP32 + verificação da capacidade do barramento (ver abaixo). | 1.5..2.2 kΩ |
| O ESP32 já fornece pull-ups | Corte em todos os módulos. Os pull-ups internos do ESP32 (≥50 kΩ) são fracos — um barramento longo continua a precisar de 2.2..4.7 kΩ externos. | igual ao anterior |
Os valores externos são valores recomendados (calculados a partir da especificação I²C: corrente de sumidouro ≤ 3 mA a 3.3 V, capacidade do barramento ≤ 400 pF). Ligue os pull-ups externos a 3.3 V (o nível lógico do barramento), e não à alimentação VCC de 5 V.
Lógica de seleção: a R_pullup efetiva é a combinação em paralelo de todos os pull-ups ativos. A gama-alvo é 1.5..4.7 kΩ (o mínimo é limitado pela corrente de dreno do ESP32 ≤ 3 mA a 3.3 V; o máximo pela constante RC do barramento). Fórmula: 1/R_eff = N/R_unit. Para o par integrado de 4.7 kΩ: 2 módulos = 2.35 kΩ, 3 = 1.57 kΩ, 4 = 1.18 kΩ — com 3 módulos o valor em paralelo é 1.57 kΩ, ainda dentro da gama, e um barramento de 3 módulos até 15 cm é medido como fiável (cabos de 15 cm, 50 kHz), pelo que a tabela mantém os jumpers integrados em 2 e 3 módulos. A partir de 4 módulos, ou mais cedo num barramento mais longo, retiram-se e passa-se a um único par externo.
Verificação de diagnóstico: meça a resistência entre SDA e VCC com a alimentação desligada. O resultado deve estar na gama 1.5..4.7 kΩ. Abaixo de 1.0 kΩ significa demasiados pull-ups ativos em paralelo; acima de 10 kΩ significa que não há pull-up ativo (verifique os jumpers).
Capacidade do barramento (para ≥7 módulos ou comprimento total de cablagem > 50 cm): a especificação I²C limita a capacidade total C_b a ≤ 400 pF. Um barramento curto com 2-3 módulos fica tipicamente entre 50 e 100 pF; um barramento de 1 m com 10 módulos pode chegar a 300..400 pF. Quando estiver perto do limite, passe para frequency: 50kHz (se ainda estiver a 100 kHz) ou use um CI de pull-up ativo (por exemplo o PCA9517).
Velocidade do barramento
Defina frequency: 50kHz no bloco i2c: do ESPHome. No firmware atual isto é obrigatório para um funcionamento fiável com o ESP-IDF v5:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32 — ESP-IDF i2c_master driver interaction, see below
O módulo faz NACK periodicamente às leituras de um ESP32 a 100 kHz (uma parte notável das transações) devido à interação entre a temporização do driver i2c_master do ESP-IDF v5 e a janela de recuperação pós-STOP do periférico I²C do módulo. A 50 kHz os NACK são bastante mais raros, e a repetição por byte dentro do componente recupera > 99% das leituras válidas.
O firmware reforçou a janela de recuperação I²C do módulo (lançado na v1.1 e v1.3), o que reduziu a contribuição do lado do módulo — mas 50 kHz continua a ser a definição recomendada em mestres baseados em ESP-IDF, porque a interação de temporização do driver persiste a 100 kHz. Trate-a como recomendação permanente para o ESP32, não como solução temporária à espera de correção.
Outros mestres I²C correm este módulo a 100 kHz sem problemas: STM32 HAL, RP2040 SDK, Raspberry Pi smbus2 (I²C do kernel Linux) e Arduino não ESP32 (AVR / STM32duino). Repare que o eixo é o driver, não a placa: o Arduino num ESP32 usa o mesmo driver i2c_master do ESP-IDF, por isso também precisa de 50 kHz — só o Arduino não ESP32 corre a 100 kHz.
Esquema de referência — um ESP32 + um rbAmp
Notes:
- A resistência de 10 kΩ no DRDY está do lado do mestre (junto ao GPIO), não do lado do módulo. O DRDY é open-drain, sem pull-up interno.
- A tomada CT deve estar totalmente inserida; a pinça deve envolver completamente um único condutor com a seta apontada para a carga.
- A polaridade L/N nos terminais afeta o sinal de P (ver 03_sensor_selection.md).
Potência
Alimentação do módulo (VCC)
O módulo requer +4.5..+5.5 V DC. Consumo de corrente:
| Modo | Típico |
|---|---|
| Medição em regime estacionário | ~15 mA |
Escrita em flash (durante o provisionamento de ct_model: / endereço) |
~25 mA de pico, ~700 ms |
| Aquecimento do arranque (~250 ms) | ~15 mA |
O pino 5V de um ESP32-DevKitC (normalmente ligado ao VBUS do USB) pode alimentar o módulo diretamente — o anfitrião USB tem de fornecer a corrente combinada do ESP32 (~200 mA) + rbAmp (~15 mA de pico) = ~215 mA. Nas instalações em que o ESP32 é alimentado por uma SMPS externa de 5 V, ligue o VCC à mesma linha de 5 V.
Subtensão do ESP32
O detetor de subtensão do ESP32 dispara a ~2.43 V em VDD. Quando dispara, o barramento I²C fica inativo enquanto o módulo continua a medir de forma autónoma (tem a sua própria alimentação de 5 V). Quando o ESP32 recupera, o setup() restaura a energia acumulada a partir da NVS antes do primeiro update(). O HA não vê nem uma falha nem uma reposição no gráfico de energia.
DRDY opcional
O pino DRDY do módulo é open-drain. Pulsa em LOW durante ~10 µs a cada ~100 ms, logo após o bloco de registos instantâneos ser atualizado. Não dispara no snapshot do período.
Com update_interval: 60s pode omitir o DRDY — o componente verifica o registo de estado no início de cada update() e salta a leitura se o módulo não estiver pronto. O componente regista o pino DRDY; as leituras são controladas por temporizador (update_interval).
Cablagem DRDY
O DRDY é open-drain: puxa para LOW mas não consegue conduzir para HIGH. Precisa de um pull-up externo:
rbAmp DRDY ──────────────────┬── ESP32 GPIO (input)
|
[10K]
|
3.3V
10 kΩ para 3.3 V. Não ligue o DRDY a 5 V, mesmo que SDA/SCL sejam tolerantes a 5 V — o DRDY é um sinal separado, e o máximo absoluto de um GPIO de entrada do ESP32 é 3.6 V.
Declare o pino no YAML:
rbamp:
id: meter1
drdy_pin: GPIO15
DRDY multi-módulo
Os sinais DRDY de vários módulos podem ser ligados em OR por fio a um único GPIO do ESP32 (as saídas open-drain combinam-se naturalmente). O sinal partilhado fica LOW quando qualquer módulo atualizou os seus registos instantâneos. O componente regista apenas o pino; não indica qual módulo disparou.
Se precisar de sinais separados, encaminhe o DRDY de cada módulo para o seu próprio GPIO e declare drdy_pin: em cada bloco rbamp: individualmente.
Atribuição de endereços num barramento multi-módulo
Todos os módulos rbAmp saem de fábrica no endereço 0x50. Antes de ligar vários módulos a um barramento, cada um precisa de um endereço único. No firmware v1.3 isto pode ser feito em produção sem o modo de provisionamento de fábrica — graças ao protocolo de commit em duas fases.
Commit de endereço em duas fases (v1.3+, produção OK)
Com new_address: o componente executa a seguinte sequência:
-
Verifica se o firmware suporta o commit em duas fases. Se sim, segue o caminho de modo de produção. Se não, recorre ao fallback monofásico legado com condicionamento por provisionamento de fábrica (firmware v1.0-v1.2).
-
Escreve o novo endereço em
REG_I2C_ADDRESS(preparado, ainda não ativo). -
Escreve a "palavra mágica"
0xA5emREG_ADDR_COMMIT_MAGIC— uma confirmação explícita de intenção que protege contra uma escrita acidental emREG_I2C_ADDRESS. -
Envia o opcode
CMD_COMMIT_ADDR— o módulo aplica atomicamente o endereço preparado, guarda-o na flash e faz um reset suave. -
Após ~700 ms o componente volta a associar o handle i2c_address ao novo endereço e verifica a reenumeração com uma leitura de sonda.
Se algum passo falhar, o módulo volta ao endereço anterior, sem ficar nenhum estado "meio aplicado". Uma ida e volta 0x50 → 0x60 → 0x50 reenumera em menos de um segundo.
Provisionamento sequencial (fluxo recomendado)
Vários módulos juntos no barramento antes do provisionamento são uma colisão de endereços (todos em 0x50). Por isso o provisionamento é sequencial, um módulo de cada vez:
- Ligue apenas o módulo 1 ao ESP32 (sozinho no barramento).
-
Grave a configuração de
example/address_change.yamlcomaddress: 0x50enew_address: 0x51. No arranque o componente deteta a discrepância → executa o commit em duas fases (ver acima). -
Confirme o sucesso nos logs do ESPHome (reenumeração no novo endereço). Atualize o YAML:
address: 0x51, removanew_address:. -
Desligue o módulo 1. Ligue o módulo 2 (ainda no
0x50de fábrica). -
Repita para
0x52,0x53, e assim por diante. OBRIGATÓRIO: apenas um módulo virgem no barramento de cada vez — caso contrário ambos respondem em 0x50, o que causa disputa no barramento. -
Quando todos os módulos tiverem endereços únicos, ligue-os todos ao barramento e defina os pull-ups conforme a tabela em Barramento multi-módulo (2 módulos: mantenha um par; 3 ou mais: corte todos e acrescente um par externo).
Perigo de provisionamento concorrente: se dois módulos virgens estiverem ambos em 0x50, ambos fazem ACK ao byte de endereço e puxam o SDA um contra o outro na fase de dados → contenção do barramento + dados indeterminados. Sempre um virgem de cada vez.
Exemplo de YAML multi-módulo
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" }
A versão completa com anotações está em example/multi_module.yaml.
Comprimento do barramento
I²C é um protocolo de curta distância (~15 cm por predefinição). Muitos utilizadores ligam os módulos com fios de jumper de baixa qualidade, que captam muito ruído e perdem muitas transferências — daí o limite curto. Comprimentos recomendados para rbAmp:
| Tipo de cabo | Comprimento máximo | Velocidade |
|---|---|---|
| JST padrão / flat de 4 fios | 0.15 m | 50 kHz |
| Par entrançado (SDA+GND e SCL+GND em pares separados) | 1 m | 50 kHz |
| Par entrançado + buffer I²C (PCA9515 / TCA9617) | 3 m | 50 kHz |
| Barramento diferencial (PCA9615 / LTC4332) | 100 m | 50 kHz |
Para mais de 0.15 m, use par entrançado, e SDA e SCL têm de estar em pares separados (por exemplo azul + branco-azul para SDA, verde + branco-verde para SCL). Se SDA e SCL partilharem um par, a acoplagem cruzada distorce as transições mesmo a 50 kHz.
⚠ Dentro de um armário elétrico, blinde o cabo I2C. Campos magnéticos fortes perto de condutores da rede, contactores e transformadores induzem ruído num cabo sem blindagem. Mantenha o cabo o mais curto possível e afastado da cablagem da rede.
Modo de provisionamento de fábrica (firmware antigo v1.0-v1.2)
Na v1.3 do firmware uma alteração de endereço não exige o modo de provisionamento de fábrica — corre em produção através do commit em duas fases (ver acima). Esta secção aplica-se apenas ao firmware legado (v1.0-v1.2), em que a alteração monofásica de endereço exigia um modo especial.
Na firmware legada algumas operações do módulo (alterar o endereço I²C, reposição de fábrica) exigiam que o módulo estivesse em modo de provisionamento de fábrica — um modo especial para ações de provisionamento únicas. Os módulos de produção standard saíam de fábrica com o modo de provisionamento desativado: uma tentativa de alterar o endereço devolvia um erro, visível nos registos do ESPHome como um WARNING no arranque.
Comportamento de compatibilidade do componente v1.3:
-
Com
new_address:o componente primeiro verifica se a firmware suporta o commit em duas fases. Sim → caminho de produção (duas fases, sem controlo de provisionamento de fábrica). -
Se não o fizer (firmware legado v1.0-v1.2) → recua para a escrita de fase única, que só tem efeito no modo de provisionamento de fábrica. O componente regista isto como
WARN_FACTORY_MODE_REQUIREDno registo de arranque.
Se tiver um módulo com firmware legada (o DUT é atualizado através da bancada de fábrica, não por OTA no terreno), contacte o seu fornecedor para o procedimento de ativação temporária do modo de provisionamento. Na firmware v1.3 este problema não existe.
A configuração de sensores de corrente (ct_model: / ct_models:) nunca exigiu o modo de provisionamento de fábrica — um módulo em qualquer firmware aceita uma escrita de modelo de CT diretamente (ver 03_sensor_selection.md).
O que vem a seguir
- 05_quickstart.md — primeira execução
- 06_examples.md — cenários completos: UI1 / UI3 / multi-módulo / provisionamento de endereços
- 10_troubleshooting.md — diagnósticos orientados por sintomas
Origem e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/04_hardware.md (v1.9.1)