Added dev README

This commit is contained in:
Sleeper85 committed 2026-11-08 23:08:32 +01:00
1 parent 6e23ffe202
commit bfa36fb15f
4 files changed
+295

No files matched your search

@@ -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/<domain>/` follow this grammar:
```
<domain>_<layer>_<Brand>_<Interface>_<variant>.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 `<domain>${xxx_id}_<name>`:
```
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 <file>.yaml # validation only
esphome compile <file>.yaml # full compilation
```
See [Installation_procedure.md](../Installation_procedure.md).
+132
View File
@@ -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.
<!-- TODO maintainer: list the exact elements that must not be merged (timer, latched state,
compound conditions) — see v1.7.1. -->
## 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.
<!-- TODO maintainer: list them here, in the form "do not lower <value> below <threshold>, or
<symptom>" — at minimum loop_task_stack_size, update intervals, RS485 timings. -->
## 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.
+66
View File
@@ -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_<Brand>_<Interface>_<variant>.yaml` | The file you include from your main YAML. Assembles the layers below. |
| `*_modbus_<Brand>_*.yaml` | Modbus register mapping (RS485/Modbus BMS only). |
| `*_sensors_<Brand>_*.yaml` | Declaration of the exposed ESPHome entities. |
| `*_errors_bitmask_<Brand>.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.