BLE Battery Management Systems for Home Assistant

This integration allows to monitor Bluetooth Low Energy (BLE) battery management systems (BMS) from within Home Assistant. After installation, no configuration is required. You can use the ESPHome Bluetooth proxy to extend the bluetooth coverage range. By using standard dashboard cards, it is easy to visualize the current state of remote batteries.

• Features
• Installation
• Removing the Integration
• Troubleshooting
  • Known Issues
  • Device is not Recognized
  • Support Issues
• Energy Dashboard Integration
• FAQ
• Outlook
• Thanks to
• References

Features

• Zero configuration
• Autodetects compatible batteries
• Supports ESPHome Bluetooth proxy (limit: 3 devices/proxy)
• Any number of batteries in parallel
• Native Home Assistant integration (works with all HA installation methods)
• Readout of individual cell voltages to be able to judge battery health
• 100% test coverage plus fuzz tests for BLE data

Supported Devices

• ABC/SOK BMS (show up as ABC-…, SOK-…)
• CBT Power BMS, Creabest batteries
• D-powercore BMS (show up as DXB-…), Fliteboard batteries (show up as TBA-…)
• Daly BMS (show up as DL-…)
  • 100Balance BMS
  • Bulltron batteries
• E&J Technology BMS (show ups as libatt…)
  • Elektronicx batteries (show up as LT-…)
  • Lithtech batteries (show up as LT-12V-… or L-12V…)
  • Meritsun, Supervolt v1 (show up as SV12V…), and Volthium (show up as V-12V…) batteries
• ECO-WORTHY + BW02 adapter (show up as ECO-WORTHY…)
  • DCHOUSE batteries (show up as DCHOUSE…)
• Ective, Topband batteries (show up as $PFLAC…, NWJ20…, ZM20…)
• Felicity ESS batteries (show up as F10…)
• JBD BMS, Jiabaida (show up as AP2.S…, SP..S…)
  • accurat batteries (show up as GJ-…)
  • Bulltron, DCHOUSE, ECO-WORTHY (show up as DP04S…, ECO-LFP…), Epoch batteries
  • Eleksol, Liontron, Perfektium (show up as PKT…), Ultimatron batteries (show up as 12??0…)
  • SBL batteries, Supervolt v3 batteries (show up as SX1…), Vatrer batteries (show up as DWC…)
• JK BMS, Jikong, (HW version ≥ 6 required)
• LiTime, Power Queen, and Redodo batteries
• Offgridtec LiFePo4 Smart Pro: type A & B (show up as SmartBat-A… or SmartBat-B…)
• Renogy BMS
• RoyPow batteries
• Seplos v2 (show up as BP0?)
• Seplos v3 (show up as SP[0,1,4-6]…)
• TDT BMS
  • Wattcycle batteries

Tip

New device types can be easily added via the plugin architecture of this integration. See the contribution guidelines for details.

Provided Information

Caution

This integration (including Home Assistant) shall not be used for safety relevant operations! The correctness or availability of data cannot be guaranteed (see warranty section of the license), since the implementation is mostly based on openly available information or non-validated vendor specifications. Further, issues with the Bluetooth connection, e.g. disturbances, can lead to unavailable or incorrect values.

Do not rely on the values to control actions that prevent battery damage, overheating (fire), or similar.

Platform	Description	Unit	Decription	optional Attributes
binary_sensor	battery charging	bool	indicates True if battery is charging
binary_sensor	problem	bool	indicates True if the battery reports an issue or plausibility checks on values fail
sensor	charge cycles	#	lifetime number of charge cycles	package charge cycles
sensor	current	A	positive for charging, negative for discharging	balance current, package current
sensor	delta voltage	V	maximum difference between any two cells	cell voltages
sensor	power	W	positive for charging, negative for discharging
sensor	runtime	s	remaining discharge time till SoC 0%, unavailable during idle/charging
sensor	SoC	%	state of charge, range 100% (full) to 0% (battery empty)	package SoC
sensor	stored energy	Wh	currently stored energy
sensor	temperature	°C	(average) battery temperature	individual temperature values
sensor	voltage	V	overall battery voltage	package voltage
sensor*	link quality	%	successful BMS queries from the last hundred update periods
sensor*	RSSI	dBm	received signal strength indicator

*) sensors are disabled by default

Installation

BMS_BLE is a default repository in HACS. Please follow the guidelines on how to use HACS if you haven't installed it yet. To add the integration to your Home Assistant instance, use this My button:

