Overview

📦 GitHub: rb-amp/rbamp-esp-idf — source, examples, releases (v1.2.0).
Install: idf.py add-dependency "rbamp/rbamp^1.2"

What rbAmp is

rbAmp is a compact hardware module for precision measurement of AC-mains parameters over the I²C interface. It is built around a Cortex M0+ microcontroller with an integrated isolated analog front end and factory calibration stored in flash.

From an integrator's point of view, the module behaves like a standard I²C slave: apply power, open the bus with i2c_new_master_bus(), create a handle with rbamp_new() — and you get ready-to-use values in physical units through the rbamp_read_*() functions. No master-side signal processing is required.

What rbAmp measures

The RT active-power value P is always signed on every module tier (negative means export to the grid). The behavior of the period-averaged value (avg_p[ch] in rbamp_period_snapshot_t) depends on the module tier — see the "Module tiers" section below and 02_tiers.md.

Connection

The module connects to the master with four wires on the LV side. The mains side is already routed inside the enclosure and is galvanically isolated.

The default address is 0x50 (7-bit, changeable in the 0x08..0x77 range), with a recommended speed of 50 kHz on ESP32 (see the section on retry + sanity discipline below). The cold start until the first valid measurement takes ~250 ms.

The full rules (bus length, pull-up recommendations on a multi-module bus, wiring diagrams for the various ESP32 targets) are in chapter 04 · Hardware connection.

Module tiers (quick cheat sheet)

In the current firmware (v1.2) only the BASIC tier is implemented — one-directional (consumption-only) metering following the logic of a classic mechanical meter:

Details are in chapter 02 · Module tiers. At the component level the same rbamp_handle_t handle is used regardless of tier; the differences show up in the values the module returns.

Bidirectional metering on BASIC: rbamp_energy_wh(dev, ch) on the BASIC tier reports consumption only. If you need to account for export separately, sample the RT power with rbamp_read_power(dev, 0, &p) at ~5 Hz and split the positive and negative samples into two accumulator variables yourself. See the example in 06_examples.md (the BidirectionalEnergy scenario).

What this component does

Its main job is to hide the protocol exchange and relieve the user application of the chore of dealing with registers, byte order, and the post-command settle times. In addition, the component computes energy (Wh) — the module returns only the period-averaged power, and the master performs the integration using esp_timer_get_time().

Without the component (direct access via i2c_master_transmit_receive)

// Read U_RMS — collect 4 bytes over 4 transactions
// (SPEC §6 — no auto-increment).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
    .device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);
uint8_t buf[4] = { 0 };
for (int i = 0; i < 4; i++) {
    uint8_t reg = 0x86 + i;
    if (i2c_master_transmit_receive(slave, ®, 1, &buf[i], 1,
                                    /*xfer_timeout_ms=*/100) != ESP_OK) {
        return;   // handle the error
    }
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));

With the component

float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));

Reading a period — without the component

// Latch + 50 ms settle + ready-flag check + assembling the 4 avg_p bytes
uint8_t latch_cmd[2] = { 0x01, 0x27 };   // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));   // settle
uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
    // the snapshot is stale — t_latch_us must STILL be recorded,
    // otherwise the next snapshot will count Wh over two periods
    return;
}
// ...read the 4 avg_p bytes, assemble the float, integrate Wh:
//   double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
//   E_Wh += avg_p * dt_s / 3600.0;

Reading a period — with the component

rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
    // snap.avg_p[0] is filled in,
    // rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
    // master_dt_ms is accounted for and saved for the next cycle.
}

Internally the component guarantees:

• A 50 ms settle after CMD_LATCH_PERIOD (configurable through the settle_ms parameter), and a correct snapshot read (an atomic latch on the module side).
• A check of the REG_V03_PERIOD_VALID flag before reading (the snap.valid field).
• Time-stamping against the master clock even on a stale snapshot (protects against double-counting Wh on the next period).
• Per-channel Wh accumulation with double precision (the double type inside the handle).
• Automatic loading of calibration coefficients when the current sensor is selected via rbamp_set_sensor_class() + rbamp_set_ct_model() — the user does not need to know about the internal calibration registers.

When to use the component, when to access the bus directly

For all typical tasks in the first rows, the component is the right fit.

Architecture

Logging and Kconfig

Unlike the Arduino library, where the log stream is configured at runtime (setLogStream(&Serial)), here the standard ESP-IDF pattern is used: the component logs under the "rbamp" tag via esp_log. The log level is compiled in through the Kconfig choice CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, INFO by default). At NONE, log strings are removed from the binary entirely.

The runtime filter also works (via esp_log_level_set("rbamp", ...)), but it is capped from above by the compile-time level.

Six CONFIG_RBAMP_* symbols are available in idf.py menuconfig → Component config → rbAmp client:

For more details, see 09 · API reference, the "Compile-time configuration" section.

Interaction diagrams

The rbamp_begin() flow

The first latch is a primer (the module returns what has been accumulated since power-up, which is unsuitable for tariff metering). The component itself records that this snapshot must be discarded — the user code never sees it.

The rbamp_read_period_snapshot(dev, &snap, 50, false) flow

The atomic latch on the module side guarantees that every ADC micro-sample within a period lands in exactly one snapshot — with no duplication and no losses at period boundaries.

Mapping to the direct register API

A table for those migrating from their own direct-access code:

What's next

• 02 · Module tiers — which tier suits which task
• 04 · Hardware connection — pull-ups, bus length, ESP32-family pin-out
• 05 · Quickstart — your first working project
• 06 · Examples — a walkthrough of the ready-made IDF projects
• 09 · API reference — every public function
• 10 · Troubleshooting — when something doesn't work

Contents | Tier Support →

Source & issues: rb-amp/rbamp-esp-idf · this page in the repo: docs/01_overview.md