syssi/esphome-jk-bms 3.0.0 on GitHub

This release is a breaking change release. All users must update their YAML configuration. A migration script is provided to automate most of the work.

Migration script

Run this once on your existing YAML file before upgrading to this release:

python3 migrate_v2_to_v3.py your_config.yaml

The script:

Creates a .bak backup before touching anything
Renames all deprecated sensor/text_sensor/number keys automatically
Flags keys that require manual action (see below)
Detects whether your config uses jk_bms (UART), jk_bms_ble (Bluetooth), or both

jk_bms_ble (Bluetooth)

`sensor.errors_bitmask` removed

The numeric sensor.errors_bitmask has been removed entirely. This change cannot be handled by the migration script and requires a manual edit.

Before:

sensor:
  - platform: jk_bms_ble
    errors_bitmask:
      name: "errors bitmask"

After:

text_sensor:
  - platform: jk_bms_ble
    errors_bitmask_hex:
      name: "errors bitmask"

The new sensor publishes the raw error bitmask as a hex string (e.g. 0x00000000). The underlying bitmask was also fixed: byte order was corrected from big-endian to little-endian and extended from 16-bit to 32-bit.

`text_sensor.errors` - error strings changed

The error strings published by text_sensor.errors have changed. Any Home Assistant automations, template sensors, or notification rules that match on specific error text strings will break.

Old strings (selection):

Charge Overtemperature -> now Charge overtemperature
Charge Undertemperature -> now Charge undertemperature
Cell Undervoltage -> now Cell undervoltage
Cell Overvoltage -> now Cell overvoltage (moved from bit 12 to bit 5 - Battery pack overvoltage)
Charge overcurrent protection -> now Charge overcurrent

The error table was also extended to 32 bits, adding 16 new error conditions such as Discharge short circuit, Battery overtemperature, Charging MOSFET abnormal, Discharging MOSFET abnormal, and more.

`binary_sensor.charging_switch` and `binary_sensor.discharging_switch` removed

These binary sensors have been replaced by proper switch entities.

Before:

binary_sensor:
  - platform: jk_bms_ble
    charging_switch:
      name: "charging switch"
    discharging_switch:
      name: "discharging switch"

After:

switch:
  - platform: jk_bms_ble
    charging:
      name: "charging switch"
    discharging:
      name: "discharging switch"

Sensor renames

The migration script handles all of these automatically.

sensor:

Old key	New key
`sensor.balancing`	`sensor.balancer_status_bitmask`
`sensor.balancer_status`	`sensor.balancer_status_bitmask`
`sensor.power_tube_temperature`	`sensor.mosfet_temperature`
`sensor.power_tube_overtemperature_protection`	`sensor.mosfet_overtemperature_protection`
`sensor.power_tube_overtemperature_protection_recovery`	`sensor.mosfet_overtemperature_protection_recovery`
`sensor.total_battery_capacity_setting`	`sensor.full_charge_capacity`
`sensor.detail_log_count`	`sensor.detail_log_entry_count`

number:

Old key	New key
`number.balance_starting_voltage`	`number.balancing_start_voltage`
`number.power_tube_overtemperature_protection`	`number.mosfet_overtemperature_protection`
`number.power_tube_overtemperature_protection_recovery`	`number.mosfet_overtemperature_protection_recovery`

text_sensor:

Old key	New key
`text_sensor.operation_status`	`text_sensor.balancer_status`

New sensors

Key	Description
`text_sensor.balancer_status`	Publishes `"Balancing"` or `"Idle"`. Available for both JK02 and JK04 protocol. Replaces `text_sensor.operation_status`.
`sensor.balancer_status_bitmask`	Raw numeric balancer status value (0 = off, 1/2/3 = active).
`text_sensor.errors_bitmask_hex`	Raw 32-bit error bitmask as hex string. Replaces the removed `sensor.errors_bitmask`.
`text_sensor.battery_type`	Battery chemistry as a human-readable string.
`sensor.battery_type_id`	Battery type as a numeric ID.

jk_bms (UART/RS485)

`text_sensor.errors` - error strings changed

The UART component's error strings have been aligned with the BLE component terminology.

Old strings (selection):

Cell pressure difference -> now Cell voltage difference
Battery box overtemperature -> no change
309_A protection -> no change

Any automations matching on these exact strings need to be reviewed.

`binary_sensor.charging_switch` and `binary_sensor.discharging_switch` removed

These binary sensors have been replaced by proper switch entities.

Before:

binary_sensor:
  - platform: jk_bms
    charging_switch:
      name: "charging switch"
    discharging_switch:
      name: "discharging switch"

After:

switch:
  - platform: jk_bms
    charging:
      name: "charging switch"
    discharging:
      name: "discharging switch"

Sensor renames

The migration script handles all of these automatically.

sensor: - operational sensors