Manual installation steps

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called bms_ble.
4. Download all the files from the custom_components/bms_ble/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. In the HA UI go to Configuration > Integrations click + Add Integration and search for "BLE Battery Management"

Removing the Integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three-dot menu. Then, select Delete.

Troubleshooting

Note

A lot of transient issues are due to problems with Bluetooth adapters. Most prominent example is the performance limitation of the internal Raspberry Pi BT adapter, resulting in, e.g., sometimes wrong data, when you have multiple devices. Please check the Home Assistant Bluetooth integration page for known issues and consider using a recommended high-performance adapter.

Known Issues

ECO-WORTHY batteries "ECOxxxx"

ECO-WORTHY batteries that show up as ECOxxxx use classic Bluetooth and do not support Bluetooth Low Energy (BLE). Thus, they unfortunately cannot be integrated. The advertisement contains {"name":"ECOxxxx","service_uuids":["0000ff00-0000-1000-8000-00805f9b34fb","00000001-0000-1000-8000-00805f9b34fb"]

Elektronicx, Lithtech batteries

Bluetooth is turned off, when there is no current. Thus, device will get unavailble / cannot be added.

Batteries with JBD BMS

JBD BMS detection unfortunately needs to rely on name patterns. If you renamed your battery it most likely will not be detected. I do appreciate issues being raised for new vendor naming schemes to ease the life of other users. To help, please follow the instructions in the last list item for non-detected devices.

Liontron batteries

These batteries need a shorter interval between queries. Be a bit patient to get them added and set a custom interval of about 9s to keep a stable connection.

Seplos v2

The internal Bluetooth adapter issues AT commands in regular intervals which can interfer with BMS messages causing them to be corrupted. This impacts data availability (link quality).

If your device is not recognized

1. Check that your BMS type is listed as supported device
2. If a name detection pattern is listed ("show up as"), make sure your device matches it.
3. Make sure that no other device is connected to the BMS, e.g. app on your phone
4. Check that your are running the latest release of the integration
5. Go to the advertisement monitor and verify that your device shows up there. Also, please ensure that your RSSI value is >= -75 dBm. If your device is missing or the RSSI value is -80 dBmor worse, please check your BT setup (is the device in range?).
6. If you use a BT proxy, make sure you have set active: true and that you do not exced the BT proxy limit of 3 devices/proxy; check the logs of the proxy if the device is recognized. Note: The Bluetooth proxy of Shelly devices does not support active connections and thus cannot be used.
7. If above points did not help, please go to the bluetooth integration. On your BT adapter select configure.
   1. Verify that you have connection slots available.
   2. Go to the advertisement monitor and click the device in question. Please provide the information via copy to clipboard to a new issue giving your BMS/battery type in the title.

Some/all sensors go unavailable temporarily or permanently

In case sensors are reported unavailable please enable the diagnostic sensors, i.e. RSSI and link quality and check your connection quality. The value of link quality results from (temporarily) bad RSSI values, which are impacted by disturbances of the Bluetooth communication. Your quality should be at least fair according to the following table:

Quality	link quality [%]	RSSI [dBm]
excellent	98 to 100	-60 to high
good	90 to 98	-60 to -75
fair	80 to 90	-75 to -80
weak	60 to 80	-80 to -90
bad	0 to 60	-90 to low

Verify that you have a proper Bluetooth setup according to the recommendations for the Home Assistant Bluetooth Integrations, see this note. In case your RSSI level is fair or better, but still the sensors show unknown, please follow the instructions for opening an issue. Please attach

• a debug log as a file,
• diagnosis data as a file, and
• a 24hrs diagram of RSSI and link quality sensor.

In case you have troubles you'd like to have help with

• please enable the debug protocol for the BLE Battery Management integration,
• restart Home Assistant, wait till it is fully started up,
• reproduce the issue,
• disable the log (Home Assistant will prompt you to download the log), and finally
• open an issue with a good description of what your question/issue is and attach the log, or
• open a bug if you think the behaviour you see is caused by the integration, including a good description of what happened, your expectations, and attach the log.

Energy Dashboard Integration

If you want your battery to be integrated with the Home Assistant energy dashboard you need to integrate the reported power value separately for charge and discharge power to two energy values. Here are the detailed steps for energy dashboard configuration in your configuration.yaml (you achieve the same result by configuring equivalent helpers):

Add two template sensors

template:
  - sensor:
    - unique_id: charge_power
      state: "{{ [states('sensor.smartbat_..._power') | float, 0] | max}}"
      unit_of_measurement: 'W'
      state_class: measurement
      device_class: power
      availability: "{{ has_value('sensor.smartbat_..._power') }}"
    - unique_id: discharge_power
      state: "{{ [states('sensor.smartbat_..._power') | float, 0] | min | abs}}"
      unit_of_measurement: 'W'
      state_class: measurement
      device_class: power
      availability: "{{ has_value('sensor.smartbat_..._power') }}"

Add two integration sensors

sensor:
  - platform: integration
    name: energy_in
    source: sensor.template_charge_power
  - platform: integration
    name: energy_out
    source: sensor.template_discharge_power

Then go to the energy dashboard configuration, add a battery system and set the two sensors energy_in and energy_out.

FAQ

My sensors show unknown/unavailable at startup!

The polling interval is 30 seconds. So at startup it takes a few minutes to detect the battery and query the sensors. Then data will be available.

Can I set a custom polling interval?

Yes, but I strongly discourage that for stability reasons. If you still want to do so, please see the default way to define a custom interval by Home Assistant. Note that Bluetooth discoveries can take up to a minute in worst case. Thus, please expect side effects, when changing the default of 30 seconds!

Can I have the runtime in human readable format (using days)?

Yes, you can use a template sensor or a card to show templates, e.g. Mushroom template card with the following template:
{{ timedelta(seconds=int(states("sensor.smartbat_..._runtime"), 0)) }} results in e,g, 4 days, 4:20:00

How do I get the cell voltages as individual sensor for tracking?

The individual voltages are available as attribute to the delta voltage sensor. Click the sensor and at the bottom of the graph expand the attribute section. Alternatively, you can also find them in the developer tools. To create individual sensors, go to Settings > Devices & Services > Helper and add a template sensor for each cell you want to monitor. Fill the configuration for, e.g. the first cell (0), as follows:

Field	Content
State template	{{ iif(has_value("sensor.smartbat_..._delta_voltage"), state_attr("sensor.smartbat_..._delta_voltage", "cell_voltages")[0], None) }} The index [0] can be in the range from 0 to the number of cells-1, i.e. 0-3 for a 4 cell battery.
Unit of measurement	V
Device class	Voltage
State class	Measurement
Device	smartbat_...

or add the following snippet to your configuration.yaml:

template:
  - sensor:
    - name: cell_voltage_0
      state: >-
        {{ state_attr('sensor.smartbat_..._delta_voltage', 'cell_voltages')[0] }}
      unit_of_measurement: 'V'
      state_class: measurement
      device_class: voltage
      availability: >- 
        {{ has_value('sensor.smartbat_..._delta_voltage') }}

I want to know the maximum cell voltage!

Please follow the explanations in the previous question but use the following:

Field	Content
State template	{%- if has_value("sensor.smartbat_..._delta_voltage") %} {{ state_attr("sensor.smartbat_..._delta_voltage", "cell_voltages") | max }} {% else %} None {% endif -%}

There are plenty more functions you can use, e.g. min, and the full power of templating.

I need a discharge sensor not the charging indicator, can I have that?

Sure, use, e.g. a threshold sensor based on the current to/from the battery. Negative means discharging, positiv is charging.

My BMS needs a pin, how can I enter it?

Then you need to pair your device first. This is procedure is only required once for each device.

• Open a terminal to Home Assistant.
• Use the command bluetoothctl devices to check that your devices is detected and
• run bluetoothctl pair <MAC_of_BMS> to start pairing the device.

Once pairing is done, the integration should automatically detect the BMS.

Outlook

• Improvements to fulfill the Home Assistant quality scale
• Add option to only have temporary connections (lowers reliability, but helps running more devices via ESPHome Bluetooth proxy)
• Add further battery types on request

Thanks to

@gkathan, @downset, @gerritb, @Goaheadz, @alros100, @majonessyltetoy, @snipah, @Gruni22, @azisto, @BikeAtor, @Karatzie, @PG248, @SkeLLLa,@romanshypovskyi, @riogrande75, @ebagnoli, @andreas-bulling, @goblinmaks, @andreitoma-github, @hacsler, @ViPeR5000, @edelstahlratte, @nezra, @Fandu21, @rubenclark74, @geierwally1978, @Tulexcorp, @oliviercommelarbre, @shaf, @gavrilov

for helping with making the integration better.

References

• Home Assistant Add-on: BatMON
• Daly BMS: esp32-smart-bms-simulation
• Jikong BMS: esphome-jk-bms
• JBD BMS: esphome-jbd-bms
• D-powercore BMS: Strom BMS monitor
• Redodo BMS: LiTime BMS bluetooth