ESPHome 2026.11 makes `relation` a required option for every entry under `esphome: devices:`, and 2026.10 rejects that key. Both changes have to land together, so raise min_version to 2026.11.0 in the same commit. Use `relation: via` on all ten device declarations (BMS, sniffer, shunt, balancer, Deye stack, board, YamBMS instance, CAN and RS485 links). It is the value the API assumed before the key existed, so Home Assistant keeps showing the devices exactly as before. `child` would fit the board, the YamBMS instance and the inverter links better, but it is left for later: a Home Assistant release that reads the field without supporting `child` drops those devices and their entities. Docs: ESPHome 2026.11.0 in README and Installation_procedure (which still said 2025.11.0), Design_decisions no longer equates min_version with the flow_control requirement, and Coding_conventions documents the `relation: via` rule.
137 lines
4.6 KiB
Markdown
137 lines
4.6 KiB
Markdown
# 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.
|
|
|
|
## UART declaration
|
|
|
|
A package that needs a UART imports it itself, from its `*_uart_id` var, and exposes the baud rate
|
|
under its own key. `uart_baud_rate` is the internal parameter of the UART file: never a key of a
|
|
package.
|
|
|
|
```yaml
|
|
packages:
|
|
shunt_uart: !include
|
|
file: ../board/board_options_itf_${shunt_uart_id}.yaml
|
|
vars:
|
|
uart_baud_rate: ${shunt_uart_baud_rate | default(115200)}
|
|
```
|
|
|
|
Use `| default(...)` when the device has a usual speed, and leave it out when the speed depends on
|
|
the installation. Never put a fixed value there, nor the default in `substitutions:`. See
|
|
[Design_decisions.md](Design_decisions.md) for the reasons.
|
|
|
|
## CAN declaration
|
|
|
|
A package that needs a CAN node imports it itself, from its `canbus_platform` var, and exposes the
|
|
bit rate as `canbus_bitrate`. `canbus_bit_rate` is the internal parameter of the CAN file: never a
|
|
key of a package.
|
|
|
|
```yaml
|
|
packages:
|
|
canbus_node: !include
|
|
file: ../board/board_options_itf_canbus_${canbus_platform}.yaml
|
|
vars:
|
|
canbus_bit_rate: ${canbus_bitrate | default('500kbps')}
|
|
```
|
|
|
|
`canbus_platform` has no default, and the id of the node stays free in `canbus_node_id`. See
|
|
[Design_decisions.md](Design_decisions.md) for the reasons.
|
|
|
|
## 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.
|
|
|
|
Since ESPHome 2026.11, every entry under `esphome: devices:` requires a `relation:`. Use `via`
|
|
for all of them, including the board, the YamBMS instance and the inverter links: it is the value
|
|
the API assumed before the key existed, so Home Assistant shows the devices exactly as it did.
|
|
|
|
## 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).
|