Added dev README
This commit is contained in:
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).
|
||||
@@ -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.
|
||||
File renamed without changes.
@@ -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.
|
||||
Reference in new issue
Block a user