Pace active-control deltas to the battery firmware's ramp (#458) by tomquist · Pull Request #467 · tomquist/AstraMeter

tomquist · 2026-06-12T21:06:24Z

Summary

Closes #458 (and documents the conclusion of #459). Builds on the evaluation harness from #466 — the steering-eval CI comment on this PR shows the real before/after (base = develop without pacing, head = with pacing), which is why we landed the harness first.

The problem (#458)

The balancer assumed a deadbeat battery — it sent each battery a target delta and expected it applied in one poll. But the real Venus firmware runs its own gain-scheduled accelerating ramp (≈50 W → ≈400 W per poll) on the reading we send, bounded only by |reading|. So a large delta plus one poll of meter latency let that accelerated ramp overshoot by hundreds of watts and oscillate. The balancer's deadband (15 W) also sat below the battery's own ±20 W input deadband, so it chased corrections the battery ignored.

The change

Ramp pacing. Auto-path readings are now capped per consumer: the cap starts at the firmware's ~50 W first ramp step, doubles toward 200 W only while the battery's reported output demonstrably tracks the command (moved ≥20 W toward it since the last poll), follows the error back down, and resets on direction reversal. Probe, MIN_DC_OUTPUT-floor, manual and steer-to-zero paths bypass pacing. New knobs PACE_BASE_STEP / PACE_MAX_STEP (0 disables).
BALANCE_DEADBAND default 15 → 25 W, above the battery's own ±20 W input deadband.
Preserves Venus E stops the charging process when Venus D is feeding excess power into the grid. #376. Because the per-poll delta is now capped, the instructed net power can keep the sign of a battery's involuntary output (PV passthrough at full SoC) for many polls. The balancer now records the unpaced control intent (last_intent), and the cross-talk chrg/dchrg attribution filters by it instead of the paced instructed power.

Why these defaults

Chosen with the evaluation suite under realistic 1 s meter latency. Versus the unpaced baseline across the scenario matrix:

	overshoot (summed max)	battery churn	steady RMS	settling
Δ	−80% (13.7 kW → 2.0 kW)	−33%	−25%	~8% slower

Growing the cap to the firmware's full 400 W gain measurably overshoots under meter latency, so 200 W wins.

Also lands #459 (comment-only, no behavior change)

Since the redesign keeps per-battery targeting, active control must keep reporting *_chrg_nb = 1 (a real count N would make each battery divide its already-individual target by N). The chrg_nb branches (Python + C++) and docs/ct002-ct003-protocol.md now explain why, so the #455 relay-count fix isn't accidentally generalized. #459 is closed as won't-fix.

Scope

src/astrameter/ct002/balancer.py, ct002.py, main.py, web_config.py + config docs (config.ini.example, README.md, esphome.example.yaml).
C++ parity: esphome/components/ct002/{balancer.h,balancer.cpp,ct002.cpp,__init__.py,test_hooks.cpp} mirror the pacing, the last_intent observable, and the config plumbing.
Tests: new TestPaceReading unit tests + host gtests, the parity fuzz harness exercises the new knobs and the intent observable, a paced-vs-unpaced overshoot regression in tests/test_steering_eval.py, and the Venus E stops the charging process when Venus D is feeding excess power into the grid. #376 e2e now asserts the intent on both backends.

Known limitation (not introduced here)

The mixed_venus_b2500/eff scenario stays rough in every variant (probe/rotation churn with a DC-only unit) — pacing neither helps nor hurts it. Worth its own follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SeKwnaH74tzQoZEPhmhBu8

Generated by Claude Code

Summary by CodeRabbit

Release Notes

New Features
- Added ramp-pacing for battery control commands with new configurable parameters PACE_BASE_STEP (default 50W) and PACE_MAX_STEP (default 200W); pacing can be disabled by setting PACE_BASE_STEP = 0.
Configuration
- BALANCE_DEADBAND default increased from 15W to 25W.
Documentation
- Updated all configuration files and documentation to reflect new pacing parameters and balance deadband defaults.

coderabbitai · 2026-06-12T21:06:31Z

Walkthrough

This PR implements ramp-paced battery command control and unpaced intent tracking to reduce overshoot and improve convergence when working with the battery firmware's own ±20 W deadband and accelerating control loop. It raises balance_deadband to 25 W, introduces pace_base_step/pace_max_step pacing parameters, separates intended control intent from paced targets, and filters active-control cross-talk using intent-vs-instructed sign conflicts.

Changes

Ramp Pacing Control System

Layer / File(s)	Summary
Documentation and configuration updates `CHANGELOG.md`, `README.md`, `config.ini.example`, `esphome.example.yaml`, `docs/ct002-ct003-protocol.md`	Changelog, README, config examples, and protocol docs are updated to explain the new pacing parameters (PACE_BASE_STEP, PACE_MAX_STEP defaults), raised balance_deadband (15 → 25 W), and active-control per-phase battery count reporting behavior.
Pacing constants and balancer configuration schema `esphome/components/ct002/balancer.h`, `src/astrameter/ct002/balancer.py`, `esphome/components/ct002/__init__.py`, `src/astrameter/web_config.py`	New module constants (PACE_TRACKING_DELTA_W, PACE_GROWTH_FACTOR) and BalancerConfig fields (pace_base_step, pace_max_step) are introduced in C++ and Python. ESPHome schema wiring and web configuration keys recognize and type these fields.
Pacing and intent state tracking structures `esphome/components/ct002/balancer.h`, `src/astrameter/ct002/balancer.py`	BalancerConsumerState is extended with last_intent (pre-pacing control target) and pacing state (pace_cap, pace_sign, pace_prev_reported) to track per-consumer tracking dynamics across polls. Public get_last_intent() accessor and protected pace_reading_() helper are declared.
Pacing algorithm implementation `esphome/components/ct002/balancer.cpp`, `src/astrameter/ct002/balancer.py`	Core pace_reading_() logic ramps per-poll command deltas: caps at pace_base_step initially, grows cap up to pace_max_step while battery tracks, passes through when error fits, and resets on direction reversal. Config clamping also validates pacing bounds.
Intent tracking across all control paths `esphome/components/ct002/balancer.cpp`, `src/astrameter/ct002/balancer.py`	Probe-target, manual-override, min-dc-floor, and steer-to-zero control paths now record last_intent separately from paced last_target in both C++ and Python.
Auto-target pacing in fading and residual branches `esphome/components/ct002/balancer.cpp`, `src/astrameter/ct002/balancer.py`	Auto-target fading and residual paths compute desired intent, pass it through pace_reading_() to produce paced target, and store both values in consumer state.
Active control intent-based cross-talk filtering `esphome/components/ct002/ct002.cpp`, `src/astrameter/ct002/ct002.py`	collect_reports_by_phase_() now zeroes instructed power when last_intent sign conflicts with computed power sign, preventing involuntary-output reversals from being counted in active-control aggregation. Clarifying comments explain per-phase battery count reporting.
Configuration reading and initialization wiring `esphome/components/ct002/__init__.py`, `src/astrameter/ct002/ct002.py`, `src/astrameter/main.py`	Pace parameters are wired from ESPHome to_code() through Python CT002.init() and LoadBalancerConfig, with main.py reading from config and web_config.py providing schema typing.
Test harness and parity infrastructure `esphome/components/ct002/test_hooks.cpp`, `tests/components/ct002/fixtures/balancer_parity_harness.cpp`, `tests/components/ct002/test_balancer_parity.py`, `tests/_ct002_e2e_backend.py`	Parity harness supports optional pace_base/pace_max in cfg command and new intent command to query last_intent. Dump format includes last_intent per consumer. Fuzz generator randomly varies pacing content to validate host/firmware consistency.
Pacing-specific validation tests `tests/components/ct002/host_balancer_test.cpp`, `tests/test_balancer.py`	New C++ LoadBalancer test (PaceReadingCapsGrowsAndResets) and Python TestPaceReading class comprehensively verify cap growth/reset, direction reversals, disabling when base_step=0, max_step clamping, small error passthrough, and that manual/inactive paths bypass pacing.
Existing test adjustments for pacing isolation `tests/components/ct002/test.esp32-idf.yaml`, `tests/test_balancer_distribution_weight.py`, `tests/test_balancer_mixed_battery_charging.py`, `tests/test_ct002_active_control.py`	Existing tests disable pacing (pace_base_step=0) to isolate raw share math and floor behavior. CT002 active-control tests use _ct002() factory helper to consistently apply pacing=0.
E2E and regression testing with pacing enabled `tests/test_efficiency_e2e.py`, `tests/test_issue376_pv_passthrough.py`, `tests/test_steering_eval.py`	Efficiency e2e relaxes specific-battery assertions to pool-level validation. Issue376 test uses last_intent for Venus D assertions and ESPHome aggregation filtering. New TestRampPacingRegression validates overshoot bounds comparing paced vs unpaced firmware plant runs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

tomquist/AstraMeter#406: Extends CT002 differential-parity testing framework (balancer_parity_harness.cpp/test_balancer_parity.py) to support the new intent field and pacing parameters.
tomquist/AstraMeter#384: Changes CT002 cross-talk aggregation to use per-consumer instructed/net intent; this PR adds an additional sign-conflict filter on top of that basis.
tomquist/AstraMeter#455: Modifies CT002 active-control aggregation and per-phase battery count reporting; this PR refines the sign-based filtering and clarifies the count-reporting intent (issue #459).

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.83% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: implementing ramp pacing for active-control deltas aligned to the battery firmware's behavior (`#458`).
Linked Issues check	✅ Passed	All objectives from `#458` are met: deadband increased to 25W (≥20W), per-consumer per-poll pacing introduced (50-200W ramp matching battery), last_intent tracking preserves prior behavior, config exposed, Python/C++ parity maintained, and tests validate reduced overshoot/oscillation.
Out of Scope Changes check	✅ Passed	All changes are directly tied to `#458/`#459: ramp pacing implementation, deadband tuning, intent tracking for attribution, config/web plumbing, parity harness updates, and regression tests validating overshoot behavior.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch claude/serene-ptolemy-kpd6ig

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-06-12T21:07:58Z

Steering evaluation (base vs head)

Lower is better for every metric. See src/astrameter/simulator/evaluation.py for definitions.

What do these metrics mean?

Metric	Meaning
`settle_mean_s`	Mean seconds after a load/PV step for grid power to return inside the ±25 W settle band and hold for 10 s (reaction speed).
`settle_p95_s`	95th-percentile settle time — the slow tail of reactions.
`unsettled_events`	Number of disturbance events that never settled within the 10-minute measurement window.
`overshoot_mean_w`	Mean overshoot (W): how far grid power swings past zero to the opposite sign after an event.
`overshoot_max_w`	Worst-case overshoot (W) across all events.
`band_crossings_per_h`	Sign flips per hour across the ±20 W hysteresis band — oscillation / hunting.
`steady_rms_w`	RMS grid power (W) during steady state (excluding the 120 s after each event) — residual jitter when nothing is changing.
`mean_abs_grid_w`	Mean absolute grid power (W) over the whole run — overall tracking accuracy.
`avoidable_import_wh`	Energy imported from the grid (Wh) the battery could have supplied (it had charge and discharge headroom) — missed self-consumption.
`avoidable_export_wh`	Energy exported to the grid (Wh) an AC-chargeable battery could have absorbed (it had room and charge headroom) — missed charging.
`battery_travel_w_per_h`	Total absolute change in battery setpoints per hour (W/h) — control effort / actuator wear; lower is smoother.

mixed_cadence/eff — settle 105.7→88.8s, overshoot 1949.5→872.7W, RMS 111.7→39.6W

Metric	Base	Head	Δ
settle_mean_s	105.7	88.8	-16%
settle_p95_s	241.7	178.9	-26%
unsettled_events	1	1	=
overshoot_mean_w	766.7	323.5	-58%
overshoot_max_w	1949.5	872.7	-55%
band_crossings_per_h	446.0	302.0	-32%
steady_rms_w	111.7	39.6	-65%
mean_abs_grid_w	100.0	69.6	-30%
avoidable_import_wh	75.2	51.7	-31%
avoidable_export_wh	25.1	18.1	-28%
battery_travel_w_per_h	180519.0	80294.0	-56%