esp32-example.yaml

substitutions:
  name: ecoworthy-bms
  device_description: "Monitor an Ecoworthy BMS via RS485"
  external_components_source: github://rar/esphome-ecoworthy-bms@main
  tx_pin: GPIO16
  rx_pin: GPIO17

esphome:
  name: ${name}
  comment: ${device_description}
  min_version: 2024.6.0
  project:
    name: "rar.esphome-ecoworthy-bms"
    version: 1.0.0

esp32:
  board: wemos_d1_mini32

external_components:
  - source: ${external_components_source}
    refresh: 0s

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

ota:
  platform: esphome

logger:
  level: DEBUG

# Enable Home Assistant API
api:

uart:
  id: uart_0
  # Ecoworthy BMS default baud rate is 9600
  baud_rate: 9600
  tx_pin: ${tx_pin}
  rx_pin: ${rx_pin}
  # Increased RX buffer for large Modbus frames
  rx_buffer_size: 512

ecoworthy_modbus:
  id: modbus0
  uart_id: uart_0

ecoworthy_bms:
  id: bms0
  # Battery address (1-15 for individual batteries, 1 is usually primary)
  address: 0x01
  ecoworthy_modbus_id: modbus0
  update_interval: 10s
  # Number of batteries in the pack (1 = primary only, 2+ = primary + secondary)
  # Secondary batteries are addressed sequentially starting from master address
  battery_count: 1

binary_sensor:
  - platform: ecoworthy_bms
    ecoworthy_bms_id: bms0
    online_status:
      name: "${name} online status"
    charging:
      name: "${name} charging"
    discharging:
      name: "${name} discharging"
    charging_switch:
      name: "${name} charging switch"
    discharging_switch:
      name: "${name} discharging switch"
    balancing:
      name: "${name} balancing"
    # Uncomment below to add secondary battery binary sensors (requires battery_count >= 2)
    # All Pack Status binary sensors are available for secondary batteries
    # batteries:
    #   2:
    #     online_status:
    #       name: "${name} battery 2 online status"
    #     charging:
    #       name: "${name} battery 2 charging"
    #     discharging:
    #       name: "${name} battery 2 discharging"
    #     charging_switch:
    #       name: "${name} battery 2 charging switch"
    #     discharging_switch:
    #       name: "${name} battery 2 discharging switch"
    #     balancing:
    #       name: "${name} battery 2 balancing"

