rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub [Edit on GitHub]

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:

Primeira leitura em oito passos: ligação, alimentação, pesquisa de 0x50, begin(), configuração opcional do sensor, leitura de U, I, P, PF, verificação de sanidade e depois energia.

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

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

Passo 2 — Ligação

Segurança

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

Ligação do lado da rede: a pinça de TC apenas no fio L com a seta em direção à carga, e a derivação de referência de tensão L/N.

Passo 3 — Primeiro esboço (leitura RT)

Um esboço mínimo — verifique a comunicação sem configurar o sensor:

C++
#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):

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

Segurança

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:

C++
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.

Nota

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:

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

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

C++
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
}
Nota

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:

  1. Envia ao módulo um comando de instantâneo de período.
  2. Aguarda 50 ms enquanto o módulo prepara o instantâneo.
  3. Verifica o flag de pronto; lê a potência média/pico.
  4. 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:

Text
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


Fonte e problemas: rb-amp/rbamp-arduino · esta página no repositório: docs/05_quickstart.md (v1.6.2)