This release requires ESPHome 2026.1.0 or higher. It contains a few small breaking changes; most configurations will keep working without changes. Please review the sections below before upgrading.
Breaking changes
Minimum ESPHome version raised to 2026.1.0
All components now require ESPHome 2026.1.0 or newer (previously between 2024.12.0 and 2025.11.0, depending on the component). Older ESPHome versions will fail config validation.
The multi-device examples additionally use the sub-device relation feature and require ESPHome 2026.11.0.
jk_balancer / heltec_balancer_ble: current and power sensors removed
The active balancers cannot measure the battery current. The current sensor (jk_balancer, heltec_balancer_ble) and the power sensor (jk_balancer) never published meaningful values and have been removed. Remove these keys from your YAML, otherwise config validation will fail.
Before:
sensor:
- platform: jk_balancer
current:
name: "current"
power:
name: "power"After: remove both entries.
jk_bms_display: UART settings are validated at compile time
The deprecated runtime check_uart_settings() call has been replaced by final_validate_device_schema. A UART bus that is not configured as 2400 baud, 8N1 with an rx_pin is now rejected during config validation instead of logging a warning at runtime.
Number entities: invalid limits are rejected
jk_bms_ble, jk_balancer and heltec_balancer_ble number entities now reject configurations where min_value is greater than max_value, step is zero or negative, or a value is not finite.
Deprecated and new option names can no longer be combined
jk_bms and jk_bms_ble still accept the deprecated option names from 2.x with a warning. Specifying both the deprecated and the new name of the same option (e.g. power_tube_temperature and mosfet_temperature) is now an error instead of silently using one of them.
Switch and button entities no longer derive from Component
The switch and button entities of all components are now plain entities. This only affects custom lambdas or C++ code that call Component methods on these entities.
JK-PB Modbus example (esp32-jk-pb-modbus-example.yaml)
The example has seen many improvements. Some entities were renamed, which changes the entity IDs in Home Assistant:
| Old name | New name |
|---|---|
balancing
| balancer
|
max voltage cell number
| max voltage cell
|
min voltage cell number
| min voltage cell
|
capacity remaining derived
| capacity remaining
|
actual battery capacity
| full charge capacity
|
disacharge OCPR left
| discharge OCPR left
|
disacharge SCPR left
| discharge SCPR left
|
charging, discharging and balancer are now exposed as switches (like the BLE component and compatible with the JK BMS card). The underlying selects are internal.
Further changes:
- New sensors:
max cell voltage,min cell voltage,average cell voltage,heating active,heating start temperature,heating stop temperature - Fixed RCV/RFV time and balancing bytes
- Fixed units and device classes to avoid Home Assistant discovery warnings
- Removed
register_count,skip_updatesandcommand_throttle
The multi-device BLE examples also dropped the redundant BMS prefix from their entity names.
jk_bms_ble (Bluetooth)
New entities
| Key | Description |
|---|---|
text_sensor.device_model
| Device model from the device info frame |
text_sensor.manufacturing_date
| Manufacturing date (YYYY-MM-DD)
|
text_sensor.serial_number
| Serial number |
text_sensor.device_name
| User defined device name |
sensor.device_address
| User defined device address |
sensor.power_on_count
| Power on counter |
sensor.smart_sleep_countdown
| Remaining time until smart sleep (JK02_32S) |
sensor.uart1_protocols_enabled_bitmask, uart2_…, uart3_…, can_protocols_enabled_bitmask
| Enabled protocols per port (JK02_32S) |
number.smart_sleep_delay
| Smart sleep delay (JK02_32S) |
number.emergency_duration
| Emergency duration (JK02_32S) |
number.soc_calibration, number.soh_calibration
| SOC / SOH calibration (JK02_32S) |
select.uart1_protocol, uart2_protocol, uart3_protocol, can_protocol
| Communication protocol per port (JK02_32S) |
select.lcd_buzzer_trigger, dry1_trigger, dry2_trigger
| Trigger sources (JK02_32S) |
select.multiplexed_port_mode
| Multiplexed port mode (JK02_32S) |
select.load_config_preset
| Load a configuration preset |
switch.discharge_overcurrent_protection_2, discharge_overcurrent_protection_3
| Additional OCP stages (JK02_32S) |
switch.emergency_button_trigger, dry_contact_alarm_intermittent
| (JK02_32S) |
switch.gps_locked_charging, gps_locked_discharging
| (JK02_32S) |
button.retrieve_logbook
| Request the BMS logbook (frame 0x05)
|
button.shutdown, button.restart, button.factory_reset
| Device control |
Number entities are now also writable on JK04 devices.
Other improvements
- The BLE scanner examples now filter JK-BMS devices by advertisement data
- Stale live readings, cell voltages and binary sensors are invalidated when the BMS goes offline or the cell count changes
- The first cell report after connecting is published without throttling
- Fixed select redefinition error with multiple
jk_bms_bleinstances - Newly supported devices: JK-B1A8S20P, EK-24S10EB, EK-24S20EB
jk_bms (UART/RS485)
- Removed cell readings are cleared after a cell-count change
- Fixed a misleading
errors_bitmaskwarning for UART-only configurations
heltec_balancer_ble
New entities
| Key | Description |
|---|---|
text_sensor.device_model
| Device model |
text_sensor.hardware_version
| Hardware version |
text_sensor.software_version
| Software version |
text_sensor.protocol_version
| Protocol version |
text_sensor.manufacturing_date
| Manufacturing date |
sensor.power_on_count
| Power on counter |
Other improvements
- Maximum balance current limit raised from 15 A to 20 A
- Fixed frame reassembly on small BLE MTU
- Corrected calibration diagnostics
- Formatted runtime is marked offline on disconnect
Configurable error labels (error_overrides)
jk_bms, jk_bms_ble and jk_balancer now accept an error_overrides option to replace the labels published by text_sensor.errors. Keys are the error bit number in decimal; an empty label suppresses the bit. For jk_bms_ble this is supported for the JK02 protocols only.
jk_bms_ble:
- ble_client_id: client0
error_overrides:
4: "Cell overvoltage"What's Changed
- Fix misleading errors_bitmask warning for UART-only configs by @syssi in #990
- Add write support for number entities (JK04) by @syssi in #991
- Decode hardware option field in device info frame by @syssi in #992
- Format manufacturing date as YYYY-MM-DD by @syssi in #993
- Add UART and CAN protocol name lookup arrays by @syssi in #994
- Add retrieve logbook button and frame 0x05 decoder by @syssi in #995
- Add run-cpp-tests.sh helper script by @syssi in #998
- Add emergency_button_trigger, dry_contact_alarm_intermittent, discharge_overcurrent_protection_2 switches (JK02_32S) by @syssi in #999
- Add uart{1,2,3}_protocol, can_protocol, lcd_buzzer_trigger, dry{1,2}_trigger select entities (JK02_32S) by @syssi in #1000
- Add BLE 3-pack example for JK-BMS v19 with combined stack entities by @danielschramm in #890
- Remove redundant BMS prefix from entity names in multiple-device examples by @syssi in #1001
- Add missing entities to esp32-ble-v19-3pack example by @syssi in #1002
- Add discharge_overcurrent_protection_3, gps_locked_charging, gps_locked_discharging switches (JK02_32S) by @syssi in #1003
- Add load_config_preset select entity by @syssi in #1004
- Add shutdown, restart, factory_reset button entities by @syssi in #1005
- Fix load_config_preset: empty placeholder as persistent initial state by @syssi in #1006
- Add multiplexed_port_mode select entity (JK02_32S) by @syssi in #1007
- Add smart_sleep_delay number and smart_sleep_countdown sensor (JK02_32S) by @syssi in #1008
- Add emergency_duration number entity (JK02_32S) by @syssi in #1009
- Replace locally defined unit constants with esphome.const imports by @syssi in #1010
- Align capacity sensor names in JK-PB modbus example with jk_bms_ble by @syssi in #1012
- Add and align cell voltage sensors in JK-PB modbus example by @syssi in #1013
- CI: Remove pio warmup step for esp32-idf-tidy by @syssi in #1014
- Add JK-B1A8S20P as supported by @syssi in #1018
- Drop Python 3.11 support by @syssi in #1022
- Fix device_description version numbers by @syssi in #1026
- Add EK-24S10EB tests by @syssi in #1029
- Fix heltec_balancer_ble frame reassembly on small BLE MTU by @syssi in #1032
- Expose device model, manufacturing date and serial number in jk_bms_ble by @syssi in #1035
- Expose device info fields as text sensors in heltec_balancer_ble by @syssi in #1036
- Expose power on count sensor in jk_bms_ble by @syssi in #1037
- Expose power on count sensor in heltec_balancer_ble by @syssi in #1038
- jk_bms_ble: make JK02 error labels configurable via error_overrides by @syssi in #1039
- Make jk_bms error labels configurable via error_overrides by @syssi in #1040
- Make jk_balancer error labels configurable via error_overrides by @syssi in #1041
- Publish multiplexed_port_mode state from the settings frame (JK02_32S) by @syssi in #1044
- Fix bogus values in JK02 cell info debug logs (jk_bms_ble) by @syssi in #1046
- Add JK02_32S SOC and SOH calibration numbers by @katrinagui in #1053
- Fix select redefinition error with multiple jk_bms_ble instances by @syssi in #1060
- Import shared constants from esphome.components.const with fallback by @syssi in #1063
- Wrap ternary log string literals in LOG_STR_LITERAL by @syssi in #1064
- Migrate deprecated check_uart_settings to final_validate_device_schema by @syssi in #1065
- Declare log tags with ESPHOME_LOG_TAG by @syssi in #1067
- Add DOMAIN constant to components by @syssi in #1068
- Use DOMAIN in uart final validate schema by @syssi in #1069
- Remove ADDR_STR compatibility shim for ESPHome < 2025.12.0 by @syssi in #1072
- Migrate format_hex_pretty to format_hex_pretty_to by @syssi in #1071
- Use icon constants from ESPHome core by @syssi in #1073
- Remove register_count from JK-PB modbus example by @syssi in #1074
- Remove deprecated skip_updates and command_throttle from JK-PB modbus examples by @syssi in #1075
- Publish user defined device name and address by @tpruvot in #1077
- docs: clarify JK-BMS UART pin guidance by @Fstarnb in #1076
- docs: clarify JK-B1A20S15P BLE protocol mapping by @Fstarnb in #1078
- Fix BLE scanner examples for ESPHome 2026.9 StringRef device names by @syssi in #1079
- Replace flake8 with ruff docstring rules by @syssi in #1082
- Add relation to sub-devices and require ESPHome 2026.11.0 by @syssi in #1084
- modbus sample: add missing types/units by @tpruvot in #1083
- Import CONF_DEVICE_TYPE from esphome.components.const if available by @syssi in #1085
- modbus: fix units to avoid H.A warning/errors on discovery by @tpruvot in #1087
- Show Ah capacities of the JK-PB modbus example with one decimal by @syssi in #1088
- modbus: update sample for min/max cell voltage by @tpruvot in #1081
- Decode temperature sensor absent bitmask as 8-bit value by @syssi in #1089
- Rename temperature sensor absent bitmask to presence bitmask by @syssi in #1090
- Improve BLE scanner and filter JK-BMS by advertisement data by @syssi in #1091
- Raise max balance current limit of the Heltec balancer to 20A by @syssi in #1093
- Add EK-24S20EB to the list of supported devices by @syssi in #1094
- Invalidate binary sensors when device is offline by @syssi in #1095
- modbus: balancer switch for JK BMS Card compat by @tpruvot in #1096
- modbus: replace dis/charging select boxes like ble by @tpruvot in #1097
- Remove duplicate CONF_ component schema by @syssi in #1098
- Move duplicated constants into const.py by @syssi in #1099
- Scope v3 migration renames to each JK BMS entity by @Solarboaters in #1101
- Keep the final Bluetooth frame when analysing captures by @Solarboaters in #1102
- Reject conflicting deprecated configuration names by @Solarboaters in #1104
- Reject invalid JK BLE number limits and steps by @Solarboaters in #1105
- Reject invalid JK balancer number limits and steps by @syssi in #1115
- Reject invalid Heltec balancer number limits and steps by @syssi in #1116
- Keep missing capture bytes distinct from real zeros by @Solarboaters in #1106
- Reset select lookup tables for each configuration build by @Solarboaters in #1108
- Invalidate cell readings that disappear from display frames by @Solarboaters in #1109
- Clear removed cell readings after balancer cell-count changes by @Solarboaters in #1110
- Clear removed cell readings after jk_bms cell-count changes by @syssi in #1117
- Clear remaining stale BLE live readings when the BMS goes offline by @Solarboaters in #1112
- Publish the first JK BLE cell report without throttling by @Solarboaters in #1113
- Publish the first Heltec BLE cell report without throttling by @Solarboaters in #1114
- Remove current and power sensors the active balancers cannot measure by @Solarboaters in #1120
- Mark Heltec formatted runtime offline on disconnect by @Solarboaters in #1121
- Resolve local component paths by @Solarboaters in #1122
- Refuse .txt capture input to avoid overwriting it by @Solarboaters in #1123
- Correct Heltec calibration diagnostics and power-on counter decoding by @Solarboaters in #1124
- Clone public ESPHome sources over HTTPS in the host test runner by @Solarboaters in #1125
- Preserve repeated ATT values when extracting Bluetooth captures by @Solarboaters in #1126
- Accept only decimal error bit keys in error_overrides by @Solarboaters in #1127
- Update pre-commit hooks and pin the minimum ESPHome version by @syssi in #1128
- Remove unused includes by @syssi in #1129
- Remove empty loop() overrides by @syssi in #1130
- Drop the Component base from the switch and button entities by @syssi in #1131
- Fix the RCV/RFV time and balancing bytes in the PB Modbus example by @thebitrock in #1132
- Add the heating state sensor to the PB Modbus example by @thebitrock in #1133
- Add the heating switch and temperature thresholds to the PB Modbus example by @syssi in #1135
New Contributors
- @danielschramm made their first contribution in #890
- @katrinagui made their first contribution in #1053
- @tpruvot made their first contribution in #1077
- @Fstarnb made their first contribution in #1076
- @Solarboaters made their first contribution in #1101
Full Changelog: 3.0.0...3.1.0