02 · Module tiers

rbAmp ships in three product lineups: BASIC, STANDARD, and PRO. Each tier is a complete combination of a hardware revision and a firmware build, not just a flag in the firmware. Moving between tiers requires a physical module swap, not an upgrade.

The ESPHome component works with all three tiers the same way: the YAML schema is shared, only what data the module actually emits and which YAML keys make sense on each tier differs.

Tiers

BASIC — entry level

The analog front-end is optimized for cost and suits typical residential loads. The firmware performs unidirectional consumption metering: the average active power over a period cannot be negative — reverse segments inside the window are zeroed before integration. Behaviorally it resembles a classic mechanical disc meter.

• The energy_exported sensor exists in the YAML schema (for config compatibility), but on BASIC it always publishes 0.
• Typical applications: apartments without on-site generation, sub-metering of specific consumers (water heaters, motors, household appliances, HVAC).

STANDARD — bidirectional

An extended analog stack for precise bidirectional measurement. The firmware maintains two separate accumulators per period: one for consumption (positive segments), another for export (negative). The energy_exported sensor on this lineup carries a real signal.

• The bidirectional: true key on the rbamp: block enables reads of the export-energy register.
• NVS persistence works identically for both accumulators.
• Typical applications: homes with solar/wind generation, battery storage, V2G EV charging, any installation where import and export must be accounted separately.

PRO — premium

Low-noise analog front-end, tighter component tolerances. Additionally available on PRO:

• Extended diagnostics (peak demand windows, harmonic indicators, drift monitoring) — to be integrated into the YAML schema in a future component revision.
• SKUs with more channels (UI5 / UI7, I6 / I8).

Typical applications: sub-metering of commercial tenants, billing-grade installations, instrument-grade laboratories, energy-intensive industrial loads, service bureaus requiring audit-quality data.

Capability matrix

The base register block is identical on all tiers. STANDARD- and PRO-specific registers live in a separate range above the base. The component reads only what sensors are declared for — an undeclared register is never requested.

YAML keys per tier

bidirectional: (default false)

Enables the read branch for the export-energy register on every update() cycle.

rbamp:
  id: solar_meter
  address: 0x51
  bidirectional: true   # meaningful on STANDARD / PRO; no-op on BASIC

On BASIC the key is accepted by the schema without error, but energy_exported always yields 0. The component has no way to detect the tier at runtime (no tier register exists in current firmware) — the user sets the key for their own SKU.

The key is reserved for upcoming firmware revisions. The current build already accepts it in the schema and reserves energy_export_wh[3] slots in NVS, but the actual export register read will be wired up in a future component revision together with the final register layout.

sensor_class: — fixing the sensor family

rbamp:
  id: meter1
  sensor_class: SCT_013   # default SCT_013

Accepted on all tiers. On firmware v1.2+ the value is written to flash and becomes a precondition for writing the CT model: the module will refuse to write the model if the class is not set. On earlier firmware the value is accepted by the schema and will be applied automatically on a firmware upgrade — without any YAML changes.

Enum values: SCT_013 (the current family), WIRED_CT, BUILTIN_CT (reserved for future SKUs).

ct_model: / ct_models: — CT clamp model

One global profile for all channels:

rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Or an individual profile per channel (for UI3 with mixed clamps):

rbamp:
  id: meter_ui3
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]

Accepted on all tiers, mutually exclusive. On firmware v1.2+ the module automatically loads factory coefficients for the chosen model — no additional calibration steps required. On earlier firmware the value is stored as a model marker; full auto-loading of coefficients comes with a firmware upgrade.

More on model selection in Sensor Selection.

new_address: — one-shot I²C address provisioning

rbamp:
  id: meter1
  address: 0x50
  new_address: 0x51   # one-shot; remove after a successful boot

Accepted on all tiers. On current firmware (v1.3+), changing a module's I²C address needs no special mode, jumper, or factory tooling — you stage the new address, arm the change, and commit it (a two-phase, magic-armed sequence so an address can't change by accident). The module reboots at its new address. (On firmware older than v1.3 the address change was only possible while the module was in factory mode (a manufacturer operation); update to v1.3 or newer for the no-mode two-phase path.)

Execution flow within a single boot: the component polls the current address, writes the new address and saves it to flash, resets the module, verifies a response at the new address. After success, update YAML to address: 0x51 and remove new_address:. If the component finds that the old address is silent while the new one responds, it adapts automatically with a warning in the log (in case a previous boot already applied the change).

broadcast_latch: — synchronous latch for a multi-module bus

rbamp:
  - id: meter1
    broadcast_latch: true   # no-op on v1 firmware; safe for forward-compat

When true, the component sends the latch command to the I²C broadcast address — synchronizing the period snapshot across all modules on the bus in a single transaction. On v1 firmware the general-call is disabled — a write to the broadcast address is silently ignored. The component sees the firmware version and logs an ESP_LOGW warning, then falls back to a sequential latch for each module individually.

Skew between modules on a 50 kHz bus is on the order of ~540 µs × N, which is less than 0.003% of a 60-second period. On daily totals in HA this irregularity is invisible.

Leave the key in YAML when upgrading from v1 to v1.1 firmware — the warning will disappear and the component will switch to the real broadcast on its own.

topology: — topology hint

rbamp:
  id: meter1
  topology: SINGLE      # SINGLE / SPLIT_PHASE / THREE_PHASE

Accepted on all tiers. On current firmware the component derives the channel count itself from the declared sensor slots (if current_1 is declared — there are at least 2 channels). The key is cosmetic, it goes into the dump_config log line. It will become authoritative once the module publishes the topology through its own register in a future firmware revision.

drdy_pin: — optional data-ready interrupt

rbamp:
  id: meter1
  drdy_pin: GPIO15

Accepted on all tiers. Connects to the module's optional open-drain DRDY output. When declared, the component uses the pin as a hint that the instantaneous registers are fresh before reading them. With a typical update_interval: 60s the key can be omitted: the component skips instantaneous reads when the status register is not ready, independently of DRDY.

Requires a 10 kΩ pull-up on the master's GPIO to 3.3 V (the output is open-drain, with no internal pull-up on the module side). See Wiring.

Summary table — YAML key × tier

What next

• Sensor Selection — choosing a CT clamp and behavior of ct_model: / ct_models:
• Wiring — physical wiring, GPIO selection

Source & issues: rb-amp/rbamp-esphome · this page in the repo: docs/02_tiers.md