feat(config): add num_chargers so a repeated charger is caught rather than silently summed

[chalfontchubby]

Written by Claude, posted on behalf of @chalfontchubby.

Fixes #4879

car_charging_power is the one car_charging_* key that is not one entry per car: it lists chargers, and update_car_charging_power() sums them. It sits among five keys that are indexed by num_cars, so a household with two cars sharing one charger naturally lists that charger twice — and Predbat reports double the power it is drawing. The reporter's diagram showed 14140 W against a Zappi reading 7.1 kW.

Why not just detect it

Deduplicating identical entity ids catches the literal [zappi, zappi] case, but not this, which is the shape a careful user is more likely to produce:

car_charging_power:
  - sensor.zappi_id_buzz_charging_power   # template reading the same Zappi
  - sensor.zappi_kia_ev6_charging_power   # template reading the same Zappi

Two distinct entities, one charger. We cannot see through a template sensor to its source, and there is no invariant to check the sum against — car_energy_reported_load exists precisely because the charger may sit outside the house CT clamp. A check that caught one shape and stayed silent on the other would be worse than none: the silence would read as "validated".

So ask instead

num_chargers names the concept Predbat was missing entirely — it models cars and has no notion of chargers at all, which is the root of the confusion. The existing entries validation then compares it against the length of car_charging_power, catching both shapes because it stops trying to infer something invisible.

• Unset means no check, so no existing apps.yaml changes behaviour.
• The shipped template sets num_chargers: 1 — the common case, and the one that gets this wrong.
• Fewer entries than declared is warned but not an error — a charger with no live power sensor is a real, documented setup, so a short list must not force a false count; but an entry deleted by accident under-reports just as quietly as a repeated one over-reports, so it does not pass in silence either. The warning records no arg_error, so a legitimate setup is never left showing "apps.yaml has N errors".

Two supporting changes worth a reviewer's eye

1. entries validation only ever rejected too FEW entries. Extra entries have always been tolerated, and newly rejecting them everywhere would fail working installs. But for a list that is summed rather than indexed, an extra entry inflates the total instead of being ignored. Hence a new entries_exact flag, set only on this key, so every existing key keeps its current behaviour.

2. A latent hole in the item type check. It trims a list to required_entries before validating the items:

if required_entries is not None and len(value) > required_entries:
    value = value[:required_entries]

With a count key that is simply unset, required_entries is 0, so the list was trimmed to nothing and no items were type-checked at all. That silently disabled the existing "a nonsense charger sensor is rejected" behaviour the moment this key gained an entries rule — caught by an existing test, which is how I found it. Guarded with if required_entries instead. The same hole applied to every entries key whenever its count was 0.

Docs

docs/car-charging.md said only the positive case ("one per line, if you have more than one charger"). It now says the negative out loud: this list describes chargers not cars, num_cars has no bearing on it, list each charger once however many cars you have, and two cars sharing a charger is a single entry. Plus the self-check — compare predbat.car_charging_power against the charger's own app; if it reads double, an entry is repeated.

Testing

Four new cases in test_web_power_flow: a duplicated charger against num_chargers: 1 is an error; the same list validates at num_chargers: 2; fewer entries than declared warns without recording an arg_error; and a nonsense sensor is still type-checked with num_chargers unset (the truncation regression above).

./run_all --quick and ./run_all --test debug_cases both pass.

[Copilot]

🟡 Changes recommended

validate_config() still misses warning-on-short-count when optional_entries is used with a scalar (non-list) value, and the integer-type validation chain contains unreachable duplicated logic that should be addressed for correctness/maintainability.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR introduces a new configuration concept, num_chargers, to prevent EV charging power from being accidentally double-counted when car_charging_power (a summed list) contains repeated entries in multi-car / shared-charger setups.

Changes:

• Add num_chargers and apply it to car_charging_power via entries validation, with a new entries_exact flag to reject extra entries for this specific summed list.
• Fix validate_config() list-truncation logic so entries rules with a count of 0 don’t silently skip per-item type validation.
• Update docs and add unit tests covering duplicated entries, exact matching, short-list warnings, and type-checking when num_chargers is unset.

File summaries

File	Description
docs/car-charging.md	Clarifies that car_charging_power describes chargers (summed), not cars, and documents num_chargers.
docs/apps-yaml.md	Adds num_chargers and notes car_charging_power is charger-based (not per-car).
apps/predbat/tests/test_web_power_flow.py	Adds regression tests for duplicated charger entries, exact-count validation, short-list warnings, and type-checking.
apps/predbat/predbat.py	Extends validate_config() with entries_exact, short-list warning behavior, and fixes the “count=0 truncates away validation” hole.
apps/predbat/config/apps.yaml	Updates the shipped template to include num_chargers.
apps/predbat/config.py	Adds num_chargers schema entry and applies entries_exact/optional_entries rules to car_charging_power.

Review details

Suppressed comments (1)

apps/predbat/predbat.py:1485

• When optional_entries is true and required_entries > 1, a non-list value (single sensor) currently passes with no warning. That contradicts the intent of optional_entries here (warn-but-not-error when fewer entries are provided) and can let an under-specified config go by silently (e.g., num_chargers=2 with a single car_charging_power sensor). Consider emitting the same warning used for short lists in this branch.

                    elif required_entries > 1:
                        if not optional_entries:
                            self.log("Warn: Validation of apps.yaml found configuration item '{}' is not a list, but requires {} entries based on {}".format(name, required_entries, entries))
                            self.arg_errors[name] = "Invalid type, expected list"
                            errors += 1
                            continue

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chalfontchubby]

Fixed in 6976adf — merged the second, unreachable integer/integer_list block's allowed-list check into the one branch the elif chain actually reaches, and deleted the dead duplicate. Added a regression test (threads=21) confirming an out-of-range integer is now rejected.

Posted by Claude on behalf of @chalfontchubby.

[chalfontchubby]

Fixed in 6976adf — arg_errors now reads "Too many entries, expected exactly N" to match the log line.

Posted by Claude on behalf of @chalfontchubby.