Passa al contenuto

01 · Overview

rbAmp signal chain: sensor → module → I²C → master → cloud / Home Assistant


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 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: you create RbAmp(bus, 0x50), call dev.begin(), and get ready-to-use values through properties / methods. The same source runs on MicroPython (with machine.I2C) and CPython (with smbus2) — the backend is selected automatically from the type of the bus object.


Terms used in these docs

  • Module line — BASIC or STANDARD (STD): the product line of the module (see 02).
  • Variant — UI1, UI2, UI3, I1, I2, I3 (and UI5/UI7): how many current channels, and whether the module has a voltage input.
  • Firmware version / module image version — the software inside the module; some STD calls need a recent enough image.
  • RT reading — an instant reading (voltage, current, power), refreshed by the module every 100 ms.
  • Period / snapshot — a snapshot freezes the totals of the period so far and starts the next one; a period snapshot is the frozen result (average power per channel).
  • Stale snapshot — the module had no fresh snapshot ready; the library raises RbAmpStaleError and the next good snapshot covers the whole interval.
  • Primer — the first snapshot taken by begin(); it discards what accumulated since power-up.
  • GC (General Call) — one broadcast I²C frame that makes several modules take their snapshot at the same instant.
  • DRDY — optional pin that pulses every ~100 ms when new RT data is ready.

One module or many

One module or many: start with one RbAmp; use RbAmpFleet for several. The rbamp Python package works with a single module and also with a group of modules on a single I²C bus. The canonical multi-module scenario is one master module at the mains feed plus N modules on individual loads, all on one bus, driven by a single ESP32 / RPi / SBC. The library provides the RbAmpFleet class — a single object through which you scan the bus, poll all modules in one call, get total power and the "feed − Σ(consumers)" balance, catch errors on each module, and, when needed, synchronize period snapshots with a broadcast command.

Multi-channel modules are also supported — the current-only I2 / I3 (two or three CTs) and the voltage-equipped UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 current channels, with power, PF and Wh per channel). Each channel has its own sensor model. This is typical for a sub-panel, where a single installation point monitors several feeders.

Working with a single module is the minimal case of the same library: the RbAmp class is the building block on which RbAmpFleet is layered. If you have one module on the bus, you use that same handle directly — the fleet API is not needed.


The 80% scenario — mains + N sub-loads

One module on the mains feed and one module per sub-load share an I²C bus with the master, which polls them all with a single fleet call.

  • 1 module at the feed (mains) — total consumption and grid quality.
  • N modules on individual loads — per-channel metering.
  • Multi-channel modules fit this case too: one UI2 / UI3 / UI5 / UI7 (or I2 / I3) can meter several loads, each on its own channel — N modules do not have to mean N loads.
  • A single fleet.poll_all() call polls everything; the balance mains − Σ(sub_loads) shows "the rest" (background consumption, unmetered loads, leakage).
  • One shared master timestamp → correct Wh metering with no inter-module drift.

Important architectural detail. The I-variants (I1/I2/I3) measure current only — they have no voltage, active power, or PF. Active energy (Wh) and power are computed only on the UI-variants (which have a voltage front-end). In the canonical deployment, the "mains-meter" role (metering energy) is played by a single UI1 at the mains feed; the sub-meter role (per-load current detail) is played by I2/I3 modules (or by UI2 / UI3 / UI5 / UI7 when power and Wh are needed per load).

For details, see chapter 06 · Examples, scenario 1 ("Mains + N sub-loads — the 80% canon"). For the API, see chapter 09 · API Reference, section "Fleet manager".


What rbAmp measures

Quantity Python type Range
RMS voltage U_rms float, V 0…300 V
Peak voltage U_peak float, V 0…450 V
RMS current I_rms float, A depends on the selected sensor — see 03_sensor_selection.md
Peak current I_peak float, A depends on the selected sensor
Active power P (signed in RT) float, W depends on the selected sensor
Power factor PF float −1…+1
Mains frequency int, Hz 50 / 60 Hz (detected)
Period-averaged P float, W same as P

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


Wiring

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

Wire Purpose
VCC +5 V (4.5..5.5 V), current ~15 mA, peak ~25 mA
GND common with the host (required)
SDA, SCL I²C, 3.3 V logic, 5 V-tolerant. Built-in pull-ups 4.7 kΩ
DRDY optional, open-drain LOW ~10 µs every ~100 ms

The default address is 0x50 (7-bit, change range 0x08..0x77). The recommended speed for MicroPython on ESP32 is 50 kHz; for CPython through the kernel I²C it is usually 100 kHz (the NACK pattern does not appear through the Linux kernel API).

The full rules (bus length, pull-up recommendations on a multi-module bus, wiring diagrams for RPi / ESP32 / RP2040 / STM32) are in chapter 04 · Wiring.


Module lines (quick cheat sheet)

BASIC and STANDARD (STD) modules are shipping; STANDARD is supported by this library from 1.6.0.

BASIC is one-directional (consumption-only) metering following the logic of a classic mechanical meter:

Module line RT power dev.power[ch] Period accumulator snap.avg_p[ch] Package Wh counter
BASIC signed (negative = export to the grid, visible in real time) each 100 ms window of average P is clamped to max(P, 0) before being added to the period accumulator monotonic — consumption-only metering
STANDARD (STD) signed same calls as BASIC; the source is the module's energy counters or latch bank 0, chosen at begin(); energy is net (export subtracts) dev.energy integrates the period; the module's own totals: read_std_energy() (see chapter 02)

For details, see chapter 02 · Module lines. At the package level the same RbAmp class is used regardless of module line; the differences show up in the values the module returns.

Bidirectional metering on BASIC: dev.energy.wh(ch) on the BASIC module line gives consumption only. If you need to account for export separately, sample the RT power dev.power[0] (or dev.read_power(0)) at ~10 Hz and split the positive and negative samples into two accumulator variables yourself. For an example, see 06_examples.md, scenario "Bidirectional metering on the master side".


What this package does

The main job is to hide the protocol exchange and relieve user code of the routine of working with registers, byte order, and settle times after commands. In addition, the package computes energy (Wh) — the module returns only the period-averaged power, and the master does the integration using time.monotonic() / time.ticks_us().

Without the package (direct register access via smbus2)

python
import struct
from smbus2 import SMBus, i2c_msg
# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
    buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("<f", bytes(buf))[0]

With the package

python
from smbus2 import SMBus
from rbamp import RbAmp
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    u_rms = dev.voltage          # property (one call = one transaction)
    # or: u_rms = dev.read_voltage()

Reading a period — without the package

python
import time, struct
with SMBus(1) as bus:
    # Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
    bus.write_byte_data(0x50, 0x01, 0x27)   # REG_COMMAND, CMD_LATCH_PERIOD
    t_latch = time.monotonic()
    time.sleep(0.050)                        # settle
    bus.write_byte(0x50, 0x07)
    if bus.read_byte(0x50) & 0x01 == 0:
        # snapshot is stale — keep the previous t_prev_latch, so the next
        # good snapshot covers the full interval
        raise SystemExit("stale snapshot")
    # ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
    #   dt_s = time.monotonic() - t_prev_latch
    #   E_Wh += avg_p * dt_s / 3600

Reading a period — with the package

python
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    snap = dev.read_period_snapshot()        # snapshot + settle + valid + read + Wh tick
    print(snap.avg_p[0], "W")
    print(dev.energy.wh(0), "Wh")

Internally the package guarantees:

  • A 50 ms settle after CMD_LATCH_PERIOD, and a correct snapshot read.
  • A valid flag check before reading; on a stale snapshot it raises RbAmpStaleError.
  • Keeping the previous timestamp on a stale snapshot, so the next good snapshot covers the full interval and Wh stays exact.
  • Per-channel Wh accumulation in double precision (CPython — 64-bit float; MicroPython — depends on the build, see 04 · Wiring).
  • Automatic loading of calibration coefficients when the current sensor is selected via dev.set_sensor_class(cls) + dev.set_ct_model(code) — the user does not need to know about the internal calibration registers.

When to use the package, when to use direct bus access

Task Package Direct access via smbus2 / machine.I2C
Reading U / I / P / PF / frequency ✅ only for debugging on a logic analyzer
Per-period energy metering ✅ only if Wh are stored outside the package (e.g., in a DB on the master side)
Several modules on one bus ✅ (via sequential snapshot + shared settle) —
Bidirectional metering on BASIC ✅ (via RT reads — see 06_examples.md) alternative — your own RT-read loop
Async streaming via asyncio / uasyncio ✅ (async for snap in dev.stream_period()) hard — no built-in async wrapper
Porting to another platform n/a ✅ — see rbamp-docs (register map and protocol)

For all the typical tasks in the first rows, the package is the way to go.


Architecture

Where a Python script sits: script, rbamp package, I²C backend and the rbAmp module, with the I²C speed for each host.

