Files
esphome-yambms/documents/README/dev/Coding_conventions.md
T
Sleeper85 67b6892e24 Set ESPHome min_version to 2026.11.0 and declare sub-device relation
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.
2026-11-09 00:06:28 +01:00

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).