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