BREAKING CHANGE: both inverter link selects are renamed, so their stored value is
reset. The link stays inactive until an inverter brand is selected. See
documents/README/changelog/Changelog_Inverter_brand_and_protocol.md
New `Inverter brand` select (16 brands) and reworked `Protocol` select, now
defaulting to `Automatic`. Selecting the brand is enough, the protocol follows;
an explicit protocol still takes priority over the brand.
The protocol is resolved once, at boot and on every select change, into
`canbus${canbus_id}_active_protocol` / `rs485${rs485_id}_active_protocol`.
Everything else reads that integer instead of dispatching on `active_index()`,
where `== 5` meant LuxPower purely by convention of the option order.
New shared `yambms_inverter_registry.yaml`: protocol dictionary (`YB_PROTO_*`),
brand to protocol mapping, and the battery mode and note of each couple.
Removed the `YamBMS name` select: the manufacturer name sent on CAN frame 0x35E
now derives from the protocol in use, which is what `Automatic` already did.
Removed the `canbus_extended_ack` substitution: both the 11-bit and the 29-bit
ACK triggers are registered, so the Schneider XW Pro needs no configuration.
Renamed CAN `PYLON 1.2` to `PYLON V1` and RS485 `Pylontech` to `PYLON`.
New per-link diagnostics `Inverter link protocol`, `Inverter battery mode` and
`Note`, with a markdown card in the dashboards, alongside a system fault card.
Telemetry: `comm_bus` / `comm_protocol` replaced by `inverter_brand`,
`inverter_bus`, `inverter_protocol` and `inverter_protocol_source`, one slot per
declared link instead of a single value overwritten by the last one.
RS485 packages split: `yambms_rs485.yaml` is the entry point carrying the selects,
`yambms_rs485_pylon.yaml` the protocol implementation. The baud rate is applied
with `set_baud_rate()` + `load_settings()` instead of extending the uart
component, so boards using a UART expander no longer need their own include.
Fixes:
- the CAN bus kept re-emitting the last frame every 100 ms when the protocol was
set to `Disabled` at runtime
- the RS485 link kept answering the inverter with stale data on `Disabled`, the
proxy sensors it reads are now invalidated
- a `Disabled` link no longer lights the fault LED, it is unregistered from the
fault registry instead of being reported as failing
- the reported bus and protocol were overwritten when a node declares several
inverter links
- changing the protocol restarts the CAN frames immediately instead of waiting up
to 30 s for the next retry tick
74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# 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](../YamBMS_LP_YAML.md) and
|
|
[YamBMS_RP_YAML.md](../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 — UART, CAN, PSRAM, LVGL display, WiFi AP — included
|
|
separately depending on the hardware.
|
|
|
|
### `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_inverter_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_inverter_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:
|
|
|
|
- [Charging_logic.md](../Charging_logic.md)
|
|
- [YamBMS_functions.md](../YamBMS_functions.md)
|
|
- [YamBMS_behavior.md](../YamBMS_behavior.md)
|
|
- [Supported_devices.md](../Supported_devices.md) — supported BMS, shunts and inverters.
|