text
┌─────────────────────────────────────────────────────┐
│  User code (.py)                                    │
│   from smbus2 import SMBus                          │
│   from rbamp import RbAmp, RbAmpSensorClass         │
│   with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:    │
│       # __enter__ calls dev.begin() itself;         │
│       # explicit begin() shown for transparency     │
│       dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│       dev.set_ct_model(3)                           │
│       snap = dev.read_period_snapshot()             │
│       dev.energy.wh(0)                              │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Public API of the RbAmp class (rbamp/__init__.py)  │
│   ┌─────────────────────────────────────────────┐   │
│   │ Lifecycle:      begin / probe / wait_ready  │   │
│   │ RT properties:  .voltage / .power[ch] /     │   │
│   │                 .current[ch] / .frequency   │   │
│   │ RT methods:     read_voltage / read_power / │   │
│   │                 read_all                    │   │
│   │ Period:         latch_period /              │   │
│   │                 read_period_snapshot        │   │
│   │ Async:          stream_period               │   │
│   │ Configuration:  set_sensor_class /          │   │
│   │                 set_ct_model                │   │
│   │ Diagnostics:    retry_exhaustion_count /    │   │
│   │                 sanity_reject_count         │   │
│   │ Exceptions:     RbAmpError → IOError /      │   │
│   │                 TimeoutError / StaleError / │   │
│   │                 ParamError / ModeError /    │   │
│   │                 VersionError                │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Backend selection (inside __init__):        │   │
│   │  bus.readfrom_mem  → MachineI2CBackend      │   │
│   │  bus.read_byte_data → SMBusBackend          │   │
│   │  duck-typed        → custom (FTDI / mocks)  │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Instance state:                             │   │
│   │  • RbAmpEnergy — Wh accumulator             │   │
│   │  • RbAmpSnapshot / RbAmpPeriodSnapshot      │   │
│   │  • Time of last snapshot (monotonic)           │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Backend — native I²C on the host platform:         │
│   smbus2 (CPython)  /  machine.I2C (MicroPython)    │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  rbAmp module at address 0x50                       │
│   • U / I / P / PF measurement pipeline (~100 ms)   │
│   • Period accumulator (atomic CMD_LATCH_PERIOD)    │
└─────────────────────────────────────────────────────┘

Exception hierarchy

Unlike the Arduino library (where errors are reported via lastError() + a return code) and the ESP-IDF component (where they are reported via esp_err_t), the Python package uses the classic Python pattern — an exception hierarchy.

Exception hierarchy of the rbamp package: every error derives from RbAmpError, which derives from OSError.

The standard Python pattern:

python
from rbamp import RbAmp, RbAmpStaleError, RbAmpError
try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
    continue
except RbAmpError as e:
    log.warning("rbAmp failure: %s", e)

Interaction diagrams

The dev.begin() flow

Sequence of bus transactions that begin() performs: read the version, detect the module line, send the primer snapshot, then return.

text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─dev.begin()►                     │                       │
  │             ├─read_u8(REG_VERSION)►                      │
  │             │                    ├──[0x50, 0x03]────────►│
  │             │                    │◄────────────────ACK───┤
  │             │                    ├──[read 1 byte]───────►│
  │             │                    │◄──────────────[0x04]──┤
  │             │◄─────── version_byte ─────┤                  │
  │             │                    │                       │
  │             ├─read_float_le(U_RMS)►(4 single-byte reads) │
  │             │  → 226.3 V         │                       │
  │             │  → has_voltage_hw = True                   │
  │             │                    │                       │
  │             ├─write_cmd(LATCH)──►│                       │
  │             │                    ├──[0x50, 0x01, 0x27]──►│
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │◄────self────┤  (or raises RbAmpIOError on failure)        │

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

The dev.read_period_snapshot() flow

Sequence of read_period_snapshot(): take the period snapshot, read the snapshot block, integrate energy on the master for BASIC or read on-device counters for STD.

text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─read_period_snapshot()►          │                       │
  │             ├─write_cmd(LATCH)──►│  t_now = time.monotonic()
  │             │                    │                       │
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │             ├─is_period_valid()─►│                       │
  │             │  → True            │                       │
  │             │                    │                       │
  │             ├─read_float_le(AVG_P0)►(4 reads)            │
  │             ├─read_float_le(MAX_P0)►(4 reads)            │
  │             ├─read_u32_le(LATCH_MS)►(4 reads)            │
  │             │                    │                       │
  │             │  dt = t_now − last_latch                    │
  │             │  energy.wh[ch] += avg_p[ch] × dt / 3600    │
  │             │  last_latch = t_now                         │
  │             │                    │                       │
  │◄─snap──────┤                    │                       │

The atomic snapshot on the module side guarantees that every measurement within a period lands in exactly one snapshot — no duplication, no losses at the period boundary.


Mapping to the direct register API

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

Direct API (smbus2 / machine.I2C) Package equivalent
Manual 4-byte read + struct.unpack dev.voltage (property) or dev.read_voltage()
Per-channel read_byte × 4 dev.power[ch] (_ChannelProxy) or dev.read_power(ch)
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) dev.latch_period(); time.sleep(0.05) (or directly dev.read_period_snapshot())
Checking read_byte(0x07) & 1 dev.is_period_valid() or the snap.valid field
Manual formula E_Wh += avg_p × dt / 3600 dev.energy.wh(0) — updated automatically
Manual current-sensor configuration via the direct register API dev.set_sensor_class(cls) + dev.set_ct_model(code) — factory presets are loaded automatically

What's next


Source & issues: rb-amp/rbamp-python · this page in the repo: docs/01_overview.md (v1.6.1)