API Reference

Formal reference for the rbAmp I2C register interface. This chapter is the authoritative specification: every register, every command, every error code, with size, access, units, default value, tier availability, and operational dependencies.

For prose-style explanations of what these registers mean and when to use them, see the preceding chapters. This chapter is the machine-readable contract.

Table of contents

• 1. Bus protocol
• 2. Tier availability
• 3. Conventions
• 4. Register map
• 4.1 Control & status (0x00–0x07)
• 4.2 Diagnostic LUT view (0x08–0x0F)
• 4.3 Mains info (0x20–0x23)
• 4.4 I2C configuration (0x30)
• 4.5 Current-sensor legacy block (0x54–0x7D)
• 4.6 Charge accumulator (0x7E–0x85, legacy)
• 4.7 Real-time measurement results (0x86–0xCF)
• 4.8 Reactive power (0xD0–0xDB)
• 4.9 Period snapshot (0xDC–0xEF)
• 4.10 Bidirectional period accumulator (STANDARD / PRO)
• 4.11 Noise floor (0xE4–0xEB)
• 4.12 Gain calibration (0xF0–0xFF)
• 5. Commands
• 6. Error codes
• 7. Operation sequences
• 8. Dependency summary

1. Bus protocol

Reading a 4-byte float (master pseudo-code)

uint8_t buf[4];
for (int i = 0; i < 4; i++) {
    buf[i] = i2c_read_byte(addr, reg + i);    // explicit register address each time
}
float value;
memcpy(&value, buf, 4);

Reading a multi-byte integer

uint8_t buf[4];
for (int i = 0; i < 4; i++) buf[i] = i2c_read_byte(addr, reg + i);
uint32_t value = (uint32_t)buf[0] | (uint32_t)buf[1] << 8
               | (uint32_t)buf[2] << 16 | (uint32_t)buf[3] << 24;

2. Tier availability

rbAmp ships in three product tiers — each tier is a complete combination of hardware revision and firmware:

Register availability matrix

The exact register addresses for the bidirectional PERIOD_AVG_P_NEG[0..2] and the PRO-only extended diagnostics block are documented in the SKU datasheet of the STANDARD / PRO product. They are stable within each tier but tier-specific in placement.

Bidirectional registers — runtime detection

Master code that targets all tiers should:

1. Probe a known STANDARD/PRO-only register with a 1-byte read.
2. If it returns NACK, the module is BASIC tier — disable export-metering features.
3. If it returns a value, the module supports bidirectional metering — enable both consumption and export accumulators.

3. Conventions

Access notation

• R — read-only (writes return ERR_PARAM)
• W — write-only (reads return implementation detail; do not rely on the value)
• RW — read-write

Size and type