Old key	New key	Notes
`sensor.capacity_remaining`	`sensor.state_of_charge`	Was: SOC in %
`sensor.capacity_remaining_derived`	`sensor.capacity_remaining`	Was: remaining capacity in Ah
`sensor.battery_strings`	`sensor.cell_count`
`sensor.temperature_sensors`	`sensor.temperature_sensor_count`
`sensor.alarm_low_volume`	`sensor.low_soc_alarm_threshold`
`sensor.low_soc_alarm`	`sensor.low_soc_alarm_threshold`
`sensor.total_battery_capacity_setting`	`sensor.full_charge_capacity`
`sensor.power_tube_temperature`	`sensor.mosfet_temperature`
`sensor.balance_starting_voltage`	`sensor.balancing_start_voltage`
`sensor.balance_opening_pressure_difference`	`sensor.balancing_delta_voltage`
`sensor.cell_pressure_difference_protection`	`sensor.cell_voltage_difference_protection`

Note: sensor.capacity_remaining now refers to the remaining capacity in Ah (previously sensor.capacity_remaining_derived). If you use this sensor in Home Assistant energy dashboards or automations, verify the unit and meaning after migration.

sensor: - protection thresholds

Old key	New key
`sensor.power_tube_temperature_protection`	`sensor.mosfet_overtemperature_protection`
`sensor.power_tube_temperature_recovery`	`sensor.mosfet_overtemperature_recovery`
`sensor.mosfet_temperature_protection`	`sensor.mosfet_overtemperature_protection`
`sensor.mosfet_temperature_recovery`	`sensor.mosfet_overtemperature_recovery`
`sensor.temperature_sensor_temperature_protection`	`sensor.battery_overtemperature_protection`
`sensor.temperature_sensor_temperature_recovery`	`sensor.battery_overtemperature_recovery`
`sensor.temperature_sensor_temperature_difference_protection`	`sensor.battery_temperature_difference_protection`
`sensor.charging_high_temperature_protection`	`sensor.charging_overtemperature_protection`
`sensor.charging_low_temperature_protection`	`sensor.charging_undertemperature_protection`
`sensor.charging_low_temperature_recovery`	`sensor.charging_undertemperature_recovery`
`sensor.discharging_high_temperature_protection`	`sensor.discharging_overtemperature_protection`
`sensor.discharging_low_temperature_protection`	`sensor.discharging_undertemperature_protection`
`sensor.discharging_low_temperature_recovery`	`sensor.discharging_undertemperature_recovery`

What's Changed

BREAKING: Correct little-endian error bitmask reading, extend to 32-bit by @syssi in #568
BREAKING: Rename jk_bms error strings to align with jk_bms_ble terminology by @syssi in #982
BREAKING: Remove deprecated charging_switch and discharging_switch binary sensors by @syssi in #983
Rename cell_pressure_difference_protection sensor to cell_voltage_difference_protection by @syssi in #969
Rename balance_opening_pressure_difference sensor to balancing_delta_voltage by @syssi in #968
Rename capacity_remaining sensor to state_of_charge by @syssi in #971
Rename capacity_remaining_derived sensor to capacity_remaining by @syssi in #972
Rename battery_strings sensor to cell_count by @syssi in #973
Rename temperature_sensors sensor to temperature_sensor_count by @syssi in #974
Add deprecation compat layer for renamed sensors by @syssi in #975
Rename power_tube_temperature sensors to mosfet_temperature by @syssi in #976
Rename temperature_sensor_temperature_* sensors to battery_temperature_* by @syssi in #977
Rename balance_starting_voltage to balancing_start_voltage by @syssi in #978
Rename UART temperature protection/recovery sensors by @syssi in #981
Rename low_soc_alarm sensor to low_soc_alarm_threshold by @syssi in #984
Rename detail_log_count to detail_log_entry_count by @syssi in #985
Refactor balancer status sensors for JK02/JK04 protocol parity by @syssi in #986
Remove dead charging_sensor_ and discharging_sensor_ from jk_bms by @syssi in #987
Add v2-to-v3 YAML config migration script by @syssi in #988
Remove capacity_remaining from _RENAMED_SENSORS by @syssi in #989

Full Changelog: 2.5.0...3.0.0

syssi/esphome-jk-bms 3.0.0 on GitHub

Migration script

jk_bms_ble (Bluetooth)

sensor.errors_bitmask removed

text_sensor.errors - error strings changed

binary_sensor.charging_switch and binary_sensor.discharging_switch removed

Sensor renames

New sensors

jk_bms (UART/RS485)

text_sensor.errors - error strings changed

binary_sensor.charging_switch and binary_sensor.discharging_switch removed

Sensor renames

What's Changed

syssi/esphome-jk-bms 3.0.0
on GitHub

`sensor.errors_bitmask` removed

`text_sensor.errors` - error strings changed

`binary_sensor.charging_switch` and `binary_sensor.discharging_switch` removed

`text_sensor.errors` - error strings changed

`binary_sensor.charging_switch` and `binary_sensor.discharging_switch` removed