sensor:
  - platform: ecoworthy_bms
    ecoworthy_bms_id: bms0
    
    # Voltage sensors
    total_voltage:
      name: "${name} total voltage"
    min_cell_voltage:
      name: "${name} min cell voltage"
    max_cell_voltage:
      name: "${name} max cell voltage"
    delta_cell_voltage:
      name: "${name} delta cell voltage"
    average_cell_voltage:
      name: "${name} average cell voltage"
    min_voltage_cell:
      name: "${name} min voltage cell"
    max_voltage_cell:
      name: "${name} max voltage cell"
    
    # Individual cell voltages
    cell_voltage_1:
      name: "${name} cell voltage 1"
    cell_voltage_2:
      name: "${name} cell voltage 2"
    cell_voltage_3:
      name: "${name} cell voltage 3"
    cell_voltage_4:
      name: "${name} cell voltage 4"
    cell_voltage_5:
      name: "${name} cell voltage 5"
    cell_voltage_6:
      name: "${name} cell voltage 6"
    cell_voltage_7:
      name: "${name} cell voltage 7"
    cell_voltage_8:
      name: "${name} cell voltage 8"
    cell_voltage_9:
      name: "${name} cell voltage 9"
    cell_voltage_10:
      name: "${name} cell voltage 10"
    cell_voltage_11:
      name: "${name} cell voltage 11"
    cell_voltage_12:
      name: "${name} cell voltage 12"
    cell_voltage_13:
      name: "${name} cell voltage 13"
    cell_voltage_14:
      name: "${name} cell voltage 14"
    cell_voltage_15:
      name: "${name} cell voltage 15"
    cell_voltage_16:
      name: "${name} cell voltage 16"

    # Current and power
    current:
      name: "${name} current"
    power:
      name: "${name} power"
    charging_power:
      name: "${name} charging power"
    discharging_power:
      name: "${name} discharging power"

    # Temperature sensors (JK-BMS naming convention)
    temperature_sensor_1:
      name: "${name} temperature sensor 1"
    temperature_sensor_2:
      name: "${name} temperature sensor 2"
    temperature_sensor_3:
      name: "${name} temperature sensor 3"
    temperature_sensor_4:
      name: "${name} temperature sensor 4"
    power_tube_temperature:
      name: "${name} power tube temperature"
    ambient_temperature:
      name: "${name} ambient temperature"
    min_temperature:
      name: "${name} min temperature"
    max_temperature:
      name: "${name} max temperature"
    avg_temperature:
      name: "${name} avg temperature"

    # Capacity
    remaining_capacity:
      name: "${name} remaining capacity"
    full_capacity:
      name: "${name} full capacity"
    rated_capacity:
      name: "${name} rated capacity"

    # State
    state_of_charge:
      name: "${name} state of charge"
    state_of_health:
      name: "${name} state of health"
    cycle_count:
      name: "${name} cycle count"
    cell_count:
      name: "${name} cell count"
    temperature_sensor_count:
      name: "${name} temperature sensor count"

    # Charge/Discharge limits
    charge_voltage_limit:
      name: "${name} charge voltage limit"
    charge_current_limit:
      name: "${name} charge current limit"
    discharge_voltage_limit:
      name: "${name} discharge voltage limit"
    discharge_current_limit:
      name: "${name} discharge current limit"

    # Bitmasks (useful for advanced diagnostics)
    fault_bitmask:
      name: "${name} fault bitmask"
    alarm_bitmask:
      name: "${name} alarm bitmask"
    mosfet_status_bitmask:
      name: "${name} MOSFET status bitmask"
    balancing_bitmask:
      name: "${name} balancing bitmask"

    # Configuration sensors (from Pack Configuration Parameters)
    balance_voltage:
      name: "${name} balance voltage"
    balance_difference:
      name: "${name} balance difference"
    full_charge_voltage:
      name: "${name} full charge voltage"
    full_charge_current:
      name: "${name} full charge current"
    sleep_voltage:
      name: "${name} sleep voltage"
    sleep_delay:
      name: "${name} sleep delay"
    total_charge:
      name: "${name} total charge"
    total_discharge:
      name: "${name} total discharge"
    configured_cvl:
      name: "${name} configured CVL"
    configured_ccl:
      name: "${name} configured CCL"
    configured_dvl:
      name: "${name} configured DVL"
    configured_dcl:
      name: "${name} configured DCL"

    # Protection threshold sensors (from 0x1800 block - primary only)
    # These show the configured OVP/UVP protection thresholds
    cell_ovp_trigger:
      name: "${name} cell OVP trigger"
    cell_ovp_release:
      name: "${name} cell OVP release"
    cell_uvp_trigger:
      name: "${name} cell UVP trigger"
    cell_uvp_release:
      name: "${name} cell UVP release"
    pack_ovp_trigger:
      name: "${name} pack OVP trigger"
    pack_ovp_release:
      name: "${name} pack OVP release"
    pack_uvp_trigger:
      name: "${name} pack UVP trigger"
    pack_uvp_release:
      name: "${name} pack UVP release"
    
    # Temperature protection thresholds
    charge_ot_trigger:
      name: "${name} charge OT trigger"
    charge_ot_release:
      name: "${name} charge OT release"
    charge_ot_delay:
      name: "${name} charge OT delay"
    charge_ut_trigger:
      name: "${name} charge UT trigger"
    charge_ut_release:
      name: "${name} charge UT release"
    charge_ut_delay:
      name: "${name} charge UT delay"
    discharge_ot_trigger:
      name: "${name} discharge OT trigger"
    discharge_ot_release:
      name: "${name} discharge OT release"
    discharge_ot_delay:
      name: "${name} discharge OT delay"
    discharge_ut_trigger:
      name: "${name} discharge UT trigger"
    discharge_ut_release:
      name: "${name} discharge UT release"
    discharge_ut_delay:
      name: "${name} discharge UT delay"

    # Uncomment below to add secondary battery sensors (requires battery_count >= 2)
    # All Pack Status sensors are available for secondary batteries (same as master except config blocks)
    # batteries:
    #   2:
    #     # Basic monitoring
    #     total_voltage:
    #       name: "${name} battery 2 voltage"
    #     current:
    #       name: "${name} battery 2 current"
    #     power:
    #       name: "${name} battery 2 power"
    #     charging_power:
    #       name: "${name} battery 2 charging power"
    #     discharging_power:
    #       name: "${name} battery 2 discharging power"
    #     state_of_charge:
    #       name: "${name} battery 2 SOC"
    #     state_of_health:
    #       name: "${name} battery 2 SOH"
    #     remaining_capacity:
    #       name: "${name} battery 2 remaining capacity"
    #     full_capacity:
    #       name: "${name} battery 2 full capacity"
    #     rated_capacity:
    #       name: "${name} battery 2 rated capacity"
    #     cycle_count:
    #       name: "${name} battery 2 cycle count"
    #     # Cell voltages
    #     min_cell_voltage:
    #       name: "${name} battery 2 min cell voltage"
    #     max_cell_voltage:
    #       name: "${name} battery 2 max cell voltage"
    #     delta_cell_voltage:
    #       name: "${name} battery 2 delta cell voltage"
    #     average_cell_voltage:
    #       name: "${name} battery 2 average cell voltage"
    #     cell_voltage_1:
    #       name: "${name} battery 2 cell 1"
    #     # ... cell_voltage_2 through cell_voltage_16 also available
    #     # Temperature
    #     power_tube_temperature:
    #       name: "${name} battery 2 MOSFET temp"
    #     ambient_temperature:
    #       name: "${name} battery 2 ambient temp"
    #     min_temperature:
    #       name: "${name} battery 2 min temp"
    #     max_temperature:
    #       name: "${name} battery 2 max temp"
    #     avg_temperature:
    #       name: "${name} battery 2 avg temp"
    #     temperature_sensor_1:
    #       name: "${name} battery 2 temp sensor 1"
    #     # ... temperature_sensor_2 through temperature_sensor_4 also available
    #     # Limits
    #     charge_voltage_limit:
    #       name: "${name} battery 2 CVL"
    #     charge_current_limit:
    #       name: "${name} battery 2 CCL"
    #     discharge_voltage_limit:
    #       name: "${name} battery 2 DVL"
    #     discharge_current_limit:
    #       name: "${name} battery 2 DCL"
    #     # Status
    #     cell_count:
    #       name: "${name} battery 2 cell count"
    #     fault_bitmask:
    #       name: "${name} battery 2 fault bitmask"
    #     alarm_bitmask:
    #       name: "${name} battery 2 alarm bitmask"
    #   3:
    #     total_voltage:
    #       name: "${name} battery 3 voltage"
    #     state_of_charge:
    #       name: "${name} battery 3 SOC"

