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

• Zero configuration
• Autodetects compatible batteries
• Supports ESPHome Bluetooth proxy (BT 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

Supported Devices

• CBT Power BMS, Creabest batteries
• D-powercore BMS (show up as DXB-…), Fliteboard batteries (show up as TBA-…)
• Daly BMS (show up as DL-…)
• E&J Technology BMS, Supervolt v1 batteries
• JBD BMS, Jiabaida
  • accurat batteries
  • Supervolt v3 batteries
• JK BMS, Jikong, (HW version >=11 required)
• Offgridtec LiFePo4 Smart Pro: type A & B (show up as SmartBat-A… or SmartBat-B…)
• LiTime, Redodo batteries
• Seplos v3 (show up as SP0… or SP1…)

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.

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

Installation

Automatic

Installation can be done using HACS by adding a custom repository.

Manual

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 "+" and search for "BLE Battery Management"

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

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:

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.

Troubleshooting

In case you have severe troubles,

• please enable the debug protocol for the BLE Battery Management integration,
• 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 happened and attach the log.

Outlook

• Clean-up of translations
• Implement status report of the BMS, e.g. warnings, errors as (single) binary sensor (ok, not ok)
• 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, @SkeLLLa,@romanshypovskyi

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