Files
esphome-yambms/documents/README/YamBMS_LP_YAML.md
T
Sleeper85 faad9e60ce YamBMS 1.8.1 LP/RP examples
Update the root YAML and the examples for the UART and CAN declarations, the
RS485 block and the Board Options section.
2026-11-08 23:08:34 +01:00

20 KiB
Raw Blame History

YamBMS - How to create your YamBMS Local Packages YAML

Badge License: GPLv3 Badge Version GitHub stars GitHub forks GitHub watchers

Tip

Not sure which YAML to choose ? ... 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 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.

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.

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

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.

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.

ESPHome Web Server Component

Importing YamBMS Local Packages

Package imports are done below this line:

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 folder.

So just one of the packages below :

ESP32 Generic

  board: !include packages/board/board_ESP32_Generic.yaml

ESP32 DevKit-V1

  board: !include packages/board/board_ESP32_DevKit-V1.yaml

ESP32-S3 DevKitC-1

  # RGB LED to GPIO 38
  board: !include packages/board/board_ESP32-S3_DevKitC-1_LED-38.yaml
  # RGB LED to GPIO 48
  board: !include packages/board/board_ESP32-S3_DevKitC-1_LED-48.yaml

Atom S3 Lite

  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.

  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

  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).

  board: !include packages/board/board_ESP32-C3_ETH01-EVO.yaml

ESP32 LilyGo T-CAN485

  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

ESP32-S3 LilyGo T-Connect

  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

  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.

  # 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

  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

  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

  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

  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 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 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) 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 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 :

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: :

  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. Both are enabled by default and set in the same substitutions: block :

  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.

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.

  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.

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.

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.

  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.

Debug

The debug package will add useful information to refer to if problems occur.

  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'