rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub

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.

Segurança

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.

Cablagem do painel: a pinça CT no fio L após o disjuntor de entrada, com a tomada de referência de tensão L e N para o módulo.

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.

Os cinco pinos de baixa tensão do módulo rbAmp e o que cada um necessita.

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.

Vários módulos rbAmp num barramento I²C com os pull-ups integrados cortados e um par externo no mestre, mais as opções de DRDY.

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.

Regras de pull-up I²C para um a três módulos num barramento curto e para quatro ou mais, com o jumper de solda no módulo e a velocidade do barramento por mestre.

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:

YAML
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

Cablagem de referência entre uma placa de desenvolvimento ESP32 e um módulo rbAmp, com a pinça CT no fio L e uma linha DRDY opcional.

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.

Janelas de medição contínuas de 100 ms, um pulso DRDY por janela e a leitura em rajada pelo mestre do bloco de resultado atómico.

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:

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

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:

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

  2. Escreve o novo endereço em REG_I2C_ADDRESS (preparado, ainda não ativo).

  3. Escreve a "palavra mágica" 0xA5 em REG_ADDR_COMMIT_MAGIC — uma confirmação explícita de intenção que protege contra uma escrita acidental em REG_I2C_ADDRESS.

  4. Envia o opcode CMD_COMMIT_ADDR — o módulo aplica atomicamente o endereço preparado, guarda-o na flash e faz um reset suave.

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

A alteração de endereço em duas fases: preparar, armar, confirmar, aguardar, reiniciar, aguardar e verificar no novo endereço.

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.

O provisionamento endereça um módulo virgem de cada vez no barramento, repetindo depois para o seguinte.

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:

  1. Ligue apenas o módulo 1 ao ESP32 (sozinho no barramento).
  2. Grave a configuração de example/address_change.yaml com address: 0x50 e new_address: 0x51. No arranque o componente deteta a discrepância → executa o commit em duas fases (ver acima).

  3. Confirme o sucesso nos logs do ESPHome (reenumeração no novo endereço). Atualize o YAML: address: 0x51, remova new_address:.

  4. Desligue o módulo 1. Ligue o módulo 2 (ainda no 0x50 de fábrica).

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

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

Nota

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

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

Segurança

⚠ 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_REQUIRED no 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.

Nota

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


Origem e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/04_hardware.md (v1.9.1)