Files
esphome-yambms/documents/README/dev/Coding_conventions.md
T
Sleeper85 58c03ac83f Packages: Declare each CAN node in the package that consumes it
yambms_canbus.yaml and the Deye top packages now import their node from
canbus_platform (esp32_can, mcp2515 or external). canbus_bitrate replaces
esp32_canbus_bitrate and mcp2515_canbus_bitrate. Breaking change.
2026-11-08 23:08:34 +01:00

133 lines
4.4 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.
## 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).