Files
esphome-yambms/documents/README/dev/Design_decisions.md
T

5.6 KiB
Raw Blame History

Design decisions

Some parts of the codebase look more verbose or more redundant than they need to be. They are deliberate. This page records why, so that a well-intentioned cleanup doesn't reintroduce a bug that took a long time to find.

Do not refactor anything listed here without discussing it first, and read the rationale before touching the code.

Cut-Off / EOC logic

File: packages/yambms/yambms_core.yaml

The End Of Charge condition is deliberately compound. It has to distinguish a genuine EOC from a charge current that is merely capped by low solar production. Collapsing it into a single threshold or voltage comparison reintroduces false EOC on overcast days.

The combiner pipeline

Files: packages/bms/bms_combine.yaml, packages/shunt/shunt_combine.yaml, packages/yambms/yambms_core.yaml

Every BMS and Shunt package instance runs the same interval lambda, and they coordinate through a shared counter rather than through any central loop. Each instance only acts on the tick where var_to_combine_bms_number equals its own ${bms_id}, then increments the counter so the next instance can run. yambms_core.yaml (STEP 2) waits until every device has been processed, then resets the counters to 1 for the next round.

This is why bms_id must start at 1 and be contiguous. It is not a style rule and not only about the bitmask index: with a gap in the numbering, the counter stops at the missing id, never advances, and STEP 2 never fires. The whole pipeline deadlocks silently.

Include the BMS and Shunt packages in ascending id order. Out-of-order includes still converge, but spread one round over several intervals instead of completing in one.

can_be_combined is deliberately exhaustive

The condition in bms_combine.yaml checks every sensor the combiner will read. It is long on purpose: a single missing or NaN value entering the totals corrupts the aggregate that drives the inverter. Do not shorten it to a few representative checks.

Note that the checks are not uniform. Most use has_state(), but total_voltage, battery_capacity, max_charge_current and max_discharge_current use > 0 — a BMS reporting zero for those is treated as not ready rather than as a valid reading.

Combined once, combined continuously, uncombined

Three distinct scopes in the same lambda, and they are not interchangeable:

  • Once — total_installed_battery_capacity accumulates a single time per BMS, for the lifetime of the boot. It represents the installed capacity and deliberately does not shrink when a BMS drops offline.
  • Not continuously — the combined counter is incremented on the transition into the combined state, not on every tick.
  • Continuously — the totals, bitmasks and min/max values are recomputed every round.

bms_seen_online_bitmask is never cleared

It records that a BMS has been online at least once since boot. shunt_combine.yaml uses it to tell "this BMS is offline" apart from "this BMS was never there" — a shunt must not be uncombined because of a BMS the user never installed.

Cell numbers are offset per pack

The combiner reports cell number + (${bms_id} × 100), so cell 8 of BMS 1 is reported as 108 and cell 3 of BMS 2 as 203. This makes the pack immediately identifiable in the dashboard. It caps a pack at 99 cells, which is well beyond any realistic configuration.

A shunt uncombine turns the user switch off, and does not turn it back on

When a BMS mapped to a shunt goes offline, shunt_combine.yaml switches Combine enabled off and records which BMS caused it, so the diagnostic State entity can say so. Re-enabling is deliberately manual: coming back online does not automatically restore the combination, because the SoC reference has to be trusted before it is used again.

The {0} sentinel in bms_ids

shunt${shunt_id}_bms_map defaults to '{0}' because the vector needs a non-empty initialiser, and the loop skips id 0 (if (!bms_id) continue;). Do not "clean up" the zero — it is what makes an unmapped shunt valid.

CAN frame catalogue

File: packages/yambms/yambms_canbus.yaml

Several can_id values are reused with different payloads depending on the protocol:

CAN ID Frame Protocol
0x359 5 PYLON
0x359 24 Deye PCS
0x371 11 SEPLOS
0x371 28 Deye PCS

A frame's identity is its internal frame number, never its CAN ID. Do not merge two blocks because they share a CAN ID — that would break both protocols at once.

Byte order is not uniform either: 0x373 sends min cell voltage before max, 0x361 sends max before min. Both match their respective specifications. Do not "harmonise" them.

Frame sequencing

File: packages/yambms/yambms_canbus.yaml

Each protocol is defined as a sequence of frame numbers emitted on a fixed interval, so a full cycle lasts interval × sequence length — from a few hundred milliseconds to over a second depending on the protocol. Some inverters are sensitive to that cadence. Do not change the interval to make protocols "consistent" with each other.

When adding a frame to a sequence, remember that the sequence length is tracked alongside the array. Keep the two in sync, or the new frame will silently never be emitted.

Empirical constants

Some constants were found by trial on real hardware and must not be rounded or harmonised.