11 · Changelog
This chapter mirrors CHANGELOG.md
in the repository root. Public releases resume with version 1.7.2;
intermediate versions were released internally only.
1.7.3 — STD energy stays on the counters, 100 A and 50 A clamp models, locked-module message (2026-11-01)
Fixed
- STD modules that report both snapshot banks (capability bit 8) and on-device
energy counters (bit 13), such as module image 0x0001007E: energy and the
period calls now stay on the persisted counters. Before, such a module was
switched to host-integrated bank 0 without any sign. The snapshot-bank calls
(
rbamp_std_arm_banks,rbamp_std_latch,rbamp_std_read_latch) are a separate tool that depends on bit 8 only and work on these modules as before.rbamp_std_info_t.period_sourcereports the source actually used.
Added
- README: "STD line" section with the minimum component version for module image 0x0001007E and the snapshot-bank calls.
- Example
std_meterarms its own bank 1 on every module that reports latch banks, also when the energy comes from the counters. - Firmware name for BASIC
REG_VERSION0x0E:rbamp_basic_fw_name()returns "1.4.22" (all BASIC variants). - Sensor-model registry: clamp 2000:1 codes 11 (50 A) and 13 (100 A) are now characterized models (rated 50.0 A / 100.0 A, full scale 62.5 A / 116.5 A, peak 88.4 A / 164.7 A). Code 12 (80 A) stays for modules already bound to it.
Changed
rbamp_set_ct_model_ch_force()on a BASIC module of class 2 or 3 returnsESP_ERR_INVALID_STATEwith a log line naming the locked configuration when the module refuses the write (firmware 1.4.22 and later refuse class and model writes on a factory-paired module outside maintenance mode). Before, the refusal surfaced as a generic parameter error. The force path works on such a module in maintenance mode only.
1.7.2 — SCT-013 rating correction, resume after master downtime, one-transaction window reads (2026-10-21)
First public release since 1.5.0. It carries 1.6.0 – 1.7.2 together: the STD module line behind the same handle, the data-ready line, events, µWh energy and phase quantities, a channel count that follows the module (1, 2, 3, 5 or 7), the sensor-model registry with clip limits, one-transaction window reads, resume after a master outage, and the SCT-013 rating correction for current- line modules whose firmware keeps the 30 A calibration (firmware reporting the self-correction capability corrects itself). Hardware validation of this line was done on a host running ESP-IDF 5.4.1.
Added
- SCT-013-060 and -100 are accepted (they were refused client-side as reserved); sensor-model clip limits updated to measured values.
- SCT-013 rating switch: a current-sensor
module of class 1 is calibrated with the 30 A sensor, and firmware up to
1.4.19 keeps that calibration after the user binds another model. The
library now reads the gain the module applies at
rbamp_begin(), after a model write and after every detected module restart, and scales current, peak current, real power, period average power, the energy it integrates, the digest and the event thresholds to the selected model. Voltage and power factor are not scaled.rbamp_sct_correction()reports the outcome per channel (rbamp_sct_correction_t: status, model, scale, applied gain) andrbamp_sct_refresh()re-evaluates on demand. A gain still equal to the raw preset (model switched in this boot without a restart) triggers one CMD_RESET; an unexpected applied gain, an unknown model, or a raw preset that survives the reset leave the readings unscaled with a warning. A module that reports the self-correction capability (firmware 1.4.20 and later) corrects itself and gets scale 1 — detected by the capability, never by VERSION.CONFIG_RBAMP_SCT_RATING_CORRECTION(default on) turns the mechanism off. rbamp_begin_resume()—rbamp_begin()without the primer latch. A BASIC module keeps averaging until the next latch, so after a master reboot or outage the first consumed snapshot integrates over the module's own window and recovers the energy of the downtime. Later snapshots use the master clock as before. STD modules behave exactly as withrbamp_begin().rbamp_period_snapshot_t:module_window_ms(the module's own length of the latched window, 0 on STD; the module counts commits of 100 ms on current firmware and 200 ms on pre-v1.2 firmware — the library tells which from the snapshot itself and reports it inmodule_commit_ms),module_uptime_s,window_from_boot(the window started at the module's boot: a restart, or the first latch since boot) andwindow_long(over 6 h, where the module's average loses precision). On the first snapshot afterrbamp_begin_resume(),module_restarted=window_from_boot.rbamp_read_uptime_s()— seconds since the module booted (BASIC and STD). Reads 0 on BASIC firmware that does not publish it; thenwindow_from_bootstays false.rbamp_read_digest()— one window of a BASIC module in a single transaction: status, window sequence, and the chosen fields (current, voltage, signed real power in whole watts, power factor) for channels 0-2. Made for reading every published window on the data-ready line.rbamp_set_digest_fields()chooses the fields; the library writes the choice to the module and writes it again after a detected module restart. Needs BASIC firmware with the digest capability; not available on STD.rbamp_basic_fw_name()— the firmware release name for a BASIC version byte ("1.4.19" for 0x0B, and so on).rbamp_read_sensor_class()— the module's current sensor class.rbamp_sensor_model_limits()— a sensor model's rated RMS current, the RMS current at which a sine starts to clip, and the instantaneous clip ceiling, in A, from the generated model registry (0 when not known).rbamp_sensor_model_rated_a()is the rated-current shorthand; note the rating can differ from the amps in the model's name.- Generated sensor-model registry refreshed with those limits.
rbamp_set_ct_model_ch_force()— service path that sets a channel's model regardless of the module's class and current model. It replaces the calibration the unit carries for that channel with the model's generic preset; follow it with a calibration.
Changed
rbamp_set_ct_model(),rbamp_set_ct_model_ch()andrbamp_configure_channels()on a class-1 module without the self-correction capability (firmware up to 1.4.19) end with a module restart (CMD_RESET, the same UID verified, about a second): the only way the module returns to its calibrated gain after a model write. The library re-applies what it owns (primer latch, digest mask on next use); the period accumulators restart as after any module reset.- The transport no longer calls
i2c_master_bus_reset()on its own before the final retry attempt of a failed transaction. The driver resets its state machine after every failed transaction already, and the explicit reset takes no bus lock: when another task has a transaction in flight it drives a STOP on the live pins, which the driver's interrupt handler can take for the end of a read and crash in the ISR (seen on a host with a hot-plugged module).CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTIONrestores the old behaviour for a single-task master. rbamp_set_sensor_class(),rbamp_set_ct_model(),rbamp_set_ct_model_ch()andrbamp_configure_channels()read before they write. A class or model the module already holds is not rewritten (no bus write): on the module a class write clears the CT models even when the value is unchanged, and a model write re-applies the generic preset over the unit's own calibration even when the model is unchanged, so re-applying a stored configuration on every reconnect used to degrade the readings. A module of class 2 or 3 (shipped and calibrated together with its sensor) is not reconfigured:ESP_ERR_INVALID_STATE.rbamp_configure_channels()decides the whole request before its first write, so on such a module nothing is half-applied.latch_msdocumentation: diagnostic only, may read short under load; the energy-integration window ismaster_dt_msormodule_window_ms.- Documentation and the Kconfig help now state the module's publish window as 100 ms across the family (older images: 200 ms). The 300 ms settle the library applies after an STD latch is described as the safe upper bound it is. No timing behaviour changed.
Fixed
rbamp_read_all()/rbamp_read_all_ready()on a module with more than three channels (UI5/UI7, BASIC or STD) wrote channels 3+ past the three-entry arrays ofrbamp_snapshot_t:frequency,topologyandchannelswere overwritten (the host then sawchannels= 0) and the last channel landed four bytes past the struct, on the caller's stack. The call now fills ch0-2 only (RBAMP_SNAPSHOT_CHANNELS), exactly as the period snapshot does; ch3+ stay onrbamp_read_channel()/rbamp_read_all_channels(). Found on a host with a 7-channel module. A host simulation of the whole component against a fake register image now runsread_allfor 1/3/5/7 channels with guard words after the struct.
1.7.1 — Channel count follows the module (2026-10-18)
Fixed
rbamp_new()created a handle whose channel count was fixed at three, so a single-channel module (UI1, I1) still reported three channels afterrbamp_begin(). The default constructor now adopts the channel count and voltage presence from the module's variant register; three channels remain only the fallback for firmware that does not publish a variant.rbamp_new_with_topology()keeps pinning the count as before (a warning is logged when the module disagrees). Reported from a host running a UI1; validated there: a UI1 module reports one channel and the UI1 variant afterrbamp_begin().rbamp_read_variant()on the BASIC line returned UNKNOWN for the UI5 / UI7 codes; it now maps every known code.
Added
rbamp_variant_t rbamp_variant(rbamp_handle_t dev)— the variant cached byrbamp_begin(), without bus traffic.RBAMP_VARIANT_UNKNOWNbeforerbamp_begin()or when the module does not publish its variant.- Host unit tests for the variant policy of both constructors
(
test/host/test_std_decode.c).
1.7.0 — µWh energy, starting current, phase angles and sequence (2026-10-17)
Support for module image version 0x0001007A / 0x0001007B. Every addition is gated on what the module reports; older modules behave exactly as before.
Validated on STD modules with module image version 0x0001007B on a host application: starting-current get/set and read-back, phase angles and phase sequence on a three-phase module, fine energy flags, energy delta across module restarts.
Added
- Energy at µWh / µvarh resolution in
rbamp_std_energy_t:act_import_uwh,act_export_uwh,act_net_uwh,rea_import_uvarh,rea_export_uvarh,ch_import_uwh[],ch_export_uwh[], plusfine/fine_reactive. The fields are filled on every module: from the module's own µ counters when it publishes them (module image version 0x0001007A; reactive from 0x0001007B), otherwise scaled from the coarse counters withfinefalse — callers can use the µ fields unconditionally. Read as coherent snapshots (one transaction per block).rbamp_std_energy_deltaapplies the same rules to them (generation change → no delta, uptime drop = restart, a counter below the previous reading → 0, net = import − export).rbamp_read_period_snapshoton the counter path uses the µWh difference when available. - Starting current for energy:
rbamp_std_get_start_current/rbamp_std_set_start_current(µA; 0 = off; a value outside the set the module accepts →ESP_ERR_INVALID_ARGwithout a bus write; read back and confirmed;rbamp_save_user_configpersists it). Below this channel current the module counts no energy; readings are not affected. Also inrbamp_std_config_t(start_ua,start_ua_supported).ESP_ERR_NOT_SUPPORTEDwithout bus traffic before module image version 0x0001007B. - Voltage phase angle:
rbamp_std_voltage_t.angle_deg/angle_valid(degrees against voltage input 0; module image version 0x0001007A+, three-phase modules; otherwiseangle_validfalse). Same single-burst read as before. - Phase sequence:
rbamp_std_read_phase_seq→rbamp_std_phase_seq_t(RBAMP_STD_PHASE_SEQ_NA/FORWARD/REVERSE/ABNORMAL);ESP_ERR_NOT_SUPPORTEDwithout bus traffic before module image version 0x0001007A. - Host unit test of the pure decode helpers:
test/host/run.sh(gcc, no ESP-IDF). The energy delta rules now live insrc/rbamp_std_decode.c.
Changed
rbamp_is_provisioned(STD line) documents the module image version 0x0001007A calibration marker: a unit calibrated under older firmware reads false after the update until onerbamp_save_gains.
Upgrade note
- The energy snapshot structure (
rbamp_std_energy_t) gained fields in this version. If your application saves it as a raw binary blob (NVS, file), store only the fields you need in your own fixed format; a blob saved by an older version will not match the new size.
1.6.1 — Command completion, coherent reads, OTA session checks (2026-10-11)
Library-side fixes from the firmware/library audit of 2026-10-11. No new API; behaviour of existing calls on the STD line is tightened.
Changed
- Command completion is the module's command-state register (busy flag
cleared and the completed-command counter advanced), never the error
register alone; the verdict is read only after completion. Saves
(
rbamp_save_gains,rbamp_save_user_config),rbamp_std_cal_thd_floor,rbamp_reset, address change and every OTA command use it — no fixed settle sleeps on modules that publish the register, timeouts of at least 1 s (3 s for OTA commit). A command written while the module is busy is waited out first; a command the module dropped (overrun) fails withESP_ERR_INVALID_STATEinstead of returning the previous command's verdict. - A command write is never retried on a transport error (a retry could deliver the opcode twice). Data-register reads and writes keep the retry.
- Block reads are one transaction — the module serves
each read from a coherent snapshot, so energy counters, channel blocks and
totals no longer tear across bursts.
rbamp_read_allon an STD module reads the voltage block and each channel block whole instead of field by field. - OTA: after every page the session must still be open (status 1);
otherwise
ESP_ERR_INVALID_STATEwith the module's reason logged — restart from begin. Polls during a flash stall no longer reset the bus.rbamp_std_ota_activateholds through the module's ~10 s trial window and confirms the running image is the staged version and the swap is no longer pending.rbamp_std_ota_write_image(host-built, unsigned image) returnsESP_ERR_NOT_SUPPORTEDbefore touching the module — only vendor-prepared images are accepted by the module firmware. - Address change (
rbamp_commit_address_change, STD): the config save is synchronous (rate limit →ESP_ERR_NOT_FINISHED, retry after ~5 s), and the handle switches to the new address only after a module answers there; otherwiseESP_ERR_NOT_FOUNDand the handle keeps the old address. rbamp_std_read_totals: the energy fields of aggregate blocks read 0 (not populated by the module — userbamp_std_read_energy).rbamp_read_frequency(STD): 0 from the module means no mains →ESP_ERR_INVALID_RESPONSE/ NaN (rbamp_read_allflags it implausible).rbamp_is_provisioned(STD): documented as reliable from module image version 0x00010079 (older images also report calibration valid on default gains).
1.6.0 — STD module line, data-ready line, events (2026-10-11)
Added
- STD module line (16-bit register map) behind the same handle and API as the
original line:
rbamp_std_probe/rbamp_std_identify/rbamp_std_info, per-channel real-time readings incl. reactive and apparent power (rbamp_read_reactive_power,rbamp_read_apparent_power,rbamp_std_read_channel,rbamp_std_read_voltage), per-phase and grand totals (rbamp_std_read_totals), configuration and harmonics (rbamp_std_read_config,rbamp_std_set_harmonics,rbamp_std_cal_thd_floor). - Energy on modules without latch banks: the period source is chosen from
the module capabilities at
rbamp_begin(rbamp_std_info_t.period_source); period energy is the difference of two readings of the persistent counters, with restart and counter-reset rules.rbamp_std_read_energy(Wh / varh, plus mWh per channel and per group on map 0x36+),rbamp_std_energy_delta,rbamp_energy_add_wh,RBAMP_ENERGY_CH_TOTAL.rbamp_period_snapshot_tgainedavg_p_total,wh_netandmodule_restarted. - Latch banks on modules that have them:
rbamp_std_arm_banks,rbamp_std_latch,rbamp_std_read_latch,rbamp_std_latch_wh. - Module clock, history and event log:
rbamp_std_set_time,rbamp_std_read_time,rbamp_std_read_image_version,rbamp_std_hist_info,rbamp_std_hist_read,rbamp_std_hist_read_raw,rbamp_std_event_read,rbamp_std_hist_flush(hourly ring is persistent; the 15-minute record is the last one only). - Health:
rbamp_std_read_healthextended with status bits, lifetime and calibration sources, frame counters, uptime, and reset cause + boot count (module image version 0x00010076 and newer,RBAMP_STD_RST_*). - Commands and service:
rbamp_std_command,rbamp_std_wait_idle,rbamp_std_locate,rbamp_std_read_board_id,rbamp_std_ota_board_ok(board check before an OTA stream),rbamp_std_set_address_by_uid. - OTA: dual-bank image update incl. prepared signed images
(
rbamp_std_ota_begin…rbamp_std_ota_activate,rbamp_std_ota_write_prepared,rbamp_std_ota_write_prepared_pair,rbamp_std_ota_diag,rbamp_std_ota_staged_version,rbamp_std_ota_abort). - Certificate and attestation:
rbamp_std_read_certificate,rbamp_std_attest(signature verification is done by the application). - Data-ready line (DRDY), both module lines:
rbamp_set_drdy_gpio,rbamp_wait_data_ready,rbamp_read_all_ready,rbamp_read_data_seq. One open-drain line may be shared by several modules; the library verifies the publish sequence, counts missed windows, reports latency and detects a held-low alarm. Polling fallback viaCONFIG_RBAMP_DRDY_POLL_MS. STD modules need module image version 0x00010075 or newer. - Events on both lines:
rbamp_read_event_mask,rbamp_set_event_mask,rbamp_set_event_thresholds,rbamp_begin_event_flags,RBAMP_EVENT_NVM_FAULT;rbamp_read_event_flags/rbamp_clear_event_flags/rbamp_has_error/rbamp_clear_errornow cover the STD line. - Kconfig:
RBAMP_I2C_SCL_WAIT_US(clock-stretch budget, default 10 ms) andRBAMP_DRDY_POLL_MS. - Example
std_meter.
Changed
- Period calls on modules without latch banks return
ESP_ERR_NOT_SUPPORTEDinstead of silently reporting an invalid period. rbamp_set_ct_model_chreturnsESP_ERR_NOT_SUPPORTEDon STD modules whose channel map is not writable.rbamp_err_to_strcoversESP_ERR_NOT_FOUND,ESP_ERR_NOT_FINISHEDandESP_ERR_INVALID_CRC.rbamp_period_snapshot_tandrbamp_std_health_tgained fields (source-compatible; rebuild dependants).- Component now requires
esp_driver_gpio(built-in IDF component).
1.5.0 — Per-channel CT model on every channel (2026-09-04)
Added
rbamp_set_ct_model_ch/rbamp_read_ct_model_ch/rbamp_configure_channelsaccept any channel up to the detected channel count (channels 3+ through the channel window).- Model codes and descriptors come from the generated
rbamp_sensor_models.h(rbamp_sensor_model_lookup); unknown codes are rejected by the module and surfaced to the caller.
Fixed
- Sensor class and CT model now persist on production modules: the previous save opcode did not persist to flash on production firmware, so the binding applied to RAM and was lost on the next reboot. No API change, same ~700 ms settle.
1.4.0 — Five- and seven-channel modules
Added
- Topology
FIVE_CH/SEVEN_CH, variantsUI5/UI7,RBAMP_MAX_CHANNELS= 7;rbamp_read_channel,rbamp_read_all_channels,rbamp_read_commit_seq. The period snapshot integrates all channels.
1.3.0 (2026-06-16) — Public release
First public release of the rbamp component for ESP-IDF v5.x.
Key features
- Fleet manager: manage a group of modules on a single I²C bus
through a single
rbamp_fleet_thandle. Discovery with conflict detection and Tier-2 wedge canary, MISS-resilient_poll_all, aggregation of total-power / total-energy / errors, broadcast-latch for tight synchrony. See chapter 09 · API Reference, section "Fleet manager". - Provisioning:
rbamp_provision— a single-call workflow for reassigning a virgin module to its working address, with optional persistence of the configuration to flash. Discipline: one virgin at a time on the bus (a normative MUST). - Multi-channel configuration:
rbamp_configure_channels— atomic per-channel setup of CT models in a single operation with a single terminal flash cycle (flash-friendly). - Error model v1.3: separates the last-write-outcome
(
REG_ERROR (0x02)— synchronous channel, validated by setters) from the durable async signal (EVENT_FLAGS.bit3— sticky, for runtime facts). The corresponding functions arerbamp_read_last_error,rbamp_has_error,rbamp_clear_error,rbamp_read_event_flags. - Identity / feature-detect:
rbamp_read_variant,rbamp_read_capability(feature map),rbamp_has_voltage,rbamp_read_product_id,rbamp_read_uid,rbamp_is_provisioned.
Canon reflected in the documentation
- Multi-module topology is the library's primary operating mode. The "one module on the bus" scenario is the minimal case, not the canon. The canonical deployment is a mains module at the service entrance plus N modules on individual loads, all on a single I²C bus under a single fleet handle.
- Supported SKUs on current hardware:
UI1(mains meter: voltage + current + power + PF + energy),I1/I2/I3(sub-meters: current only, per channel).UI2/UI3followed in later firmware. - Energy and power are computed only on UI variants (which have a
voltage front-end). On I variants,
rbamp_read_power/_power_factorreturn0.0f; fleet aggregation of total-power / energy correctly sums and ignores the zero contributions. - CT-binding is pure-staging (v1.3 canon): writing
REG_CT_MODELdoes NOT apply the value automatically; binding happens through the per-channelCMD_SET_CT_MODEL_CHn. The binding order is arbitrary (the "ascending/descending order" anachronisms from pre-v1.3 have been removed). - Address change is production-OK: two-phase commit + magic + reset works in production (no factory-mode required).
- Master wall-clock = canonical timebase for Wh: the chip software
timer
PERIOD_LATCH_MS (0xEC)is diagnostic-only; do not use it for energy. The master uses its ownesp_timer_get_time()or wall-clock.
Documentation — new / reworked chapters
01_overview— lead reworked to be multi-module-first; added an ASCII diagram of the 80% scenario.03_sensor_selection— sweep on CT order; new section "Multi-channel modules — I2 and I3 (current-only)" with a UI1+I3 disaggregation pattern.04_hardware— the section "Multi-module bus — primary topology" promoted to the main operating mode; explicit requirement for external ~4.7 kΩ pull-ups on the fleet bus; provisioning workflow viarbamp_provision.09_api_reference— added sections: "Identity and provisioning", "Error model v1.3", "Multi-channel configuration", "Fleet manager — managing multiple modules", "Per-device fleet config".10_troubleshooting— added sections "IDF i2c_master hangs on a marginal bus — three-layer mitigation" (with an HW-validated hang-rate table), "Fleet: a module ended up excluded", "Fleet: rbamp_fleet_scan returned INVALID_STATE", "Fleet: rbamp_provision returned an error".11_changelog— this file.
Source & issues: rb-amp/rbamp-esp-idf · this page in the repo: docs/11_changelog.md (v1.7.3)