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

4.6 KiB

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:

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

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

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 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:

# +----------------------------------------+
# | 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:

esphome config <file>.yaml    # validation only
esphome compile <file>.yaml   # full compilation

See Installation_procedure.md.