Files
esphome-yambms/documents/README/dev/Project_structure.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

4.0 KiB

Project structure

YamBMS is a set of ESPHome YAML packages — there is no compiled application code beyond a few embedded C++ lambdas. It merges data from several BMS / Shunt / Balancer units and drives an inverter over CAN or RS485 (PYLON / SMA / Victron / LuxPower). All the logic lives in YAML (substitutions, packages: !include, lambda:) and is assembled by the ESPHome compiler.

Entry points

  • YamBMS_LP_*.yaml — Local Packages. Requires the packages/ folder to be present locally.

  • YamBMS_RP_*.yaml — Remote Packages. Pulls the packages from GitHub (!include on a github:// URL). This is what most users run.

    Differences and structure are detailed in YamBMS_LP_YAML.md and YamBMS_RP_YAML.md.

  • YamBMS_Local_Packages_example.yaml / YamBMS_Remote_Packages_example.yaml — starting templates.

  • yambms_config.yaml — Modbus substitutions shared between several nodes in a multi-node setup.

  • yambms_custom.yaml — snippets meant to be copy-pasted into the main YAML (extra switches and services). Not included by default.

  • examples/single-node/ and examples/multi-node/ — ready-to-copy !include blocks for a given BMS, Shunt or Balancer.

The packages/ tree

base/

Generic device building block: ESPHome core, WiFi, Ethernet, sub_device declarations, the fault registry (device_base_fault_registry.yaml), memory and PSRAM debug helpers.

board/

One file per board (board_ESP32-S3_*.yaml) defining pins and GPIO. The board_options_*.yaml files are optional building blocks — CAN, PSRAM, LVGL display, WiFi AP — included separately depending on the hardware.

The board_options_itf_uart_*.yaml files are the exception: they are not included from the main YAML. Each one declares a single UART (uart_esp_N, uart_N on the RPi Pico, uart_spi_N and uart_i2c_N on a WK2168) and is imported by the package that consumes that UART, from its *_uart_id var. A WK2168 only needs board_options_itf_wk2168_spi.yaml or board_options_itf_wk2168_i2c.yaml in the main YAML, which declares the bridges.

The board_options_itf_canbus_*.yaml files follow the same rule: yambms_canbus.yaml and the Deye top packages import the one named by their canbus_platform var (esp32_can, mcp2515, or external for a node declared elsewhere).

bms/, shunt/, balancer/

All three follow the same layered scheme, per brand and protocol:

File pattern Role
*_combine_<Brand>_<Interface>_<variant>.yaml The file you include from your main YAML. Assembles the layers below.
*_modbus_<Brand>_*.yaml Modbus register mapping (RS485/Modbus BMS only).
*_sensors_<Brand>_*.yaml Declaration of the exposed ESPHome entities.
*_errors_bitmask_<Brand>.yaml Alarm bit mapping.
*_base*.yaml Brand-agnostic shared logic: combining engine, SoC/SoH, cycles, LED.

yambms/

The central engine. yambms.yaml aggregates yambms_brand_registry.yaml, yambms_core.yaml, the yambms_auto_*.yaml functions (CVL / CCL / DCL / Float / EOC / temperature / SoC limit) and yambms_service.yaml, then yambms_canbus*.yaml or yambms_rs485*.yaml for the link to the inverter.

yambms_brand_registry.yaml holds the protocol dictionary (YB_PROTO_*), the brand to protocol mapping and the per-couple battery mode and note. Both inverter buses read it.

On the RS485 side, yambms_rs485.yaml is the entry point — selects, diagnostics, telemetry slot — and it includes the protocol implementation, currently yambms_rs485_pylon.yaml.

Where the behaviour is documented

The structure above tells you where code lives, not what it does. For the charging logic and the auto functions, read: