From 58c03ac83ff439fd8cac2ce6f95915e4b4221cc3 Mon Sep 17 00:00:00 2001 From: Sleeper85 Date: Thu, 5 Nov 2026 22:18:11 +0100 Subject: [PATCH] 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. --- documents/README/YamBMS_LP_YAML.md | 30 +++++++--- documents/README/YamBMS_RP_YAML.md | 26 +++++--- documents/README/YamBMS_behavior.md | 5 +- documents/README/changelog/Changelog.md | 2 + documents/README/dev/Coding_conventions.md | 17 ++++++ documents/README/dev/Design_decisions.md | 59 +++++++++++++++++++ documents/README/dev/Project_structure.md | 4 ++ .../bms/bms_sensors_DEYE_CAN_top_full.yaml | 11 +++- .../bms/bms_sensors_DEYE_CAN_top_minimal.yaml | 11 +++- .../board/board_ESP32-P4_M5Stack-Tab5.yaml | 4 +- .../board_options_itf_canbus_esp32_can.yaml | 15 ++--- .../board_options_itf_canbus_external.yaml | 24 ++++++++ .../board_options_itf_canbus_mcp2515.yaml | 25 ++++---- packages/yambms/yambms_canbus.yaml | 6 ++ 14 files changed, 192 insertions(+), 47 deletions(-) create mode 100644 packages/board/board_options_itf_canbus_external.yaml diff --git a/documents/README/YamBMS_LP_YAML.md b/documents/README/YamBMS_LP_YAML.md index 16828a5..ff339b3 100644 --- a/documents/README/YamBMS_LP_YAML.md +++ b/documents/README/YamBMS_LP_YAML.md @@ -396,22 +396,34 @@ Take the time to configure `YamBMS` correctly according to your battery chemistr > This package is only used with the `YamBMS` main node. > It's possible to use this package multiple times in order to send information on two different `CAN` bus. -You can keep the default configuration and adapt the `canbus` node on which the component must connect. +The CAN bus connected to your inverter via the CAN transceiver `canbus_inverter_1`. -You can keep the default configuration. +> [!NOTE] +> A package that uses a CAN bus declares its node itself, so there is no CAN interface to include +> separately. `canbus_platform` selects the controller and has no default : +> +> - `esp32_can` : CAN controller of the ESP32, with a TJA105x, SN65HVD230 or M5Stack CAN base/unit transceiver. +> - `mcp2515` : MCP2515 module on the SPI bus. +> - `external` : the node is already declared, by the board (espBerry) or by another package. This +> is what a second link on the same node must use. + +You can keep the default configuration and adapt the `canbus` node on which the component must connect. ```YAML canbus1: !include file: packages/yambms/yambms_canbus.yaml + # file: packages/yambms/yambms_canbus_web_server.yaml vars: - # CANBUS vars - canbus_id: 'canbus1' + canbus_id: '1' # Must be a number canbus_name: 'CANBUS 1' - canbus_node_id: 'canbus_inverter_1' - canbus_light_id: 'esp_light' - # The CANBUS link will be considered down if no response from the inverter (ID 0x305) for 5s - # The Deye inverter sends the ACK (can_id 0x305) only when it receives the can_id 0x356 - canbus_link_timer: '5s' + canbus_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable + # CAN frames sending will be paused for `30s` if the inverter does not respond with an ACK (can_id 0x305) before the end of the `canbus_link_timer` (5s by default). + canbus_link_timer_enabled: 'true' # Set it to 'false' if your inverter/charger is not sending ACK (can_id 0x305) every `1s` as specified by the protocol + canbus_link_timer: '10s' # min 6s with Deye + # CAN setup + canbus_platform: 'esp32_can' # esp32_can / mcp2515 + canbus_node_id: 'canbus_inverter_1' # CAN bus node to which your inverter is connected + canbus_bitrate: '500kbps' # Default : 500kbps ``` # RS485 bus to Inverter diff --git a/documents/README/YamBMS_RP_YAML.md b/documents/README/YamBMS_RP_YAML.md index 823a6db..887afd9 100644 --- a/documents/README/YamBMS_RP_YAML.md +++ b/documents/README/YamBMS_RP_YAML.md @@ -407,6 +407,15 @@ Take the time to configure `YamBMS` correctly according to your battery chemistr The CAN bus connected to your inverter via the CAN transceiver `canbus_inverter_1`. +> [!NOTE] +> A package that uses a CAN bus declares its node itself, so there is no CAN interface to include +> separately. `canbus_platform` selects the controller and has no default : +> +> - `esp32_can` : CAN controller of the ESP32, with a TJA105x, SN65HVD230 or M5Stack CAN base/unit transceiver. +> - `mcp2515` : MCP2515 module on the SPI bus. +> - `external` : the node is already declared, by the board (espBerry) or by another package. This +> is what a second link on the same node must use. + You can keep the default configuration and adapt the `canbus` node on which the component must connect. ```YAML @@ -415,15 +424,18 @@ You can keep the default configuration and adapt the `canbus` node on which the ref: main refresh: 0s files: - - path: 'packages/yambms/yambms_canbus.yaml' + - path: 'packages/yambms/yambms_canbus.yaml' # yambms_canbus_web_server.yaml vars: - canbus_id: 'canbus1' + canbus_id: '1' # must be a number canbus_name: 'CANBUS 1' - canbus_node_id: 'canbus_inverter_1' - canbus_light_id: 'esp_light' - # The CANBUS link will be considered down if no response from the inverter (0x305 frame) for 5s - # The Deye inverter sends the ACK 0x305 only when it receives the 0x356 frame. - canbus_link_timer: '5s' + canbus_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable + # CAN frames sending will be paused for `30s` if the inverter does not respond with an ACK (can_id 0x305) before the end of the `canbus_link_timer` (5s by default). + canbus_link_timer_enabled: 'true' # Set it to 'false' if your inverter/charger is not sending ACK (can_id 0x305) every `1s` as specified by the protocol + canbus_link_timer: '10s' # min 6s with Deye + # CAN setup + canbus_platform: 'esp32_can' # esp32_can / mcp2515 + canbus_node_id: 'canbus_inverter_1' # CAN bus node to which your inverter is connected + canbus_bitrate: '500kbps' # Default : 500kbps ``` # RS485 bus to Inverter diff --git a/documents/README/YamBMS_behavior.md b/documents/README/YamBMS_behavior.md index 1d0c783..257577d 100644 --- a/documents/README/YamBMS_behavior.md +++ b/documents/README/YamBMS_behavior.md @@ -192,11 +192,14 @@ The Deye inverter sends the ACK (can_id `0x305`) only when it receives the can_i vars: canbus_id: '1' # must be a number canbus_name: 'CANBUS 1' - canbus_node_id: 'canbus_inverter_1' # CAN bus node to which your inverter is connected canbus_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable # The CAN bus link will be paused for `30s` if the inverter does not respond with an ACK (can_id 0x305) # before the end of the `canbus_link_timer` (5s by default). canbus_link_timer: '5s' + # CAN setup + canbus_platform: 'esp32_can' # esp32_can / mcp2515 + canbus_node_id: 'canbus_inverter_1' # CAN bus node to which your inverter is connected + canbus_bitrate: '500kbps' # Default : 500kbps ``` ## Warning & Alarms diff --git a/documents/README/changelog/Changelog.md b/documents/README/changelog/Changelog.md index 841a715..8ef49c3 100644 --- a/documents/README/changelog/Changelog.md +++ b/documents/README/changelog/Changelog.md @@ -17,6 +17,8 @@ * New `uart_flow_control_pin` var on any package using a native ESP32 UART, which replaces the `board_options_itf_uart_flow_control.yaml` include ; the `_talk_pin` packages stay available for the rare setups that need them but are no longer shown in the examples * WK2168 channels are now declared the same way : `board_options_itf_wk2168_spi.yaml` or `board_options_itf_wk2168_i2c.yaml` replaces the PVbrain2 files in your YAML, the `uartN_baudrate` substitutions and `uart_hub_bus` are removed (write `uart_spi_3`), and `board_options_itf_modbus_expander.yaml` and `shunt_combine_Victron_SmartShunt_UART_expander.yaml` are removed + * **Breaking change** - A package that uses a CAN bus now declares its node itself : remove the `board_options_itf_canbus_*.yaml` includes from your YAML, otherwise ESPHome reports `ID canbus_inverter_1 redefined`, and add `canbus_platform` (`esp32_can` or `mcp2515`) to the `yambms_canbus.yaml` package and to the Deye `top` package. A node declared by the board, or a second link on the same node, uses `canbus_platform: 'external'` + * The CAN bit rate is set with the new `canbus_bitrate` var (default `500kbps`), which replaces `esp32_canbus_bitrate` and `mcp2515_canbus_bitrate` * RS485 packages reorganised for the additional protocols to come : the file you include changes from `yambms_rs485_pylon.yaml` to `yambms_rs485.yaml`, which now takes a `rs485_protocol` var (`pylon` or `voltronic`) and includes the matching protocol implementation for you ; a node with several RS485 links on different UARTs can run a different protocol on each, one var per link ; `yambms_rs485_pylon_web_server.yaml` becomes `yambms_rs485_web_server.yaml` and must now be included alongside the entry point with its own `rs485_id`, instead of swapping one for the other, see [release note](documents/README/changelog/Changelog_Inverter_brand_and_protocol.md) * New diagnostic entities per inverter link : `Inverter link protocol` (what the link is actually doing, e.g. `Solis - CAN SMA`), `Inverter battery mode` (how to configure the battery type on the inverter, keyed on brand *and* protocol so that forcing a protocol never displays a wrong instruction) and `Note` (what is specific to that brand and protocol) diff --git a/documents/README/dev/Coding_conventions.md b/documents/README/dev/Coding_conventions.md index 29ad424..897fde7 100644 --- a/documents/README/dev/Coding_conventions.md +++ b/documents/README/dev/Coding_conventions.md @@ -68,6 +68,23 @@ Use `| default(...)` when the device has a usual speed, and leave it out when th 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 `${xxx_id}_`: diff --git a/documents/README/dev/Design_decisions.md b/documents/README/dev/Design_decisions.md index 15223bc..f1ccde5 100644 --- a/documents/README/dev/Design_decisions.md +++ b/documents/README/dev/Design_decisions.md @@ -459,6 +459,65 @@ Everywhere else `uart_flow_control_pin` replaces them, and the examples no longe The UART id must be readable when the `!include` filename is resolved. A value built from a substitution declared in a package, such as `uart_${uart_hub_bus}_3`, is not, so write `uart_spi_3`. +## A CAN node is declared by the package that consumes it + +**Files:** `packages/board/board_options_itf_canbus_*.yaml`, `packages/yambms/yambms_canbus.yaml`, +`packages/bms/bms_sensors_DEYE_CAN_top_*.yaml` + +Same principle as the UART: the main YAML describes a link once, in the `vars:` of the package that +uses it. The mechanism is not the same, and the differences are deliberate. + +### The file is picked by platform, not by id + +`uart_esp_1` is bound to pins and says nothing about what is connected. A CAN node is the reverse: +its id is a role (`canbus_inverter_1`, `canbus_bms_1`) that users read and reuse, and the hardware +behind it is either of two controllers. Naming the file after the id would have replaced those +roles with `canbus_esp_1`-style names for no gain. + +So the id stays free in `canbus_node_id` and `canbus_platform` picks the file, the way +`rs485_protocol` picks the RS485 implementation. + +### `canbus_platform` has no default + +A wrong default is valid configuration on the wrong pins, and it fails silently on the wire. A +missing key fails validation instead, with `Cannot load include with unresolved substitutions`. + +### `external` declares nothing + +The import is unconditional, so a node that already exists needs a file that adds nothing: + +- the espBerry board declares its two nodes in its own board file ; +- a second link on the same node would otherwise fail with `ID canbus_inverter_1 redefined`. + +`board_options_itf_canbus_external.yaml` is that file. `canbus_bitrate` has no effect there, the +bit rate is the one of the package or board that declares the node. + +### One importer per node + +As with a UART, two imports of the same node fail, and that should stay so. This is why only the +Deye `top` packages import the node: the `module` packages are included several times on one bus +and only add `on_frame` triggers with `!extend`. + +In the Deye packages `canbus_id` holds a node id, while in `yambms_canbus.yaml` it is a number. The +`top` packages map it with `canbus_node_id: ${canbus_id}` so that the examples keep their key. + +`board_options_itf_canbus_mcp2515.yaml` declares its own `spi:` bus, so importing it twice fails +with `ID mcp2515_spi_bus redefined`. A board with two MCP2515 declares them itself and uses +`external`, as the espBerry does. + +### `canbus_bit_rate` stays internal + +The reasoning is the UART one: the default lives in the `| default()` of the consumer, not in the +CAN file nor in `substitutions:`. `esp32_canbus_bitrate` and `mcp2515_canbus_bitrate` were removed, +the bit rate is not a property of the controller but of the bus. + +### The bit rate is set at compile time, the protocol is not + +`canbus_bitrate` is compiled in, and nothing in YamBMS changes it at runtime, while the `Protocol` +select does change at runtime. So a protocol that does not run at 500 kbps cannot work from the +select alone: the user must also set `canbus_bitrate`. Any such protocol needs a `Note` in +`yambms_brand_registry.yaml` that says so. + ## Empirical constants Some constants were found by trial on real hardware and must not be rounded or harmonised. diff --git a/documents/README/dev/Project_structure.md b/documents/README/dev/Project_structure.md index a8eece4..ab86372 100644 --- a/documents/README/dev/Project_structure.md +++ b/documents/README/dev/Project_structure.md @@ -43,6 +43,10 @@ YAML. Each one declares a single UART (`uart_esp_N`, `uart_N` on the RPi Pico, ` `*_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: diff --git a/packages/bms/bms_sensors_DEYE_CAN_top_full.yaml b/packages/bms/bms_sensors_DEYE_CAN_top_full.yaml index a00843f..9bf7bd5 100644 --- a/packages/bms/bms_sensors_DEYE_CAN_top_full.yaml +++ b/packages/bms/bms_sensors_DEYE_CAN_top_full.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.10.18 -# Version : 1.1.7 +# Updated : 2026.11.05 +# Version : 1.1.8 # GitHub : https://github.com/GHswitt/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -17,6 +17,13 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +packages: + canbus_node: !include + file: ../board/board_options_itf_canbus_${canbus_platform}.yaml + vars: + canbus_node_id: ${canbus_id} + canbus_bit_rate: ${canbus_bitrate | default('500kbps')} + esphome: # sub device devices: diff --git a/packages/bms/bms_sensors_DEYE_CAN_top_minimal.yaml b/packages/bms/bms_sensors_DEYE_CAN_top_minimal.yaml index e11f083..daa209c 100644 --- a/packages/bms/bms_sensors_DEYE_CAN_top_minimal.yaml +++ b/packages/bms/bms_sensors_DEYE_CAN_top_minimal.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.10.18 -# Version : 1.1.7 +# Updated : 2026.11.05 +# Version : 1.1.8 # GitHub : https://github.com/GHswitt/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -17,6 +17,13 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +packages: + canbus_node: !include + file: ../board/board_options_itf_canbus_${canbus_platform}.yaml + vars: + canbus_node_id: ${canbus_id} + canbus_bit_rate: ${canbus_bitrate | default('500kbps')} + esphome: # sub device devices: diff --git a/packages/board/board_ESP32-P4_M5Stack-Tab5.yaml b/packages/board/board_ESP32-P4_M5Stack-Tab5.yaml index 0d6652e..9233974 100644 --- a/packages/board/board_ESP32-P4_M5Stack-Tab5.yaml +++ b/packages/board/board_ESP32-P4_M5Stack-Tab5.yaml @@ -31,7 +31,7 @@ # | - MCP2515 CAN controller (SPI): MOSI=G18, MISO=G19, SCK=G5, CS=G2, INT=G47 # | - RS485 (SP3485): TX=G6, RX=G7 (uses Port C pins on M5-Bus) # | - TTL UART: TX=G37, RX=G38 (uses UART0 pins on M5-Bus) -# | Include board_options_itf_canbus_mcp2515.yaml for CAN +# | Set canbus_platform: 'mcp2515' for CAN # | Include board_options_itf_modbus.yaml with modbus_uart_id: uart_esp_1 for RS485 # | # +--------------------------------------------------------------------------------------------+ @@ -40,7 +40,7 @@ # | The DIN BASE provides Port.A and Port.B for native TWAI CAN (requires CAN transceiver unit): # | - Port.A: PA_IN=G53, PA_OUT=G54 (M5-Bus pins 2,3) # | - Port.B: PB_IN=G17, PB_OUT=G52 (M5-Bus pins 4,10) -# | Include board_options_itf_canbus_esp32_can.yaml for native CAN +# | Set canbus_platform: 'esp32_can' for native CAN # | Recommended: Use M5Stack CAN Unit (U085) or PwrCAN Module (M013.2) on Port.A or Port.B # | # +--------------------------------------------------------------------------------------------+ diff --git a/packages/board/board_options_itf_canbus_esp32_can.yaml b/packages/board/board_options_itf_canbus_esp32_can.yaml index 08c542e..0cdbeae 100644 --- a/packages/board/board_options_itf_canbus_esp32_can.yaml +++ b/packages/board/board_options_itf_canbus_esp32_can.yaml @@ -1,5 +1,5 @@ -# Updated : 2025.08.03 -# Version : 1.1.3 +# Updated : 2026.11.05 +# Version : 1.1.4 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -17,16 +17,13 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -# The settings below can be changed via `vars` when importing the package -# or by declaring new `substitutions` in the main YAML -substitutions: - esp32_canbus_id: '1' - esp32_canbus_bitrate: '500kbps' +# Imported by the package that consumes this CAN node, which passes `canbus_node_id` and +# `canbus_bit_rate`. Optional var of that import : `esp32_canbus_id`. canbus: - platform: esp32_can id: ${canbus_node_id} tx_pin: ${tx_pin_4} rx_pin: ${rx_pin_4} - can_id: ${esp32_canbus_id} - bit_rate: ${esp32_canbus_bitrate} + can_id: ${esp32_canbus_id | default(1)} + bit_rate: ${canbus_bit_rate} diff --git a/packages/board/board_options_itf_canbus_external.yaml b/packages/board/board_options_itf_canbus_external.yaml new file mode 100644 index 0000000..2f52ee4 --- /dev/null +++ b/packages/board/board_options_itf_canbus_external.yaml @@ -0,0 +1,24 @@ +# Updated : 2026.11.05 +# Version : 1.1.1 +# GitHub : https://github.com/Sleeper85/esphome-yambms + +# YamBMS ( Yet another multi-BMS Merging Solution ) + +# This YAML is free software: you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation, either version 3 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +# See the GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +# `canbus_platform: 'external'` : the CAN node is declared elsewhere, so this file declares +# nothing. It is used for a node declared by the board file (espBerry) or already imported by +# another package (a second link on the same node). + +{} diff --git a/packages/board/board_options_itf_canbus_mcp2515.yaml b/packages/board/board_options_itf_canbus_mcp2515.yaml index 6213017..77bf45b 100644 --- a/packages/board/board_options_itf_canbus_mcp2515.yaml +++ b/packages/board/board_options_itf_canbus_mcp2515.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.02.05 -# Version : 1.1.6 +# Updated : 2026.11.05 +# Version : 1.1.7 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -17,17 +17,12 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -# The settings below can be changed via `vars` when importing the package -# or by declaring new `substitutions` in the main YAML. - -substitutions: - mcp2515_spi_id: 'mcp2515_spi_bus' - mcp2515_canbus_id: '2' - mcp2515_canbus_bitrate: '500kbps' - mcp2515_clock: '8MHz' +# Imported by the package that consumes this CAN node, which passes `canbus_node_id` and +# `canbus_bit_rate`. Optional vars of that import : `mcp2515_spi_id`, `mcp2515_canbus_id`, +# `mcp2515_clock`. spi: - - id: ${mcp2515_spi_id} + - id: ${mcp2515_spi_id | default('mcp2515_spi_bus')} mosi_pin: ${spi_mosi_pin} miso_pin: ${spi_miso_pin} clk_pin: ${spi_clk_pin} @@ -35,9 +30,9 @@ spi: canbus: - platform: mcp2515 - spi_id: ${mcp2515_spi_id} + spi_id: ${mcp2515_spi_id | default('mcp2515_spi_bus')} id: ${canbus_node_id} cs_pin: ${mcp2515_cs_pin} - can_id: ${mcp2515_canbus_id} - bit_rate: ${mcp2515_canbus_bitrate} - clock: ${mcp2515_clock} # Default MCP2515 clock is 8MHz; many boards use 16MHz + can_id: ${mcp2515_canbus_id | default(2)} + bit_rate: ${canbus_bit_rate} + clock: ${mcp2515_clock | default('8MHz')} # Default MCP2515 clock is 8MHz; many boards use 16MHz diff --git a/packages/yambms/yambms_canbus.yaml b/packages/yambms/yambms_canbus.yaml index bcf47ac..1af3223 100644 --- a/packages/yambms/yambms_canbus.yaml +++ b/packages/yambms/yambms_canbus.yaml @@ -17,6 +17,12 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +packages: + canbus_node: !include + file: ../board/board_options_itf_canbus_${canbus_platform}.yaml + vars: + canbus_bit_rate: ${canbus_bitrate | default('500kbps')} + substitutions: canbus_status_led_id: "virtual_status_light" # The ID of the LED on your board used for this component canbus_link_timer_enabled: 'true' # Set it to 'false' if your inverter/charger is not sending ACK (can_id 0x305) every `1s` as specified by the protocol