02 · Module Lines
What a Module Line Is
rbAmp modules come in two module lines: BASIC and STANDARD (STD). A module line is a complete bundle of a hardware revision and firmware, not a software flag. Moving between module lines requires a physical SKU change, not a firmware update.
From the package and user-code perspective: one RbAmp class serves
every module line, and the common readers (voltage, current, power,
power_factor, frequency) work on all of them. The module line is detected
automatically at begin(). STANDARD (STD) modules additionally expose the
STD-only calls (on-device energy and so on, see below); calling one of those
on a BASIC module raises RbAmpNotSupportedError.
Current State
BASIC and STANDARD modules are supported by this library (STANDARD from 1.6.0).
| Module line | Shipping |
|---|---|
| BASIC | ✅ yes |
| STANDARD (STD) | ✅ yes (supported by this library from 1.6.0) |
BASIC — Entry-Level Consumption-Metering Module Line
Hardware
A cost-optimized analog path suited to typical household loads. The module includes an isolated analog front-end, an on-board power regulator, and factory calibration in flash memory.
Firmware Behavior
The logic of a classic mechanical disc meter — the count only goes forward; export to the grid is not subtracted.
The three "layers" of active-power values behave differently:
| Signal | Meaning | Behavior on BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
instantaneous RT power, ~100 ms update | signed — a negative value is visible in real time (export) |
snap.avg_p[ch] (from dev.read_period_snapshot()) |
average power over the period | each 100 ms average-P window is clamped to max(P, 0) before being added to the period accumulator |
dev.energy.wh(ch) |
accumulated Wh by the package | monotonic — consumption only; export is not counted |
In other words: the user sees export in the RT reading, but it is not present in the package's Wh counter on BASIC.
Typical Applications
- Households without their own generation (no solar panels, wind turbines, battery systems)
- Submetering of purely consuming loads (water heaters, motors, home appliances)
- Building consumption monitoring where bidirectional metering is not required
Bidirectional Metering on BASIC (Master-Side)
If you need to track export to the grid separately on a BASIC module,
do it on the master side. The RT power dev.power[0] is
signed (or the equivalent method dev.read_power(0)), so:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
t_now = time.monotonic()
dt_s = t_now - t_prev
t_prev = t_now
try:
p = dev.read_power(0)
except RbAmpIOError:
continue
dwh = p * dt_s / 3600.0
if p >= 0.0:
consume_wh += dwh
else:
export_wh += -dwhOn MicroPython, replace time.monotonic() with time.ticks_ms() /
time.ticks_diff() (more accurate and cheap on RAM on embedded
platforms) and time.sleep(0.1) with time.sleep_ms(100). On
CPython, no changes.
A complete working example of the pattern is in 06_examples.md,
the "Master-side bidirectional metering" scenario, as well as the
source files examples_upy/07_bidirectional_energy.py
and examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — Shipping Module Line
STANDARD modules are a shipping module line that this library supports from
version 1.6.0. They use a different (16-bit) register map from BASIC; the
library hides the difference — the same RbAmp class, the same I²C wiring
and address, and the same common readers.
What the library adds on an STD module:
- On-device energy:
dev.read_std_energy()returns the module's own lifetime counters — active import / export / net and reactive energy, at Wh, mWh and µWh resolution, with per-channel figures.RbAmp.std_energy_delta(prev, now)gives the energy used between two readings and is safe across a power cut. You do not integrate power on the master for these counters. - Period metering:
read_period_snapshot()and the other period calls work as on BASIC.begin()picks the source — the module's energy counters (the period is the difference of two readings; no latch command is sent) or, on a module with latch banks only, latch bank 0. The energy is net (export subtracts). - Latch banks (modules that report them):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). - Multi-phase helpers:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(STD only; on BASIC, reactive power is not exposed by this library),dev.read_apparent(ch). - Starting current:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). - Full blocks:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
- Some STD calls need a recent enough module image (micro-unit energy
counters, voltage angles, starting current). If the module does not
provide one, the call raises
RbAmpNotSupportedError("not available"). - Use
dev.is_stdto branch in application code. - Sensor-class and CT-model configuration, reset and address change, the
identity registers, the error / event channel, the fleet helpers and
wait_ready()are BASIC only; on an STD module they raiseRbAmpNotSupportedError. - On-device energy, angle and starting-current features are validated on
CPython (
smbus2). The MicroPython 16-bit path is implemented but is not yet hardware-validated — prefer CPython for these features until a release note says otherwise.
Full signatures: 09 · API Reference.
How to Detect the Module Line at Runtime
In the current firmware there is no explicit "module line" register. Indirect indicators are available through handle properties:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_stdNote:
dev.is_stdtells you the module line (STD vs BASIC). The other indicators (firmware version, channel count, presence of a voltage sensor, variant) describe the module but do not identify the module line.dev.read_variant()is the BASIC variant byte; use the SKU label on the module enclosure as the source of truth for the product.
Where Module-Line-Dependent Places Are Marked in the Documentation
In the package text and canonical documentation, module-line-dependent features are marked explicitly, for example:
STD only — this call is not available on a BASIC module.
Or, conversely, BASIC-specific behavior:
BASIC: the
dev.energy.wh(ch)counter is monotonic — export to the grid is not counted. For bidirectional metering, see the "Master-side bidirectional metering" scenario in 06_examples.md, or use a STANDARD module, where the period energy is net anddev.read_std_energy()has separate import and export counters.
What's Next
- 03 · Current Sensor Selection — which SCT-013 for which task
- 04 · Wiring — hardware specifics for each host (RPi / ESP32 / RP2040 / STM32 / Pyboard)
- 06 · Examples — scenarios for BASIC, including master-side bidirectional metering
- 09 · API Reference — the full public API
Source & issues: rb-amp/rbamp-python · this page in the repo: docs/02_tiers.md (v1.6.1)