05 · Arranque rápido
Um "olá mundo" de cinco minutos: instale a biblioteca, ligue o módulo, selecione um sensor, faça a sua primeira leitura RT e o seu primeiro instantâneo por período (Wh).
Os detalhes (pinagem para um anfitrião específico, barramento multimódulo, escolha de um SCT-013 por gama) estão nos capítulos vizinhos:
-
04 · Cablagem — detalhes de hardware e secções por MCU de cada placa
-
03 · Seleção do sensor de corrente — qual o modelo SCT-013 a escolher e porquê
O que vai precisar
- Um módulo rbAmp (qualquer nível, UI1 por simplicidade)
- Um host compatível com Arduino — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
- Uma pinça SCT-013 com calibre acima da sua maior corrente esperada (5A / 10A / 30A / 50A / 100A) — ou a pinça que veio ligada ao seu módulo
- Uma alimentação de 5 V para o módulo (da USB-5V do host ou externa)
- Um circuito AC a medir (um candeeiro, uma chaleira, um eletrodoméstico)
Passo 1 — Instalar a biblioteca
Arduino IDE — Gestor de Bibliotecas (Library Manager)
Sketch → Include Library → Manage Libraries… → pesquise RbAmp → Instalar [Install]. Não há dependências. Após a instalação, os exemplos aparecem em File → Examples → RbAmp.
Arduino CLI
arduino-cli lib install RbAmp
PlatformIO
[env:esp32dev]
platform = espressif32
framework = arduino
lib_deps = rbamp/RbAmp@^1.6.1
Passo 2 — Ligação
⚠ 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.
Quatro fios de baixa tensão mais um DRDY opcional, e depois os terminais da rede elétrica:
| pino rbAmp | Anfitrião |
|---|---|
VCC |
+5 V (intervalo 4.5..5.5 V) |
GND |
GND |
SDA |
SDA I²C (UNO A4, ESP32 GPIO21, STM32duino PB7) |
SCL |
I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6) |
DRDY (opcional) |
salte-o no primeiro esboço; ver 04_hardware.md |
Terminais L, N |
o mesmo circuito que alimenta a carga que mede (lado da rede — ver o aviso acima) |
| Conector da CT | Ficha SCT-013 totalmente enfiada |
A alimentação tem de ser de 5 V. As linhas I²C funcionam em lógica de 3.3 V mas são tolerantes a 5 V — ligue-as diretamente a um Arduino UNO sem conversor de nível. A placa do módulo já tem resistências de pull-up de 4.7 kΩ integradas — para um único módulo não são necessárias externas.
A tabela completa de pinout de cada placa Arduino está em 04 · Cablagem.
A pinça SCT-013 encaixa em torno apenas do condutor de linha (L), com a seta no corpo da pinça a apontar no sentido da corrente em direção à carga. Para mais detalhes (secção "Sensor de corrente") veja o capítulo 04 · Ligação.
Passo 3 — Primeiro esboço (leitura RT)
Um esboço mínimo — verifique a comunicação sem configurar o sensor:
#include
#include
RbAmp dev(Wire, 0x50); // default address 0x50
void setup() {
Serial.begin(115200);
while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
Wire.setClock(50000); // ESP32/ESP8266: 50 kHz — required for retry discipline
#endif
while (!dev.begin()) {
Serial.print(F("rbAmp begin failed: "));
Serial.println(dev.errorString());
delay(1000);
}
// v1.3: auto-detect the variant via REG_HW_VARIANT — more accurate than
// the constructor topology hint (which is now a fallback for legacy fw).
uint8_t variant = static_cast(dev.readVariant());
Serial.print(F("Module ready, variant="));
Serial.println(variant); // 1=UI1, 4=I1, 5=I2, 6=I3
}
void loop() {
Serial.print(F("U=")); Serial.print(dev.readVoltage(), 1);
Serial.print(F("V I=")); Serial.print(dev.readCurrent(0), 3);
Serial.print(F("A P=")); Serial.print(dev.readPower(0), 1);
Serial.print(F("W PF=")); Serial.println(dev.readPowerFactor(0), 3);
delay(1000);
}
Carregue o esboço e abra o Monitor Série [Serial Monitor] a 115200 baud.
Saída esperada (sem calibração de sensor):
Module ready, variant=1
U=230.4V I=0.000A P=0.0W PF=nan
U=230.4V I=0.000A P=0.0W PF=nan
PF pode imprimir nan, 0.000 ou outro marcador enquanto a corrente for zero.
U mostra aproximadamente a tensão da rede (220-240 V em redes de 230 V) — o que significa que o módulo está corretamente ligado. I=0.000 A mesmo com a carga ligada é normal nesta fase: o módulo ainda não sabe que pinça de TC está a ser usada. Com I=0, o PF é matematicamente indefinido (depende do firmware — pode ser NaN, 0, ou um valor provisório) — a forma exata do valor não importa enquanto a corrente for zero. O passo seguinte corrige isto.
Passo 4 — Configuração do sensor de corrente
Se instalou uma pinça SCT-013 de encaixe separada, tem de indicar ao módulo a classe e o modelo do sensor. Sem isso, os coeficientes de calibração não são carregados e as leituras de corrente ficam a zero. Se o seu módulo veio com o TC já ligado, salte este passo.
Leia o modelo na etiqueta impressa na pinça (por exemplo SCT-013-030 → código 3, ver a tabela abaixo). Escolha a pinça de classificação mais pequena acima da sua maior corrente esperada. Uma pinça com classificação demasiado pequena dá leituras cortadas e baixas nos picos; uma com classificação muito superior dá leituras ruidosas e imprecisas em correntes pequenas.
Acrescente isto ao setup() depois de dev.begin(). A função loop() mantém-se igual à do Passo 3 — só o setup() muda:
void setup() {
Serial.begin(115200);
while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
Wire.setClock(50000); // ESP32/ESP8266: 50 kHz
#endif
while (!dev.begin()) { delay(500); }
// Step 1: sensor class. SCT-013 = the clip-on clamp you fitted.
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
Serial.print(F("setSensorClass failed: "));
Serial.println(dev.errorString());
while (true) { delay(1000); }
}
// Step 2: model. For example, SCT-013-030 for a household feed up to ~7 kW.
if (!dev.setCTModel(RbAmpCTModel::Sct013_030)) {
Serial.print(F("setCTModel failed: "));
Serial.println(dev.errorString());
while (true) { delay(1000); }
}
Serial.println(F("Ready."));
}
Códigos de modelo — o conjunto aceite é {1, 2, 3, 4, 5, 6, 7}:
code |
Modelo | Gama | Estado | Utilização típica |
|---|---|---|---|---|
| 1 | SCT-013-005 | 0..5 A | ✅ selecionável | Cargas pequenas, uma só tomada |
| 2 | SCT-013-010 | 0..10 A | ✅ selecionável | Frigorífico, máquina de lavar roupa |
| 3 | SCT-013-030 | 0..30 A | ✅ selecionável | Alimentação doméstica até ~7 kW |
| 4 | SCT-013-050 | 0..50 A | ✅ selecionável | Carregador de VE, aquecimento elétrico |
| 5 | SCT-013-100 | 0..100 A | ✅ selecionável | Entrada principal de serviço, alimentações de grande porte |
| 6 | SCT-013-020 | 0..20 A | ✅ selecionável | Alimentação média — eletrodomésticos de 3-4 kW |
| 7 | SCT-013-060 | 0..60 A | ✅ selecionável | Subcontador industrial |
Para mais sobre a seleção, ver 03 · Seleção do sensor de corrente.
Estas duas chamadas são feitas uma vez na primeira instalação — a escolha fica guardada na flash do módulo e sobrevive a um reinício. O tempo total é de cerca de 1.4 segundos (duas escritas na flash × ~700 ms cada). A biblioteca serializa internamente as duas chamadas — cada uma bloqueia até a escrita na flash terminar, pelo que não precisa de acrescentar um delay() entre elas: a segunda chamada espera pela sua própria vez até a primeira libertar.
Nas execuções seguintes do esboço pode saltar setSensorClass() e setCTModel() (o módulo recorda). Mas também não faz mal — uma chamada repetida com o mesmo valor reescreve o mesmo byte.
Depois de reiniciar o esboço, deve aparecer o valor de corrente correto:
Ready.
U=230.4V I=0.523A P=119.8W PF=+0.987
Passo 5 — Contabilidade de energia (Wh)
O módulo devolve apenas grandezas instantâneas mais a potência média ao longo de um período. A própria biblioteca calcula os Wh a partir do relógio de parede do mestre:
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
onde master_dt_s é o número de segundos entre duas chamadas readPeriodSnapshot() bem-sucedidas.
Um modelo mínimo de contabilização periódica (uma vez por minuto):
void setup() {
Serial.begin(115200);
while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
Wire.setClock(50000); // ESP32/ESP8266: 50 kHz
#endif
while (!dev.begin()) { delay(500); }
dev.setSensorClass(RbAmpSensorClass::Sct013);
dev.setCTModel(RbAmpCTModel::Sct013_030);
Serial.println(F("Period meter started; the first line covers only the time since begin() — ignore it..."));
}
void loop() {
RbAmpPeriodSnapshot snap;
if (!dev.readPeriodSnapshot(snap)) {
Serial.print(F("snapshot error: "));
Serial.println(dev.errorString());
delay(60000);
return;
}
Serial.print(F("avg P for period: ")); Serial.print(snap.avg_p[0], 2);
Serial.print(F(" W accumulated: ")); Serial.print(dev.energy().wh(0), 4);
Serial.print(F(" Wh dt=")); Serial.print(snap.master_dt_ms);
Serial.println(F(" ms"));
delay(60000); // the 60-second period sits at the END of loop — the first
// snapshot is taken right after setup() and covers only the
// seconds since begin(); full periods follow
}
Após o Passo 4, setSensorClass() e setCTModel() já correram uma vez e ficam guardados na flash do módulo; no modelo acima estão lá para as repetições do esboço — o módulo ignora uma chamada repetida com o mesmo valor. O tratamento de erros foi omitido por brevidade — adicione guardas if (!...) se quiser apanhar as raras falhas de comunicação no arranque.
O que readPeriodSnapshot() faz por baixo:
- Envia ao módulo um comando de instantâneo de período.
- Aguarda 50 ms enquanto o módulo prepara o instantâneo.
- Verifica o flag de pronto; lê a potência média/pico.
- Atualiza o contador interno de Wh:
+= avg_p × master_dt_s / 3600.
O begin() já executa um primeiro instantâneo que a biblioteca descarta. O primeiro readPeriodSnapshot() no seu esboço cobre, por isso, apenas o tempo desde o begin() (alguns segundos, ver dt= na saída): ignore essa primeira linha e aguarde um período completo. A partir da segunda chamada, cada linha cobre um período completo.
Saída esperada:
avg P for period: 119.90 W accumulated: 0.1332 Wh dt=4000 ms <- short first period, ignore
avg P for period: 120.18 W accumulated: 2.1368 Wh dt=60012 ms
avg P for period: 120.21 W accumulated: 4.1405 Wh dt=60005 ms
...
Vários módulos
Para vários módulos num mesmo barramento (alimentação principal + subcargas) use RbAmpFleet. O exemplo completo está em 06 · Exemplos, cenário 1; as regras de ligação para um barramento multimódulo estão em 04 · Ligação.
Próximos passos
- 01 · Visão geral — o que é o rbAmp e o que a biblioteca faz
- 02 · Níveis dos módulos — qual nível serve cada tarefa
-
06 · Exemplos — cenários de trabalho: rede + N cargas secundárias (o cânone dos 80 %), fluxo de provisionamento, TC misto multicanal, sincronização GC da frota, MQTT, deep sleep
-
07 · Integrações DIY — Home Assistant / Node-RED / OpenHAB
-
08 · Integrações na cloud — AWS IoT / Azure / GCP / InfluxDB
-
09 · Referência da API — a API pública completa (incluindo
RbAmpFleet+ Multicanal + Modelo de erros v1.3 + Identidade e provisionamento) -
10 · Resolução de problemas — quando algo não funciona (mitigação em três camadas para bloqueios do i2c, modos de falha de conflito / bloqueio / falha de provisionamento da frota)
Fonte e problemas: rb-amp/rbamp-arduino · esta página no repositório: docs/05_quickstart.md (v1.6.2)