• u8 — unsigned 8-bit
• u16 LE — unsigned 16-bit, low byte at lower address
• u32 LE — unsigned 32-bit, low byte at lower address
• i8 — signed 8-bit (two's complement)
• f32 LE — IEEE-754 single-precision float, low byte at lower address

Persistence

• RAM — value is lost on power cycle
• Flash — value is persisted in on-chip flash, restored at boot
• Flash (via SAVE_GAINS) — value lives in RAM until the master issues CMD_SAVE_GAINS, which writes the entire parameter block to flash

Dependencies

Marked in the "Depends on" column for each register where applicable: - DATA_VALID — master must wait (0xCE & 0x01) == 1 after boot before reading - PERIOD_VALID — master must read (0x07 & 0x01) == 1 after CMD_LATCH_PERIOD before trusting the snapshot - CMD_LATCH_PERIOD — register is updated only after a latch command - CMD_SAVE_GAINS — write to register is non-persistent until SAVE_GAINS is issued

4. Register map

Reading the tables. Each row has two lines in the Register column. The first line shows the address range and the canonical register name. The second line is a compact metadata strip with these fields (separated by ·):

• Access — READ, WRITE, or READ/WRITE.
• Type — the storage type (which also implies size): u8 = 1 byte, u16 LE = 2 bytes little-endian, u32 LE = 4 bytes LE, i8 = 1 byte signed, f32 LE = 4-byte IEEE-754 float LE. See 3. Conventions.
• Tier — which product tiers / variants expose the register: All = every SKU and tier; UI* = voltage-equipped variants only (UI1, UI2, UI3); UI2 / UI3 = variant-specific; STANDARD / PRO = bidirectional tiers only.
• Unit — physical unit when applicable (V, A, W, VAR, Hz, ms, ADC counts, etc.).
• Sign — ± if the value is signed (P, PF, Q); ≥ 0 if always non-negative.
• Default — the factory-default value for READ/WRITE registers, where one applies.

4.1 Control & status (0x00–0x07)

CT model codes (REG_CT_MODEL, 0x05)

Writing the code updates RAM immediately; persistence requires CMD_SAVE_GAINS (0x26).

4.2 Diagnostic LUT view (0x08–0x0F)

These registers expose ADC linearization-LUT status for diagnostic purposes. Typical user code does not read them; production-quality firmware always sets them correctly at boot.

4.3 Mains info (0x20–0x23)

4.4 I2C configuration (0x30)

To change the bus address:

1. Write the new address to 0x30.
2. Issue CMD_SAVE_GAINS (0x26) to persist.
3. Wait ≥ 700 ms for the flash write.
4. Issue CMD_RESET (0x01) or power-cycle.
5. Communicate with the module on the new address.

4.5 Current-sensor legacy block (0x54–0x7D)

These registers implement the legacy current-sensor model (v0.2). Modern integrations use the V03 block starting at 0x86. The legacy block is kept for backward compatibility — typical user code can ignore it.

4.6 Charge accumulator (0x7E–0x85, legacy)

Volatile (RAM only) Coulomb counter for current-only modules. Cleared on power cycle and by CMD_CHARGE_RESET (0x05).

Volume sample: at 10 A continuous, Q increments by 10 000 (0.1 mA·h) every 200 ms — i.e. 5 (mA·h) per second. The u32 maximum (4 294 967 295 × 0.1 mA·h ≈ 429 496 Ah) covers > 10 years of continuous 5 A operation.

The charge accumulator is not the same as the period-snapshot energy primitive. It is a current-time integral (Ampere-hours), not an energy integral (Watt-hours). Use it on I-only modules where the master has no voltage sensor; for energy use the period snapshot at 0xDC..0xEF.

4.7 Real-time measurement results (0x86–0xCF)

All values are float32 little-endian unless noted. Refreshed approximately every 200 ms by the firmware after each RT window. The whole block is updated atomically inside the publishing ISR; reading any subset after DATA_VALID = 1 returns coherent values.

Voltage

Currents

On variants with fewer channels than the SKU's maximum, unsupported channel registers return 0.0f rather than NACK.

Power (active)

Power factor

Period diagnostic / per-channel period averages

On BASIC product tier, PERIOD_AVG_P_W[ch] is clamped to ≥ 0 — the per-window accumulator drops negative samples. On STANDARD / PRO it represents the consumption side of the bidirectional accumulator.

4.8 Reactive power (0xD0–0xDB)

4.9 Period snapshot (0xDC–0xEF)

The master-side energy primitive. Updated only by CMD_LATCH_PERIOD (0x27). Each latch atomically copies the live accumulator into this snapshot and resets the live accumulator to zero — the snapshot reflects the period that just ended.

The address range 0xE4..0xEB interleaves with the noise-floor registers — see 4.11.

Master-side energy formula

E_Wh[ch] = PERIOD_AVG_P_W[ch] × master_dt_s / 3600

where master_dt_s is the wall-clock elapsed between two successive CMD_LATCH_PERIOD commands, measured by the master.

4.10 Bidirectional period accumulator (STANDARD / PRO)

STANDARD / PRO tiers only. Not present on BASIC modules — these registers NACK on BASIC.

The numeric register addresses for PERIOD_AVG_P_NEG_W[0..2] are SKU-specific and documented in the STANDARD / PRO product datasheet. They are stable within each tier.

Master code that wants tier-portable bidirectional support should:

1. Probe a candidate PERIOD_AVG_P_NEG_W address with a 1-byte read.
2. On NACK, fall back to RT-based bidirectional integration on the master side (see chapter 10, example 5).
3. On success, use the SKU-documented address set.

4.11 Noise floor (0xE4–0xEB)

Quadrature noise subtraction: rms_corrected = √(rms_raw² − NF²). The defaults are calibrated at the factory; user overrides are rarely needed.

4.12 Gain calibration (0xF0–0xFF)

Applied as a final multiplier in Sensor_V03_Commit() after the RMS/power computation. Writing all 4 bytes of a gain takes effect immediately in RAM; persistence requires CMD_SAVE_GAINS.

Safe range: 0.5..2.0. Values outside this range almost certainly indicate a setup error and should not be written.

5. Commands

Write a command code to REG_COMMAND (0x01). The firmware processes the command within a few milliseconds (see per-command latency below) and stores any resulting error in REG_ERROR.

Other codes return ERR_PARAM in REG_ERROR.

General Call (broadcast)

Sending a command to I2C address 0x00 (general call) reaches all slaves simultaneously. rbAmp accepts a subset of commands on general call — currently CMD_LATCH_PERIOD and CMD_RESET. Address-specific commands (e.g. CMD_SAVE_GAINS) are ignored on general call.

Wire-level example:

START | 0x00 W | 0x01 | 0x27 | STOP    -> all modules latch their snapshot

6. Error codes

Returned from REG_ERROR (0x02). Read-only; cleared only by a reset (CMD_RESET or power-cycle).

Reserved encoding: any value with bit 7 = 1 indicates an error. Codes 0x01..0xF9 are reserved for future use.

7. Operation sequences

7.1 Boot smoke test

1. Apply power.
2. Wait 300 ms.
3. Read REG_VERSION (0x03)  — expect non-zero firmware version byte.
4. Read REG_DATA_VALID (0xCE), bit0  — wait until == 1.
5. Read REG_ERROR (0x02)   — expect 0x00 (or a known non-fatal code).
6. Read RT registers as needed.

7.2 Reading a real-time snapshot

1. (Optional) Wait for DRDY falling edge for tight synchronisation.
2. Read U_RMS    (4 bytes from 0x86)
3. Read I0_RMS   (4 bytes from 0x8E)
4. Read P0_REAL  (4 bytes from 0xA6)
5. Read PF0      (4 bytes from 0xB2)
6. (Optional) Read AC_FREQ (1 byte at 0x20)

7.3 Period metering — continuous polling

Master setup:
1. Write CMD_LATCH_PERIOD (0x27) to REG_COMMAND (0x01)  -- primer; discard result
2. Record t_prev = master_clock()
For each measurement period:
3. Wait the desired interval (e.g. 60 s)
4. Write CMD_LATCH_PERIOD
5. Record t_now = master_clock()
6. Wait 50 ms (let firmware finalise the snapshot)
7. Read REG_V03_PERIOD_VALID (0x07), bit0
       == 0  -> see retry pattern below
       == 1  -> continue
8. Read PERIOD_AVG_P_W[0] (4 bytes from 0xDC)
9. Compute E_Wh = avg_p × (t_now - t_prev) / 3600
10. t_prev = t_now

Retry pattern when PERIOD_VALID == 0:

Wait 250 ms        -- let at least one RT window complete
Write CMD_LATCH_PERIOD
Wait 50 ms
Read PERIOD_VALID
if still 0:
    log warning, reset t_prev = master_clock(), skip this period

7.4 Multi-module synchronous latch

1. General Call latch: START | 0x00 W | 0x01 | 0x27 | STOP
2. Record t_now
3. Wait 50 ms
4. For each module addr in your list:
     read PERIOD_VALID (0x07) on addr
     if valid:
         read PERIOD_AVG_P_W[0] (0xDC) on addr
         E_Wh[addr] = avg_p × (t_now - t_prev[addr]) / 3600
         t_prev[addr] = t_now

7.5 Change CT model (plug-in CT modules)

1. Write new model code to REG_CT_MODEL (0x05)
   e.g. rb_write_u8(addr, 0x05, 0x03)   -- SCT-013-030
2. Write CMD_SAVE_GAINS (0x26) to REG_COMMAND (0x01)
3. Wait 700 ms
4. (Optional) Read REG_CT_MODEL to verify

7.6 Change I2C address

1. Connect only the target module to the bus (current address: old_addr)
2. Write new_addr to REG_I2C_ADDRESS (0x30) on old_addr
3. Wait 10 ms
4. Write CMD_SAVE_GAINS (0x26) on old_addr
5. Wait 700 ms
6. Write CMD_RESET (0x01) on old_addr
7. Wait 300 ms
8. The module now responds on new_addr; verify with a read of REG_VERSION (0x03)
9. Physically mark the module with its new address

7.7 Gain calibration

1. Connect a known reference load (e.g. 1000 W resistive heater)
2. Read live P0_REAL several times (0xA6); average over ~5 s -> p_measured
3. Read current I0_GAIN as float (0xF4..0xF7) -> gain_now
4. Compute gain_new = gain_now × (P_reference / p_measured)
5. Sanity check: 0.5 ≤ gain_new ≤ 2.0   (otherwise abort)
6. Write gain_new as 4 bytes (LE) to 0xF4..0xF7
7. Write CMD_SAVE_GAINS (0x26)
8. Wait 700 ms
9. Verify by reading P0_REAL again — should match P_reference within calibration tolerance

7.8 Factory reset

1. Write CMD_FACTORY_RESET (0xAA) to REG_COMMAND (0x01)
2. Wait 1 s for the module to wipe flash and reboot
3. Wait an additional 300 ms for boot
4. Read REG_VERSION (0x03) to confirm the module is back online
5. Reconfigure as needed (address, CT model, gains)

8. Dependency summary

A register's value is meaningful only when its dependencies are satisfied.

Initialization order

For a master driver that brings up a fresh installation:

1. I2C bus init  (set frequency, configure SDA/SCL)
2. Wait 250 ms for module power-on
3. Probe address (default 0x50); if not present, scan range 0x08..0x77
4. Read REG_VERSION (0x03)
5. Poll REG_DATA_VALID (0xCE) bit 0 until 1 (timeout 2 s)
6. Read REG_ERROR (0x02); log if non-zero
7. (One-time setup, if applicable):
   - Set CT model:  write 0x05 + CMD_SAVE_GAINS
   - Set I2C addr:  write 0x30 + CMD_SAVE_GAINS + CMD_RESET
8. (Optional) Detect variant:
   - Probe 0xC2 (UI2/UI3 marker)
   - Read U_RMS (0x86): non-zero => UI*, ≈0 => I-only
9. (Optional) Detect tier:
   - Probe a STANDARD/PRO-only address; NACK => BASIC
10. Issue primer CMD_LATCH_PERIOD; discard the result
11. Start the main read loop

See also

• Overview — what rbAmp does and tier semantics
• Hardware Connection — pinout, wiring, CT installation
• Initialization — bring-up examples in C and Arduino
• Real-time Polling — RT register usage with code
• Period Metering — latch semantics, energy formula
• Arduino Examples — reference sketches that exercise this API
• Arduino Library — Overview — high-level wrapper if you prefer a RbAmp class to raw registers
• Troubleshooting — error code remediation