diff --git a/documents/README/dev/Coding_conventions.md b/documents/README/dev/Coding_conventions.md new file mode 100644 index 0000000..ad33744 --- /dev/null +++ b/documents/README/dev/Coding_conventions.md @@ -0,0 +1,97 @@ +# Coding conventions + +Conventions actually in use across the repository. Follow them when adding a package or editing +an existing one — the safest approach is always to copy a comparable existing file and adapt it. + +## Language + +Code comments and documentation are written in **English**. + +## File naming + +Files under `packages//` follow this grammar: + +``` +____.yaml +``` + +For example: `bms_combine_JK_RS485_Modbus_bms_full.yaml`. + +The `_full` / `_standard` / `_minimal` / `_secondary` variants control **how many entities are +exposed**, not the logic itself. + +## File header + +Every package YAML starts with the same header block: + +```yaml +# Updated : yyyy.mm.dd +# Version : x.y.z +# GitHub : https://github.com/Sleeper85/esphome-yambms +``` + +followed by the GPLv3 notice. Reproduce it in any new package. + +## Instance substitutions + +`${xxx_id}` substitutions are numeric identifiers. For BMS units (`bms_id`) they **must start at +`1` and be contiguous**. This is a functional constraint, not a style rule, and the consequence of +getting it wrong is severe: the combiner pipeline advances a shared counter from one instance to +the next, so a gap in the numbering stalls that counter and the whole aggregation deadlocks +silently — no combined values, no setpoints sent to the inverter. The identifier is also used as +a bitmask index, for instance `1 << (${bms_id} - 1)` in `bms_combine.yaml`. + +See [Design_decisions.md](Design_decisions.md) for how the pipeline works. + +## Include order + +Include the BMS and Shunt packages in ascending `${xxx_id}` order in your main YAML. The combiner +processes instances in the order their lambdas run, so ascending order completes one aggregation +round per interval; an out-of-order include still converges but spreads the round over several +intervals. + +## Entity IDs + +Entity IDs follow `${xxx_id}_`: + +``` +bms${bms_id}_total_voltage +yambms${yambms_id}_var_bms_online_bitmask +``` + +Globals used by the YamBMS engine's internal logic are prefixed `yambms${yambms_id}_var_*`. + +## Sub-devices + +Every entity carries a `device_id:` that attaches it to the matching ESPHome `sub_device`, so that +each BMS, Shunt, Balancer and YamBMS instance appears as its own device in Home Assistant. Always +fill it in — copy an existing package to get it right. + +## Section comments + +Large files (`yambms_core.yaml`, `bms_combine.yaml`, the `YamBMS_LP_*` root YAML) are structured +with ASCII box comments: + +```yaml +# +----------------------------------------+ +# | Section title | +# +----------------------------------------+ +``` + +## Boot sequencing + +Startup ordering relies on `on_boot` priorities. For example, `priority: 600` initialises the BMS +combiner in `bms_combine.yaml`, and `priority: 550` is documented as running right after it in +`yambms_custom.yaml`. If you add an `on_boot` block, respect the existing ordering rather than +picking an arbitrary priority. + +## Validating a change + +There is no test suite. Validate a YAML with: + +```bash +esphome config .yaml # validation only +esphome compile .yaml # full compilation +``` + +See [Installation_procedure.md](../Installation_procedure.md). diff --git a/documents/README/dev/Design_decisions.md b/documents/README/dev/Design_decisions.md new file mode 100644 index 0000000..d4a87a7 --- /dev/null +++ b/documents/README/dev/Design_decisions.md @@ -0,0 +1,132 @@ +# 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. + + + +## Auto CVL floor in Float + +**File:** `packages/yambms/yambms_auto_cvl.yaml` + +The Float floor is derived at runtime from the `Rebulk V.` entity, not from a fixed voltage. Any +fixed floor — including `cell_count × nominal voltage` — can sit at or below the rebulk threshold +depending on the user's settings, which lets Auto CVL pull the pack down far enough to trigger a +rebulk it caused itself, looping Float → Bulk → Float. Keep the floor derived from `Rebulk V.`. + +See [Charging_logic.md](../Charging_logic.md) for the charging behaviour itself. diff --git a/documents/README/How_to_perform_a_PR_to_the_dev_branch.md b/documents/README/dev/How_to_perform_a_PR_to_the_dev_branch.md similarity index 100% rename from documents/README/How_to_perform_a_PR_to_the_dev_branch.md rename to documents/README/dev/How_to_perform_a_PR_to_the_dev_branch.md diff --git a/documents/README/dev/Project_structure.md b/documents/README/dev/Project_structure.md new file mode 100644 index 0000000..0fbcb5d --- /dev/null +++ b/documents/README/dev/Project_structure.md @@ -0,0 +1,66 @@ +# Project structure + +YamBMS is a set of **ESPHome YAML packages** — there is no compiled application code beyond a few +embedded C++ lambdas. It merges data from several BMS / Shunt / Balancer units and drives an +inverter over CAN or RS485 (PYLON / SMA / Victron / LuxPower). All the logic lives in YAML +(`substitutions`, `packages: !include`, `lambda:`) and is assembled by the ESPHome compiler. + +## Entry points + +- **`YamBMS_LP_*.yaml`** — *Local Packages*. Requires the `packages/` folder to be present + locally. +- **`YamBMS_RP_*.yaml`** — *Remote Packages*. Pulls the packages from GitHub (`!include` on a + `github://` URL). This is what most users run. + + Differences and structure are detailed in [YamBMS_LP_YAML.md](../YamBMS_LP_YAML.md) and + [YamBMS_RP_YAML.md](../YamBMS_RP_YAML.md). + +- **`YamBMS_Local_Packages_example.yaml`** / **`YamBMS_Remote_Packages_example.yaml`** — starting + templates. +- **`yambms_config.yaml`** — Modbus substitutions shared between several nodes in a multi-node + setup. +- **`yambms_custom.yaml`** — snippets meant to be copy-pasted into the main YAML (extra switches + and services). Not included by default. +- **`examples/single-node/`** and **`examples/multi-node/`** — ready-to-copy `!include` blocks for + a given BMS, Shunt or Balancer. + +## The `packages/` tree + +### `base/` + +Generic device building block: ESPHome core, WiFi, Ethernet, `sub_device` declarations, the fault +registry (`device_base_fault_registry.yaml`), memory and PSRAM debug helpers. + +### `board/` + +One file per board (`board_ESP32-S3_*.yaml`) defining pins and GPIO. The `board_options_*.yaml` +files are optional building blocks — UART, CAN, PSRAM, LVGL display, WiFi AP — included +separately depending on the hardware. + +### `bms/`, `shunt/`, `balancer/` + +All three follow the same layered scheme, per brand and protocol: + +| File pattern | Role | +|---|---| +| `*_combine___.yaml` | The file you include from your main YAML. Assembles the layers below. | +| `*_modbus__*.yaml` | Modbus register mapping (RS485/Modbus BMS only). | +| `*_sensors__*.yaml` | Declaration of the exposed ESPHome entities. | +| `*_errors_bitmask_.yaml` | Alarm bit mapping. | +| `*_base*.yaml` | Brand-agnostic shared logic: combining engine, SoC/SoH, cycles, LED. | + +### `yambms/` + +The central engine. `yambms.yaml` aggregates `yambms_core.yaml`, the `yambms_auto_*.yaml` +functions (CVL / CCL / DCL / Float / EOC / temperature / SoC limit) and `yambms_service.yaml`, +then `yambms_canbus*.yaml` or `yambms_rs485_pylon*.yaml` for the link to the inverter. + +## Where the behaviour is documented + +The structure above tells you where code lives, not what it does. For the charging logic and the +auto functions, read: + +- [Charging_logic.md](../Charging_logic.md) +- [YamBMS_functions.md](../YamBMS_functions.md) +- [YamBMS_behavior.md](../YamBMS_behavior.md) +- [Supported_devices.md](../Supported_devices.md) — supported BMS, shunts and inverters.