Перейти к содержимому

05 · Quickstart

A five-minute hello-world: install the library, wire up the module, select a sensor, take your first RT reading and your first per-period snapshot (Wh).

The details (pinout for a specific host, multi-module bus, choosing an SCT-013 by range) live in the neighboring chapters:

First reading in eight steps: wire, power on, scan for 0x50, begin(), optional sensor setup, read U, I, P, PF, sanity check, then energy.


What You'll Need

  • An rbAmp module (any tier, UI1 for simplicity)
  • An Arduino-compatible host — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • An SCT-013 clamp rated above your largest expected current (5A / 10A / 30A / 50A / 100A) — or the CT that came attached to your module
  • A 5 V supply to power the module (from the host's USB-5V or external)
  • An AC circuit to measure (a lamp, a kettle, a household appliance)

Step 1 — Install the Library

Arduino IDE — Library Manager

Sketch → Include Library → Manage Libraries… → search for RbAmp → Install. There are no dependencies. After installation the examples appear under File → Examples → RbAmp.

Arduino CLI

sh
arduino-cli lib install RbAmp

PlatformIO

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

Step 2 — Wiring

⚠ Mains voltage can kill. Disconnect and lock out the circuit before connecting the L/N terminals or fitting the clamp; have a qualified person do mains wiring and any work inside a panel. Clamp ONE conductor only (L) — never the whole cable (L+N cancel to ~0). Fuse the L tap per local rules.

Four low-voltage wires plus an optional DRDY, then the mains terminals:

rbAmp pin Host
VCC +5 V (range 4.5..5.5 V)
GND GND
SDA I²C SDA (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (optional) skip it for the first sketch; see 04_hardware.md
L, N terminals the same circuit that feeds the load you measure (mains side — see the warning above)
CT jack SCT-013 plug pushed fully in

Power must be 5 V. The I²C lines run on 3.3 V logic but are 5 V tolerant — connect them directly to an Arduino UNO with no level shifter. The module board already carries built-in 4.7 kΩ pull-up resistors — for a single module no external ones are needed.

The full pinout table for each Arduino host is in 04 · Wiring.

The SCT-013 clamp snaps around the line conductor (L) only, with the arrow on the clamp body pointing in the direction of current toward the load. For more detail (the "Current sensor" section) see chapter 04 · Wiring.

Mains-side connection: the CT clamp on the L wire only with the arrow toward the load, and the L/N voltage reference tap.


Step 3 — First Sketch (RT reading)

A minimal sketch — verify communication without configuring the sensor:

cpp
#include <Wire.h>
#include <RbAmp.h>
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<uint8_t>(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);
}

Upload the sketch and open the Serial Monitor at 115200 baud.

Expected output (with no sensor calibration):

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 may print nan, 0.000 or another placeholder while the current is zero.

U shows roughly the mains voltage (220-240 V on 230 V networks) — which means the module is connected correctly. I=0.000 A even with the load switched on is normal at this stage: the module does not yet know which CT clamp is in use. With I=0, PF is mathematically undefined (it depends on the firmware — it may be NaN, 0, or a placeholder) — the exact form of the value does not matter while the current is zero. The next step fixes this.


Step 4 — Current Sensor Configuration

If you fitted a separate SCT-013 clip-on clamp, you must tell the module the sensor class and model. Without that the calibration coefficients are not loaded and the current readings stay at zero. If your module came with its CT already attached, skip this step.

Read the model off the label printed on the clamp (for example SCT-013-030 → code 3, see the table below). Choose the smallest rated clamp above your largest expected current. A clamp rated too small gives clipped, too-low readings at peaks; one rated far too large gives noisy, inaccurate readings at small currents.

Add this to setup() after dev.begin(). The loop() function stays the same as in Step 3 — only setup() changes:

cpp
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."));
}

Model codes — the accepted set is {1, 2, 3, 4, 5, 6, 7}:

code Model Range Status Typical use
1 SCT-013-005 0..5 A ✅ selectable Small loads, a single outlet
2 SCT-013-010 0..10 A ✅ selectable Refrigerator, washing machine
3 SCT-013-030 0..30 A ✅ selectable Household feed up to ~7 kW
4 SCT-013-050 0..50 A ✅ selectable EV charger, electric heating
5 SCT-013-100 0..100 A ✅ selectable Main service entrance, large feeds
6 SCT-013-020 0..20 A ✅ selectable Medium feed — 3-4 kW appliances
7 SCT-013-060 0..60 A ✅ selectable Industrial sub-meter

For more on selection see 03 · Current Sensor Selection.

These two calls are made once at first installation — the choice is saved to the module's flash and survives a reset. The total time is about 1.4 seconds (two flash writes × ~700 ms each). The library serializes both calls internally — each one blocks until the flash write completes, so you don't need to add a delay() between them: the second call waits on its own until the first one releases.

On subsequent runs of the sketch you can skip setSensorClass() and setCTModel() (the module remembers). But there's no harm either — a repeat call with the same value rewrites the same byte.

After restarting the sketch the correct current value should appear:

text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

Step 5 — Energy Accounting (Wh)

The module returns only instantaneous quantities plus the average power over a period. The library itself computes the Wh from the master wall-clock:

text
E_Wh += avg_P × master_dt_s / 3600
        [W]     [seconds]     →  [Wh]

where master_dt_s is the number of seconds between two successful readPeriodSnapshot() calls.

A minimal periodic-accounting template (once per minute):

cpp
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
}

After Step 4, setSensorClass() and setCTModel() have already run once and are saved to the module's flash; in the template above they are there for re-runs of the sketch — the module ignores a repeat call with the same value. Error handling is omitted for brevity — add if (!...) guards if you want to catch the rare communication hiccups at startup.

What readPeriodSnapshot() does under the hood:

  1. Sends the module a period-snapshot command.
  2. Waits 50 ms while the module prepares the snapshot.
  3. Checks the ready flag; reads the average/peak power.
  4. Updates the internal Wh counter: += avg_p × master_dt_s / 3600.

begin() already performs a first snapshot that the library discards. The first readPeriodSnapshot() in your sketch therefore covers only the time since begin() (a few seconds, see dt= in the output): ignore that first line and wait for a full period. From the second call on, each line covers one full period.

Expected output:

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

Several modules

For several modules on one bus (mains feed + sub-loads) use RbAmpFleet. The full example is in 06 · Examples, scenario 1; wiring rules for a multi-module bus are in 04 · Wiring.


What's Next


Source & issues: rb-amp/rbamp-arduino · this page in the repo: docs/05_quickstart.md (v1.6.2)