text_sensor:
  - platform: ecoworthy_bms
    ecoworthy_bms_id: bms0
    operation_status:
      name: "${name} operation status"
    fault:
      name: "${name} fault"
    alarm:
      name: "${name} alarm"
    serial_number:
      name: "${name} serial number"
    firmware_version:
      name: "${name} firmware version"
    bms_serial_number:
      name: "${name} BMS serial number"
    pack_serial_number:
      name: "${name} pack serial number"
    manufacturer:
      name: "${name} manufacturer"
    bms_model:
      name: "${name} BMS model"
    balance_mode:
      name: "${name} balance mode"
    can_protocol:
      name: "${name} CAN protocol"
    rs485_protocol:
      name: "${name} RS485 protocol"
    hardware_version:
      name: "${name} hardware version"
    # Uncomment below to add secondary battery text sensors (requires battery_count >= 2)
    # batteries:
    #   2:
    #     operation_status:
    #       name: "${name} battery 2 operation status"
    #     fault:
    #       name: "${name} battery 2 fault"
    #     alarm:
    #       name: "${name} battery 2 alarm"
    #     serial_number:
    #       name: "${name} battery 2 serial number"
    #     firmware_version:
    #       name: "${name} battery 2 firmware version"

# MOS Control Switches (JK-BMS naming convention)
switch:
  - platform: ecoworthy_bms
    ecoworthy_bms_id: bms0
    charging:
      name: "${name} charging"
    discharging:
      name: "${name} discharging"

# Sleep Mode and Emergency Buttons
button:
  - platform: ecoworthy_bms
    ecoworthy_bms_id: bms0
    standby_sleep:
      name: "${name} standby sleep"
    deep_sleep:
      name: "${name} deep sleep"
    # WARNING: This will immediately disconnect all attached batteries!
    trip:
      name: "${name} trip breaker"