04 · Cablagem
Este capítulo trata da ligação física do módulo rbAmp a um anfitrião compatível com Arduino: a pinagem do lado de baixa tensão (LV), os requisitos de alimentação, a compatibilidade de níveis I²C, o comprimento do barramento e os esquemas de ligação para placas Arduino específicas (UNO, Mega, ESP32, ESP8266, STM32duino, RP2040).
O lado LV (alimentação + I²C + DRDY opcional) está isolado dos terminais de rede. Os terminais de rede e a ligação do lado do TC estão ligados à rede — veja o aviso em "Ligação do lado da rede" abaixo.
Pinout do lado LV
O módulo funciona com lógica I²C de 3.3 V e é tolerante a 5 V nas linhas de sinal. Todos os pinos LV estão totalmente isolados galvanicamente da rede.
| Pino | Sinal | Função |
|---|---|---|
VCC |
+5 V (4.5..5.5 V) | Alimentação do módulo; mínimo de 4.5 V para funcionamento correto |
GND |
Terra | Partilhado com o master — obrigatório |
SDA |
SDA I²C | Dados I²C |
SCL |
I²C SCL | Relógio I²C |
DRDY |
Data-ready (opcional) | Dreno aberto, impulso LOW de ~10 µs a cada ~100 ms |
Potência
Parâmetros de VCC
- Tensão nominal: 5 V DC
- Intervalo admissível: 4.5..5.5 V
- Corrente de alimentação: ~15 mA típica, ~25 mA de pico durante as escritas na flash
- Ripple: < 50 mV pico a pico (para a precisão da medição)
O módulo tem um regulador integrado, filtro RC, condensadores cerâmicos e uma ferrite — não é necessária filtragem adicional por parte do utilizador. O módulo pode ser alimentado a partir da linha +5V de qualquer placa Arduino (UNO, ESP32 DevKitC, etc.).
Compatibilidade de níveis I²C
-
SDA/SCLfuncionam em lógica de 3.3 V (os pull-ups integrados puxam as linhas para 3.3 V). -
As linhas toleram 5 V: um mestre de 5 V (Arduino UNO / Nano) lê HIGH (~3.3 V) corretamente e pode comandar o barramento sem conversor de nível.
-
Para um barramento a funcionar inteiramente a níveis de 5 V — desative as resistências de pull-up integradas (ver abaixo) e acrescente resistências de pull-up externas para +5 V do lado do mestre.
Comportamento no arranque
- Arranque a frio: ~250 ms até ao primeiro resultado válido.
- Após uma reposição (por software ou por quebra de tensão): ~250 ms para recuperar.
- Até ao primeiro resultado válido, os registos leem
0eDATA_VALID= 0.
A biblioteca aguarda que o módulo fique pronto dentro de dev.begin() — o seu código limita-se a chamar begin() e continua.
Isolamento
O lado LV (I²C, alimentação, DRDY) está isolado dos terminais de rede. Trate os terminais de rede e a ligação do lado do TC como sob tensão.
- O
GNDdo módulo não está ligado à linha da rede nem ao neutro. - Não toque nos terminais L/N nem no condutor da pinça com o circuito energizado.
⚠ Não abra a caixa do módulo — isto anula a calibração de fábrica.
Resistências de pull-up integradas
Importante: cada módulo rbAmp sai de fábrica com resistências de pull-up de 4.7 kΩ integradas em SDA e SCL para 3.3 V. Para um único módulo no barramento, não são necessárias resistências externas — ligue o mestre diretamente.
Quando desativar os pull-ups integrados
Se o barramento tiver vários módulos rbAmp (ou outros dispositivos I²C com as suas próprias resistências de pull-up), ligá-los em paralelo produz uma resistência efetiva demasiado baixa, o que:
- Aumenta o consumo do barramento
-
Pode exceder a corrente máxima de absorção do estágio de saída do mestre I²C (tipicamente ≤ 3 mA em lógica de 3.3 V)
-
Acrescenta carga capacitiva num barramento longo, pouco contribuindo para a imunidade ao ruído
Solução: na face inferior da placa, junto às resistências de pull-up, existem pontes de jumper (serigrafia Pull-Up). Corte-as com uma lâmina afiada para desativar uma pull-up:
-
Deixe os pull-ups ativos em apenas um módulo (ou mova-os para um único ponto junto ao master).
-
Corte as pontes nos restantes módulos.
- Se já existirem pull-ups na placa do mestre — corte as pontes em todos os módulos rbAmp.
Regra prática
| Módulos rbAmp no barramento | Pull-ups |
|---|---|
| 1 | Deixe como está (a de 4.7 kΩ integrada funciona) |
| 2 | Deixe uma ligada, corte a outra |
| 3 | Corte em todos os módulos, instale um par externo de 2.7…3.3 kΩ junto ao mestre |
| 4…6 | Corte em todos os módulos, um par externo de 2.2…2.7 kΩ junto ao mestre |
| 7…16 | Corte em todos os módulos, um par externo de 1.5…2.2 kΩ junto ao mestre; verifique a capacidade do barramento (≤ 400 pF), reduza a velocidade do barramento se necessário |
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.
: meça a resistência entre SDA e VCC com os dispositivos sem alimentação. Deve estar na gama 1.5..4.7 kΩ. Abaixo disso significa demasiadas pull-ups ativas em paralelo.
Parâmetros do barramento I²C
- Endereço predefinido:
0x50(7 bits) - Intervalo de endereços:
0x08..0x77(reatribuído por commit de endereço em duas fases, adequado a produção) - Velocidade: UNO / Mega / STM32 / RP2040 100 kHz; ESP32 / ESP8266 50 kHz. Não use 400 kHz.
- Auto-incremento do ponteiro: apenas nas leituras. Uma leitura em rajada de
devolve N bytes consecutivos a partir de+ N bytes addr. As escritas NÃO são auto-incrementadas: uma escrita em rajada descarta os bytes 1..N e só o primeiro é gravado. Os registos multi-byte são escritos byte a byte em transações separadas de um byte. Ver 09 · Referência da API — «Escritas multi-byte».
Comprimento do barramento
O I²C é um barramento curto (~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. Topologias recomendadas para o rbAmp:
| Cabo | Comprimento máximo | Velocidade |
|---|---|---|
| JST padrão / 4 condutores planos | até 0.15 m | 100 kHz |
| Par entrançado UTP (cat-5/5e/6) — SDA+GND e SCL+GND em pares separados | até 1 m | 100 kHz |
| Par entrançado + buffer I²C (PCA9515 / TCA9617) | até 3 m | 100 kHz |
| Barramento diferencial (PCA9615 / LTC4332) | até 100 m | 100 kHz |
Para comprimentos superiores a 0.15 m, o par entrançado é obrigatório: SDA e SCL têm de estar em pares diferentes, cada um com a sua própria terra (por exemplo, azul + azul-branco para SDA, verde + verde-branco para SCL). SDA e SCL no mesmo par criam capacitância cruzada que distorce os flancos.
⚠ 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.
Cablagem do lado da rede (sensores)
⚠ A tensão da rede pode matar. Desligue e bloqueie o circuito antes de ligar os terminais L/N ou de colocar a pinça; deixe os trabalhos de rede e qualquer intervenção dentro de um quadro a cargo de uma pessoa qualificada. Prenda apenas UM condutor (L) — nunca o cabo inteiro (L+N anulam-se para ~0). Proteja a derivação L com fusível segundo as regras locais.
Sensor de tensão (variantes UI*)
A placa expõe os terminais L (linha) e N (neutro). A polaridade é importante para o sinal da potência ativa:
-
Correto (L → L, N → N):
P > 0significa consumo (corrente da rede para a carga),P < 0significa exportação para a rede (geração). -
Trocados (L e N invertidos): o sinal de P inverte-se — o consumo é contado como potência negativa.
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.
A polaridade correta é crítica para:
-
Contabilidade correta no nível BASIC (o BASIC conta apenas
max(P, 0); com a polaridade trocada o contador de energia fica a zero). -
Separação correta de consumo e geração na linha STANDARD (STD).
: numa carga puramente resistiva (chaleira elétrica, aquecedor, lâmpada incandescente) P > 0 e PF ≈ 1.0. Se P for negativo com uma carga de consumo — troque L e N na placa.
Sensor de corrente — pinça TC SCT-013
As pinças de TC externas ligam-se ao módulo através de um conector jack de 3.5 mm. O conector tem chave — não é preciso tomar decisões de cablagem.
Uma seta no corpo da pinça indica o sentido da corrente para a orientação «normal». Regras:
- Prenda a pinça TC em torno apenas do condutor de linha (L) que vai para a carga.
-
A seta na pinça tem de apontar no sentido da corrente em direção à carga (do disjuntor para a carga).
-
A pinça tem de fechar totalmente — sem qualquer folga entre as metades do núcleo magnético. Se as metades não fecharem por completo, perde-se precisão.
⚠ Não passe L e N por uma só pinça ao mesmo tempo. Os fluxos magnéticos são iguais e opostos, por isso anulam-se — o sensor lerá cerca de zero mesmo com carga.
Para mais sobre a escolha do modelo SCT-013 (5 A / 10 A / 30 A / 50 A / 100 A) e como indicar ao módulo via dev.setCTModel(code) — ver 03_sensor_selection.md.
⚠ A polaridade da pinça de TC importa no BASIC: se a seta da pinça apontar para longe da carga (ou se L/N nos terminais estiverem trocados), P_real lê negativo em consumo — e o nível BASIC limita max(P, 0), pelo que o contador de Wh fica em zero. Rode a pinça fisicamente no condutor; não a inverta em software.
DATA_READY (DRDY)
Um pino opcional para otimização da consulta. Se a aplicação consultar o módulo no máximo uma vez a cada 100 ms, DRDY pode ficar sem ligação.
Parâmetros elétricos
- Tipo de saída: dreno aberto (sem pull-up ativa para VCC)
-
Nível de repouso: HIGH (requer um pull-up no lado do master — o pull-up integrado do MCU ou uma resistência externa)
-
Impulso de prontidão: LOW durante ~10 µs depois de os registos RT (
0x86..0xCF) terem sido atualizados com dados novos -
Frequência de impulsos: ~10 Hz (um impulso por janela RT de ~100 ms)
A biblioteca pode usar a linha por si: dev.setDrdyPin(pin) associa-a (pull-up interna, interrupção por flanco de descida) e dev.waitDataReady() / dev.readAllReady() aguardam o próximo instantâneo do módulo — ver 09 · Referência da API. Vários módulos podem partilhar uma linha DRDY (wired-OR); uma linha mantida em LOW constante significa que um módulo tem um evento mascarado pendente (alarme). Sem linha, as mesmas chamadas consultam.
Semântica
Uma descida de sinal em DRDY garante que todos os registos RT estão sincronizados e publicados (o firmware atualiza-os de forma atómica numa ISR antes de puxar o pino para baixo). Após a descida, o mestre pode ler 0x86..0xCD sem risco de obter uma amostra dividida.
Utilizar no Arduino
-
Interrupção externa (
attachInterruptna descida de sinal) — acorda o mestre e dispara uma leitura. -
Pull-up:
INPUT_PULLUPno MCU, ou um externo de 10 kΩ para 3.3 V. Na UNO / Nano (AVR) use um externo de 10 kΩ para 3.3 V — o pull-up integrado (~40 kΩ) é fraco demais para linhas DRDY longas.
const int PIN_DRDY = 15;
volatile bool data_ready = false;
#if defined(ESP32) || defined(ESP_PLATFORM)
void IRAM_ATTR on_drdy() { data_ready = true; } // ESP32 — ISR in IRAM
#else
void on_drdy() { data_ready = true; } // AVR / STM32duino / RP2040 / SAMD
#endif
void setup() {
Wire.begin();
while (!dev.begin()) { delay(500); }
// Raise the pull-up + attach the ISR AFTER dev.begin() — this
// guarantees the module is already ready and the pull-up edge will not
// cause a spurious interrupt before the first RT window is captured.
// INPUT_PULLUP is fine for most cases; for long
// lines or AVR hosts add an external 10 kΩ to 3.3 V.
pinMode(PIN_DRDY, INPUT_PULLUP);
attachInterrupt(digitalPinToInterrupt(PIN_DRDY), on_drdy, FALLING);
}
void loop() {
if (!data_ready) return; // sleep until the next RT window
data_ready = false;
float p = dev.readPower(0);
// ...integration / transmit...
}
DRDY é opcional — a consulta a qualquer ritmo ≤ 10 Hz funciona sem ele. A biblioteca não depende do DRDY; setDrdyPin() / waitDataReady() são auxiliares de adesão voluntária.
Ligação a diferentes hosts Arduino
O módulo funciona com qualquer placa compatível com Arduino através do Wire padrão. Abaixo estão os pinos predefinidos para as variantes populares.
Arduino UNO / Nano (lógica de 5 V)
| rbAmp | Pino Arduino |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
A4 |
SCL |
A5 |
DRDY (opc.) |
qualquer digital, p. ex. D2 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(); // SDA=A4, SCL=A5 by default
Wire.setClock(100000); // 100 kHz — no 50 kHz clamp needed on AVR
while (!dev.begin()) { delay(500); }
}
A UNO é um host de 5 V, sem necessidade de conversor de nível (as linhas SDA/SCL do módulo toleram 5 V). Os pull-ups integrados do módulo puxam as linhas para 3.3 V, que um master de 5 V lê corretamente como HIGH.
Arduino Mega 2560 (lógica de 5 V)
| rbAmp | Pino Mega |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
D20 |
SCL |
D21 |
DRDY (opc.) |
qualquer digital, por exemplo D18 (suporta interrupções) |
Idêntico à UNO no código, só mudam os pinos físicos. Não é necessário conversor de nível.
ESP32 / ESP32-S3 / ESP32-C3 (lógica de 3.3 V)
| rbAmp | Pino do ESP32 DevKitC |
|---|---|
VCC |
+5V (alimentado a partir de USB-5V na DevKitC) |
GND |
GND |
SDA |
GPIO21 |
SCL |
GPIO22 |
DRDY (opc.) |
qualquer GPIO livre, por exemplo GPIO4 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(21, 22); // SDA=21, SCL=22 (or Wire.begin() with board defaults)
Wire.setClock(50000); // ESP32: 50 kHz
while (!dev.begin()) { delay(500); }
}
O ESP32 é um anfitrião de 3.3 V, com ligação direta ao módulo. A alimentação VCC é obtida do pino +5V da DevKitC (ligado diretamente ao USB-5V).
Pinça de 50 kHz no ESP32 — o padrão recomendado. Em vez de uma chamada explícita Wire.setClock(50000), defina a macro opcional antes do include — begin() aplica a pinça internamente:
#define RBAMP_ESP32_CLAMP_HZ 50000
#include
A macro é opcional (não ativa por predefinição) — para que as chamadas explícitas do utilizador a Wire.setClock() (por exemplo quando um OLED partilha o barramento) sejam preservadas. Ambas as formas funcionam — escolha a que se lê melhor no seu sketch.
Se a sua placa ESP32 não tiver um pino de 5 V (alguns módulos compactos ESP32-S3 / C3 só têm Vin ou nenhum 5 V) — alimente o rbAmp com uma fonte externa de 5 V (por exemplo, um carregador USB + breakout), com GND partilhado com o ESP32.
Uma nota separada sobre a reposição do módulo:
Para uma reposição de software do módulo, use dev.reset() — a biblioteca envia o comando e o módulo reinicia em ~100 ms. Se precisar de uma reposição física (por exemplo, para recuperar de um estado de bloqueio) — corte e volte a ligar a alimentação VCC (desligue durante 1+ segundo).
ESP8266 (Wemos D1 mini / NodeMCU, lógica de 3.3 V)
| rbAmp | Pino ESP8266 (NodeMCU) |
|---|---|
VCC |
Vin ou +5V |
GND |
GND |
SDA |
D2 (GPIO4) |
SCL |
D1 (GPIO5) |
DRDY (opc.) |
D5 (GPIO14) |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(D2, D1); // SDA=GPIO4, SCL=GPIO5
Wire.setClock(50000); // ESP8266 software I²C: 50 kHz for consistency with ESP32
while (!dev.begin()) { delay(500); }
}
O ESP8266 é um host de 3.3 V, ligação direta.
STM32duino (STM32F1 dev-board F103 / Black Pill F411, lógica de 3.3 V)
| rbAmp | Pino STM32 (placa de desenvolvimento STM32F1) |
|---|---|
VCC |
+5V |
GND |
GND |
SDA |
PB7 (I²C1_SDA) |
SCL |
PB6 (I²C1_SCL) |
DRDY (opc.) |
qualquer GPIO com EXTI, p. ex. PA0 |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.begin(); // SDA=PB7, SCL=PB6 by default for I²C1
Wire.setClock(100000); // the STM32 HAL I²C needs no 50 kHz clamp
while (!dev.begin()) { delay(500); }
}
O STM32duino suporta várias instâncias de Wire (Wire1, Wire2 para um segundo I²C). Se o barramento principal estiver ocupado — use o segundo periférico I²C.
RP2040 / SAMD (Raspberry Pi Pico, arduino-pico)
| rbAmp | Pino RP2040 (Pico) |
|---|---|
VCC |
VBUS (5 V do USB) ou +5V |
GND |
GND |
SDA |
GP4 |
SCL |
GP5 |
DRDY (opc.) |
qualquer GP |
#include
#include
RbAmp dev(Wire, 0x50);
void setup() {
Wire.setSDA(4);
Wire.setSCL(5);
Wire.begin();
Wire.setClock(100000); // the RP2040 hardware I²C needs no 50 kHz clamp
while (!dev.begin()) { delay(500); }
}
O RP2040 é um anfitrião de 3.3 V, com ligação direta. Nas placas SAMD (Arduino Zero, MKR) o Wire.begin() com valores predefinidos funciona da mesma forma — os pinos concretos dependem da placa.
Pico via VSYS (bateria / alimentação externa): o pino VBUS só está presente quando alimentado por USB. Se o Pico funcionar a partir de uma bateria ou de uma fonte externa através de VSYS, o VBUS não transporta nada. Alimente 5 V de uma fonte externa diretamente ao VCC do módulo, com o GND partilhado com o Pico.
Diagrama de cablagem de referência (ESP32 + módulo único)
Nesta configuração:
- As resistências de pull-up externas em I²C NÃO são necessárias (já integradas no módulo).
- O DRDY é opcional; como na imagem, use um pull-up externo de 10 kΩ para 3.3 V (o INPUT_PULLUP no pino do ESP32 também funciona em fios curtos).
- A ficha do TC SCT-013 está totalmente inserida.
- A pinça está totalmente fechada no fio L, com a seta em direção à carga.
Diagrama de cablagem de referência (Arduino UNO + módulo único)
Nesta configuração:
- Não são necessárias resistências de pull-up externas em I²C.
- A UNO trabalha com lógica de 5 V; os SDA/SCL do módulo toleram 5 V, sem necessidade de conversor de nível.
- O DRDY tem um nível de 3.3 V — numa UNO uma entrada TTL lê isto como HIGH (VIH_TTL ≥ 2.0 V, 3.3 V > 2.0 V). Recomenda-se uma pull-up do DRDY especificamente para 3.3 V por segurança: se os circuitos de proteção internos do pino DRDY não forem tolerantes a 5 V (separadamente das linhas I²C, cuja tolerância a 5 V está confirmada), uma pull-up para 5 V criaria uma pequena corrente de fuga através dos díodos ESD para a linha de 3.3 V do módulo. Para 3.3 V — nunca é problema.
Modelos multifásicos e a linha STANDARD (STD)
As SKU multicanal e multifásicas mantêm a mesma pinagem LV (VCC / GND / SDA / SCL / DRDY). Só muda o lado da rede — mais terminais L e mais conectores de ficha de TC.
Os módulos STANDARD (STD) usam a mesma cablagem I²C que os módulos BASIC — as mesmas quatro linhas de sinal, os mesmos pull-ups e regras de barramento acima. Nada muda na ligação; o dev.begin() deteta qual a linha ligada (dev.line()), e o mesmo esboço serve ambos. Notas:
-
As chamadas que existem apenas na linha STD (a família
std*, potência reativa e aparente) devolvemRB_ERR_NOT_IMPLEMENTEDnum módulo BASIC (no BASIC, a potência reativa não é exposta por esta biblioteca). -
Algumas funcionalidades STD dependem da versão da imagem do módulo: contadores de energia de micro-resolução, a corrente de arranque para a energia, os ângulos de fase de tensão e a sequência de fases exigem uma imagem de pelo menos
0x0001007B(dev.stdReadImageVersion()). Numa imagem mais antiga são reportadas como «não disponível». -
O número de canais de tensão e de corrente vem do módulo (
dev.stdInfo()); a biblioteca expõe atéRBAMP_MAX_CHANNELS(7) canais de corrente.
Barramento multimódulo — a topologia principal
O caso de uso canónico da biblioteca são vários módulos rbAmp num só barramento I²C, geridos por um único Arduino / ESP32 através do RbAmpFleet. Todas as regras e otimizações abaixo foram pensadas precisamente para esta topologia; um módulo isolado é um caso particular (o mesmo handle, mas as chamadas de frota degeneram em triviais).
Implementações típicas
| Cenário | Configuração | Número de módulos |
|---|---|---|
| Cânone dos 80%: alimentação doméstica + subcontadores | 1× UI1 (alimentação, energia da rede) + 3–6× UI1/I1 (cargas) | 4-7 |
| Subquadro com repartição de corrente | 1× UI1 (alimentação) + 1-2× I2/I3 (corrente por circuito) | 3-5 |
| Subcontagem industrial | 1× UI1 (alimentação) + N× I2/I3 (por máquina, repartição de corrente) | até ~16 |
Limites elétricos
- Número de módulos: até ~16 (capacidade total do barramento ≤ 400 pF a 100 kHz; a 50 kHz há mais margem).
- Pull-ups para o barramento da frota (importante): cada módulo vem com 4.7 kΩ integrados. Num barramento com N módulos os pull-ups funcionam em paralelo → o sumidouro fica sobrecarregado e o barramento não consegue descer até LOW. A partir de 4 módulos (ou mais cedo num barramento com mais de 15 cm) corte os pull-ups integrados em todos os módulos exceto um — com 2–3 módulos num barramento até 15 cm deixe-os em paz, esse caso está medido (ou corte-os em todos e mantenha apenas pull-ups externos (2.7…3.3 kΩ para 3 módulos, valores mais baixos para barramentos maiores — ver a tabela acima) ligados a 3.3 V num único ponto do barramento — recomendado para troços longos / ruído / ESP32 como master).
- Os pull-ups internos do ESP32 (~45 kΩ) são fracos demais para um barramento com vários módulos e comprimentos reais de cabo — são necessários pull-ups externos (valores: ver a tabela acima). Isto faz parte da mitigação em três camadas contra o bloqueio do barramento numa linha marginal — ver 10 · Resolução de problemas, a secção «O projeto ESP32 bloqueia».
Endereçamento — provisionamento e substituição em campo (aprovado para produção)
O endereço de fábrica predefinido é 0x50. Cada módulo novo ou de substituição passa pelo provisionamento (uma vez): reatribuição de 0x50 para um endereço de trabalho + gravação opcional da configuração (modelos de TC, group_id, etiqueta) na flash. O modo de fábrica não é necessário — a alteração de endereço funciona diretamente em produção através do commit de endereço em duas fases.
Método 1 — RbAmpFleet::provision() (recomendado)
RbAmp* dev = nullptr;
if (RbAmpFleet::provision(Wire, /*desired=*/0x52, /*save=*/true, dev)) {
fleet.add(dev); // ready handle, now in the fleet
}
Uma única chamada varre 0x50, executa o commit de endereço em duas fases, reinicia, procura o módulo no novo endereço dentro da janela de arranque e (opcionalmente) emite SAVE_USER_CONFIG para persistência. Devolve false em caso de violação da disciplina (ver abaixo) ou de falha de transporte.
Método 2 — prepare/commitAddressChange de baixo nível (forma manual)
dev.prepareAddressChange(0x52); // candidate in RAM
dev.commitAddressChange(); // arms 0xA5 + COMMIT_ADDR + reset
delay(300); // boot window
O mesmo mecanismo de duas fases de provision(), sem o wrapper da frota. Usado quando o RbAmpFleet não foi criado.
Protocolo de transmissão por dentro (para referência)
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. wait ~700 ms (flash erase + write)
5. issue CMD_RESET (opcode 0x01) — CMD_COMMIT_ADDR does not auto-reset
6. wait ~300 ms; the module responds at the new address
✅ REG_I2C_ADDRESS (0x30) lê o endereço ativo no arranque (sincronização de endereço no arranque, v1.3). Após o reinício pós-commit, a leitura de 0x30 mostra o novo endereço ativo. O comportamento de eco de preparação mantém-se até CMD_COMMIT_ADDR + reposição.
⚠ Disciplina de provisionamento — DEVE ser um virgem de cada vez.
A causa mais comum de falhas de provisionamento é haver mais do que um módulo com o endereço de fábrica 0x50 no barramento. É fisicamente impossível distingui-los por I²C (barramento open-drain: ambos os módulos respondem com ACK de forma idêntica, e os dados lidos ficam «colados»).
Portanto, a regra é estrita (um MUST normativo, não uma recomendação): no momento em que chama RbAmpFleet::provision() (ou prepareAddressChange()), tem de existir exatamente um módulo em 0x50 (um novo ou um reposto às predefinições de fábrica através de uma ferramenta de bancada separada). Nada de «tenho a certeza de que estes dois módulos são diferentes — vou separá-los agora»: não vai funcionar; a colisão aparece mais tarde, quando já achar que a frota está limpa.
Caminho de recuperação se suspeitar de uma violação da disciplina: 1. Desligue e volte a ligar a alimentação de todos os módulos. 2. Desligue fisicamente todos os módulos "virgens" exceto um. 3. Chame RbAmpFleet::provision() no barramento com um só módulo. 4. Acrescente os restantes módulos um de cada vez, provisionando cada um separadamente.
Orçamento de energia do barramento
A 50 kHz, uma transação de leitura ≈ 200-400 µs. Um bloco RT completo de um canal (U + I + P + PF) ≈ 5-8 ms por canal.
| Configuração | Ciclo de barramento | A 50 kHz | Taxa máxima de consulta |
|---|---|---|---|
| 1× UI1, bloco RT | ~5 ms | < 5 ms | 100+ Hz (mas o módulo atualiza a 10 Hz) |
| 1× UI3, bloco RT + período | ~25 ms | ~25 ms | até 10 Hz |
| 5× UI1, bloco RT | ~25 ms | ~25 ms | até 10 Hz |
| 16× UI3, RT + período | ~400 ms | 400 ms > 100 ms | não consegue acompanhar o módulo (10 Hz); ~2 Hz no máximo |
Os números são estimativas (200–400 µs/transação, depende do MCU). Os números são estimativas e dependem do MCU do host.
Regra: a 50 kHz os limites confortáveis são 8-10× UI3 ou 15-16× UI1 com consulta a 5 Hz (a cada segunda janela do módulo), e cerca de metade disso à taxa total de 10 Hz.
Sincronização de período
Para a medição tarifária, todos os módulos têm de tirar o seu instantâneo sobre o mesmo intervalo. Duas estratégias:
Estratégia 1 — instantâneo sequencial + estabilização comum (qualquer firmware):
RbAmp meters[N]; // array of initialized modules
void period_cycle() {
// Phase 1: sequential snapshot
for (auto& m : meters) m.latchPeriod();
// Phase 2: common settle (≥ 50 ms)
delay(50);
// Phase 3: read the snapshots with skip_latch=true
for (auto& m : meters) {
RbAmpSnapshot snap;
m.readPeriodSnapshot(snap, /*skip_latch=*/true);
}
}
Desfasamento entre módulos: 16 módulos × ~1 ms/instantâneo = ~16 ms ao longo de um período de 60 s. Desprezável para totais de energia.
Estratégia 2 — instantâneo de difusão General-Call (requer ativação):
Todos os módulos tiram o seu instantâneo com uma única trama I²C no endereço 0x00:
addr=0x00 | A5 27 (5 bytes)
Desfasamento = 0 (atómico). Pré-configuração (uma vez em cada módulo da frota):
- Defina
REG_FLEET_CONFIG.bit0 = 1viaCMD_SAVE_USER_CONFIG. CMD_RESET— a receção GC é ativada no arranque.- Após a reposição, o master envia a trama de 5 bytes em
0x00. - Testemunha: para cada módulo esperado, leia
REG_V03_PERIOD_VALID (0x07).!=1→ recorra à estratégia 1.
Qual usar:
- < 8 módulos: estratégia 1 (mais simples, não exige enable).
- ≥ 8 módulos ou sincronização apertada: estratégia 2.
Filtragem por grupo GC (barramento multi-inquilino)
REG_GROUP_ID (0x28) permite ter vários domínios GC num barramento:
group = 0x00→ chamada geral a todos (todos os módulos com GC ativa tiram um instantâneo).group = N→ só os módulos comREG_GROUP_ID = Ntiram um instantâneo.
Caso de uso — separar grupos tarifários (dia e noite) num barramento partilhado.
Modos de falha
| Sintoma | Causa | O que fazer |
|---|---|---|
i2c bus scan mostra vários módulos no mesmo endereço após uma adição em campo |
Um novo módulo em 0x50 entra em conflito com outro já endereçado |
Reatribua o novo módulo separadamente antes de o acrescentar |
| Um módulo responde com NACK com mais frequência do que os outros | Falha de cabo / queda de VCC | Verifique a VCC sob carga |
| Os Wh de um módulo divergem de forma consistente | O relógio do próprio módulo difere do do master | A energia é integrada no relógio do mestre; compare com master_dt_ms, e não com latch_ms |
| Após uma trama GC, um módulo não tira o instantâneo | FLEET_CONFIG.bit0 = 0 ou desfasamento de grupo |
Verifique REG_FLEET_CONFIG e REG_GROUP_ID |
Notas de conceção do barramento
- Clock stretching: o instantâneo do módulo só o pausa durante microssegundos; o SCL não é esticado de forma significativa. Para o Raspberry Pi BCM283x (bug de hardware conhecido no stretching): a precaução-padrão é 50 kHz + repetição.
- Comprimento com mais de 4 módulos: considere um buffer I²C (PCA9515) a partir de 8 módulos + um comprimento superior a 1 m.
Cenários multimódulo detalhados — em 06 · Exemplos.
O que vem a seguir
- 02 · Níveis dos módulos — comportamento do firmware por nível
-
03 · Seleção do sensor de corrente — que modelo SCT-013 e como o indicar ao módulo
-
05 · Arranque rápido — o seu primeiro esboço a funcionar
- 10 · Resolução de problemas — o que fazer se o barramento não funcionar / a I_rms for instável / o sinal de P estiver errado
Fonte e problemas: rb-amp/rbamp-arduino · esta página no repositório: docs/04_hardware.md (v1.6.2)