# YamBMS - How to create your YamBMS Local Packages YAML [![Badge License: GPLv3](https://img.shields.io/badge/License-GPLv3-brightgreen.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Badge Version](https://img.shields.io/github/v/release/Sleeper85/esphome-yambms?include_prereleases&color=yellow&logo=DocuSign&logoColor=white)](https://github.com/Sleeper85/esphome-yambms/releases/latest) ![GitHub stars](https://img.shields.io/github/stars/Sleeper85/esphome-yambms) ![GitHub forks](https://img.shields.io/github/forks/Sleeper85/esphome-yambms) ![GitHub watchers](https://img.shields.io/github/watchers/Sleeper85/esphome-yambms) > [!TIP] > Not sure which YAML to choose ? ... [YamBMS_Remote_Packages_example.yaml](../../YamBMS_Remote_Packages_example.yaml) > is a good basis for creating your custom YAML. > Examples of `BMS` and `Shunt` packages can be found in the [examples](../../examples/single-node/) folder. > You don't have to import a shunt but you must import at least `one BMS`. > You can mix different `BMS` models, the only condition is that the `bms_id` are numbered in order starting from `1` ! > [!IMPORTANT] > BMS monitoring with `Bluetooth` as well as the `Web server` are RAM-intensive components. > Please note that enabling these components will take up a lot of memory and may decrease the stability of your ESP32. ## WiFi & Ethernet > [!IMPORTANT] > By default, if the ESP32 is disconnected from the WiFi network it will reboot `every 15 minutes` to try to resolve the problem. > The `wifi` or `ethernet` components are found in the [YAML corresponding to the board](../../packages/board/). Configuring a fixed IP address can be done in the main YAML like this: ### WiFi > [!IMPORTANT] > Don't forget to configure your WiFi credentials in the `secrets.yaml` file. ```YAML wifi: manual_ip: static_ip: 192.168.0.85 gateway: 192.168.0.1 subnet: 255.255.255.0 dns1: 8.8.8.8 dns2: 8.8.4.4 ``` ### Ethernet ```YAML ethernet: manual_ip: static_ip: 192.168.0.85 gateway: 192.168.0.1 subnet: 255.255.255.0 dns1: 8.8.8.8 dns2: 8.8.4.4 ``` ## Home Assistant API > [!IMPORTANT] > If your ESP32 is not connected with Home Assistant it will reboot every 15 minutes. > This is the normal behavior of ESPHome, this is not a bug to be resolved but a mechanism put in place by the ESPHome team to correct a possible problem with the API connection. The **"api:"** section is therefore configured by default not to reboot every 15 minutes if `Home Assistant` is not connected. ```YAML api: reboot_timeout: 0s ``` ## Web Server > [!IMPORTANT] > Please note that enabling this component will take up a lot of memory and may decrease stability and be the cause of reboot depending on the capabilities of the board used. If you don't use `Home Assistant`, you can activate the `Web Server` and have access to YamBMS information and also interact with the application. To do so, include the `yambms_web_server.yaml` package, see [Board options](#board-options). [ESPHome Web Server Component](https://esphome.io/components/web_server.html) ## Importing YamBMS Local Packages Package imports are done below this line: ```YAML packages: ``` ## Board First you need to import the package that corresponds to the `board` you are going to use. There are other `board.yaml` not mentioned here, see in the [board](../../packages/board/) folder. So just one of the packages below : ### ESP32 Generic ```YAML board: !include packages/board/board_ESP32_Generic.yaml ``` ### ESP32 DevKit-V1 ```YAML board: !include packages/board/board_ESP32_DevKit-V1.yaml ``` ### ESP32-S3 DevKitC-1 ```YAML # RGB LED to GPIO 38 board: !include packages/board/board_ESP32-S3_DevKitC-1_LED-38.yaml ``` ```YAML # RGB LED to GPIO 48 board: !include packages/board/board_ESP32-S3_DevKitC-1_LED-48.yaml ``` ### Atom S3 Lite ```YAML board: !include packages/board/board_ESP32-S3_AtomS3-Lite.yaml ``` ### Atom S3 / S3R (display) The screen is a separate package, `board_options_display_128x128.yaml`, to include next to the board. ```YAML board: !include packages/board/board_ESP32-S3_AtomS3.yaml # board: !include packages/board/board_ESP32-S3_AtomS3R.yaml board_display: !include file: packages/board/board_options_display_128x128.yaml vars: display_auto_next_page_interval: '5s' display_rotation: '0' # 0/90/180/270 rotation angle in degrees ``` ### ESP32-C3 DevKitM-1 ```YAML board: !include packages/board/board_ESP32-C3_DevKitM-1.yaml ``` ### ESP32-C3 ETH01-EVO This board has an `Ethernet` port and can be powered from `POE` (optional). ```YAML board: !include packages/board/board_ESP32-C3_ETH01-EVO.yaml ``` ### ESP32 LilyGo T-CAN485 ```YAML board: !include packages/board/board_ESP32_LilyGo-T-CAN485.yaml ``` > [!NOTE] > The device has an integrated 120 Ohm termination resistor. If used as a node in the middle, this resistor must be removed. ![Image](../../images/MCU_ESP32_LilyGo-T-CAN485_resistors.jpg) ### ESP32-S3 LilyGo T-Connect ```YAML board: !include packages/board/board_ESP32-S3_LilyGo-T-Connect.yaml ``` > [!NOTE] > The device has an integrated 120 Ohm termination resistor. If used as a node in the middle, this resistor must be removed. ### ESP32-S3 LilyGo T-Connect Pro ```YAML board: !include packages/board/board_ESP32-S3_LilyGo-T-Connect-Pro.yaml ``` > [!NOTE] > The device has an integrated 120 Ohm termination resistor. If used as a node in the middle, this resistor must be removed. ## Board options Uncomment the options you need. Boards with a screen also need their display package, see the `Board Display` block of the [example YAML](../../YamBMS_Local_Packages_example.yaml). ```YAML # PSRAM octal 80Mhz # psram_octal_80Mhz: !include packages/board/board_options_PSRAM_octal_80Mhz.yaml # Web Server # web_server: !include packages/yambms/yambms_web_server.yaml # WiFi AP @ 192.168.4.1 # wifi_ap: !include packages/board/board_options_wifi_ap.yaml # Captive Portal @ 192.168.4.1 # captive_portal: !include packages/board/board_options_captive_portal.yaml ``` > [!NOTE] > UART and CAN interfaces are not included here. Each package declares its own, from its > `*_uart_id` or `canbus_platform` var. ## YamBMS single-node example ```YAML shunt1: !include file: packages/shunt/shunt_combine_Victron_SmartShunt_UART.yaml vars: shunt_id: '1' # must be a number shunt_name: 'Shunt 1' shunt_uart_id: 'uart_esp_1' # other settings # ... bms1: !include file: packages/bms/bms_combine_JK_UART_4G-GPS_full.yaml vars: bms_id: '1' # must be a number bms_name: 'BMS 1' bms_uart_id: 'uart_esp_2' # other settings # ... bms2: !include file: packages/bms/bms_combine_JBD_BLE_full.yaml vars: bms_id: '2' # must be a number bms_name: 'BMS 2' bms_ble_mac_address: 11:22:33:44:55:77 # other settings # ... balancer1: !include file: packages/balancer/balancer_sensors_JK_NEEY_BLE.yaml vars: bms_id: '1' # must match the BMS ID balancer_name: 'Balancer 1' balancer_ble_mac_address: 11:22:33:44:55:66 ``` ## YamBMS multi-node RS485 modbus example > [!IMPORTANT] > The BMS/Shunt IDs of the `modbus client` must match exactly with the BMS/Shunt IDs of the `modbus server` as in the example below. ### YamBMS modbus client `node1` ```YAML modbus: !include file: packages/board/board_options_itf_modbus.yaml vars: modbus_role: 'client' # client / server modbus_uart_id: 'uart_esp_1' # RS485 board shunt1: !include file: packages/shunt/shunt_combine_modbus_client.yaml # a Shunt connected to a node of the RS485 bus vars: shunt_id: '1' # must be a number, also represents the modbus server number (200 + shunt_id) ! shunt_name: 'Shunt 1' bms1: !include file: packages/bms/bms_combine_modbus_client.yaml # a BMS connected to a node of the RS485 bus vars: bms_id: '1' # must be a number, also represents the modbus server number ! bms_name: 'BMS 1' bms2: !include file: packages/bms/bms_combine_modbus_client.yaml # a BMS connected to a node of the RS485 bus vars: bms_id: '2' # must be a number, also represents the modbus server number ! bms_name: 'BMS 2' bms3: !include file: packages/bms/bms_combine_modbus_client.yaml # a BMS connected to a node of the RS485 bus vars: bms_id: '3' # must be a number, also represents the modbus server number ! bms_name: 'BMS 3' ``` ### ESP32 modbus server `node2` ```YAML modbus: !include file: packages/board/board_options_itf_modbus.yaml vars: modbus_role: 'server' # client / server modbus_uart_id: 'uart_esp_1' # RS485 board shunt1: !include file: packages/shunt/shunt_modbus_Victron_SmartShunt_UART.yaml vars: shunt_id: '1' # must be a number, also represents the modbus server number (200 + shunt_id) ! shunt_name: 'Shunt 1' # other settings # ... bms1: !include file: packages/bms/bms_modbus_JK_UART_4G-GPS_full.yaml vars: bms_id: '1' # must be a number, also represents the modbus server number ! bms_name: 'BMS 1' # other settings # ... balancer1: !include file: packages/balancer/balancer_sensors_JK_NEEY_BLE.yaml vars: bms_id: '1' # must match the BMS ID balancer_name: 'Balancer 1' balancer_ble_mac_address: 11:22:33:44:55:66 ``` ### ESP32 modbus server `node3` ```YAML modbus: !include file: packages/board/board_options_itf_modbus.yaml vars: modbus_role: 'server' # client / server modbus_uart_id: 'uart_esp_1' # RS485 board bms2: !include file: packages/bms/bms_modbus_JK_BLE_standard.yaml vars: bms_id: '2' # must be a number, also represents the modbus server number ! bms_name: 'BMS 2' # other settings # ... bms3: !include file: packages/bms/bms_modbus_JK_BLE_standard.yaml vars: bms_id: '3' # must be a number, also represents the modbus server number ! bms_name: 'BMS 3' # other settings # ... ``` ## BMS > [!IMPORTANT] > You must number your `BMS` in order starting with the number `1`. > [!TIP] > YAML files whose name starts with `bms_combine` are to be used on the main `YamBMS` node connected to your inverter, those whose name starts with `bms_modbus` are to be used on the other nodes connected to the `RS485` bus. The example YAMLs are just examples, you can mix different BMS models without problems. There are other `bms.yaml` not mentioned here, see in the [bms](../../packages/bms/) folder. The `full` / `standard` versions contain all available sensors while the `minimal` version contains the basic sensors without the voltages of each cell and other superfluous sensors. You can find `BMS` import `LP` examples in the [examples/single-node](../../examples/single-node/) folder. ## Shunt > [!IMPORTANT] > You must number your `Shunt` in order starting with the number `1`. > [!TIP] > YAML files whose name starts with `shunt_combine` are to be used on the main `YamBMS` node connected to your inverter, those whose name starts with `shunt_modbus` are to be used on the other nodes connected to the `RS485` bus. As soon as you import a `Shunt` and it can be combined ([see condition](YamBMS_behavior.md#shunt)) the values ​​`Voltage`, `Current`, `Power` and `SoC` of the shunt(s) will take precedence over the BMS values. You can find `Shunt` import `LP` examples in the [examples/single-node](../../examples/single-node/) folder. ## Balancer > [!IMPORTANT] > You must number your `Balancer` with the same number as the `BMS` it is connected to. As soon as the balancer is available/online the values ​​`equalizing` and `balance trigger voltage` of the balancers(s) will take precedence over the BMS values. ## YamBMS > [!TIP] > This package is only used with the `YamBMS` main node. > [!CAUTION] > By default, `YamBMS` is configured with the values ​​for a 16S LFP battery ! Take the time to configure `YamBMS` correctly according to your battery chemistry type `LFP/Li-ion/LTO` and `cell count`. Charging voltages can be changed in the app. The YamBMS settings are `substitutions`, not `vars`, because the other packages read them too (`yambms_id` for instance is used by the CAN and RS485 packages). Set them in the `substitutions:` block at the top of your YAML : ```YAML substitutions: # Please read the cut-off charging logic README to understand how the YamBMS works yambms_id: '1' # Number without spaces yambms_name: 'YamBMS 1' # Prefix for YamBMS entities yambms_update_interval: '1s' # Input numbers can be displayed as a slider or an input box, options are 'slider' or 'box'. yambms_input_number_mode: 'slider' # Please check and fill in the options below correctly according to your battery chemistry and number of cells in series. # These parameters are important and used for charging logic. # Battery Chemistry yambms_battery_chemistry: '1' # 1-LFP | 2-Li-ion | 3-LTO # Number of cells in series yambms_cell_count: '16' # Bulk / Absorption Voltage : corresponds to the Bulk voltage that will be used to charge the battery. (LFP : 55.2V = 3.45V/Cell for 16S battery) yambms_bulk_v: '55.2' # Float Voltage : corresponds to the voltage at which the battery would be maintained at the end of charge. (LFP : 53.6V = 3.35V/Cell for 16S battery) yambms_float_v: '53.6' # Rebulk voltage, voltage from which a new Bulk charge can start. (LFP : 52.8V = 3.3V/Cell for 16S battery) yambms_rebulk_v: '52.8' # Maximum time in minutes that the cut-off step can last before charging is complete # If your cells are properly balanced this step ends at the fastest after the `cut-off timer` # This timer can be deactivated with a switch yambms_eoc_timer: '30' # Time in seconds during which the end of charge conditions must be respected (cut-off + cells not equalizing) yambms_cutoff_timer: '180' # Max. charge current : corresponds to the maximum charge current which may be requested by YamBMS. # The current requested will be proportional to the BMS count without ever exceeding this value. yambms_max_requested_charge_current: '300' # in Ampere # Max. discharge current : corresponds to the maximum discharge current which may be requested by YamBMS. # The current requested will be proportional to the BMS count without ever exceeding this value. yambms_max_requested_discharge_current: '300' # in Ampere ``` Then include the package below `packages:`, with no `vars:` : ```YAML yambms: !include packages/yambms/yambms.yaml ``` ### YamBMS services The update service checks for a newer YamBMS version. The telemetry service sends anonymous data about your setup, see [Telemetry](Telemetry.md). Both are enabled by default and set in the same `substitutions:` block : ```YAML yambms_update_service: 'true' # Set to false to disable update checks yambms_telemetry_service: 'true' # Set to false to disable the sending of telemetry data ``` ## CAN bus to Inverter > [!TIP] > 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. > [!WARNING] > Each declared `CAN` or `RS485` link divides the requested CCL/DCL, even when its `Protocol` is `Disabled`. > Only declare the links actually wired to an inverter/charger, see [Multi-inverter / multi-charger](YamBMS_functions.md#multi-inverter--multi-charger). 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 canbus1: !include file: packages/yambms/yambms_canbus.yaml # file: packages/yambms/yambms_canbus_web_server.yaml vars: canbus_id: '1' # Must be a number canbus_name: 'CANBUS 1' 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 ``` > [!IMPORTANT] > After flashing, select the `Inverter brand` of this link in Home Assistant or the web server. > The link stays inactive until this is done. If your brand is not listed, select `Other` and set > `Protocol` yourself, see [Supported devices](Supported_devices.md). ## RS485 bus to Inverter > [!TIP] > 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 `RS485` bus. > [!WARNING] > Each declared `CAN` or `RS485` link divides the requested CCL/DCL, even when its `Protocol` is `Disabled`. > Only declare the links actually wired to an inverter/charger, see [Multi-inverter / multi-charger](YamBMS_functions.md#multi-inverter--multi-charger). The RS485 bus connected to your inverter via the RS485 transceiver `uart_esp_3`. > [!NOTE] > A package that uses a UART declares it itself from its `*_uart_id` var, so there is no UART to > include separately. Each UART can only be used by one package. If your RS485 transceiver needs a > `flow_control_pin`, add `uart_flow_control_pin: ${talk_pin}` to the `vars:` of that package > (native ESP32 UART only, not on a WK2168 channel). You can keep the default configuration and adapt the `uart` port on which the component must connect. ```YAML rs485_1: !include file: 'packages/yambms/yambms_rs485.yaml' # file: 'packages/yambms/yambms_rs485_web_server.yaml' vars: rs485_id: '1' # Must be a number rs485_name: 'RS485 1' rs485_protocol: 'pylon' # pylon / voltronic rs485_update_timeout: '10s' rs485_status_led_id: 'esp_light' # LED used to show status; default = esp_light, comment out to disable # UART setup rs485_uart_id: 'uart_esp_3' # UART interface to which your inverter is connected # ESP32 : uart_esp_1 to uart_esp_3 # WK2168 : uart_spi_0 to uart_spi_7 / uart_i2c_0 to uart_i2c_7 rs485_uart_baud_rate: '9600' # Default : 9600 / Epever : 115200 ``` > [!IMPORTANT] > After flashing, select the `Inverter brand` of this link in Home Assistant or the web server. > The link stays inactive until this is done. If your brand is not listed, select `Other` and set > `Protocol` yourself, see [Supported devices](Supported_devices.md). ## Debug The `debug` package will add useful information to refer to if problems occur. ```YAML device_debug: !include file: packages/base/device_debug_ESP32.yaml # file: packages/base/device_debug_ESP32_PSRAM.yaml # for ESP32 with PSRAM vars: debug_name: 'Debug' debug_update_interval: '5s' # Size of your PSRAM in bits # 8Mb='8388608' | 6Mb='6291456' | 4Mb='4194304' | 2Mb='2097152' | NoPSRAM='0' debug_psram_size: '8388608' ```