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.
- 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
- ABC/SOK BMS (show up as
ABC-…,SOK-…) - CBT Power BMS, Creabest batteries
- D-powercore BMS (show up as
DXB-…), Fliteboard batteries (show up asTBA-…) - 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-… orL-12V…) - Meritsun, Supervolt v1, and Volthium (show up as
V-12V…) batteries
- Elektronicx batteries (show up as
- ECO-WORTHY + BW02 adapter (show up as
ECO-WORTHY…) - 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-…) - DCHOUSE, ECO-WORTHY (show up as
DP04S…), Epoch batteries - Eleksol, Perfektium (show up as
PKT…), Ultimatron batteries (show up as12??0…) - SBL batteries, Supervolt v3 batteries (show up as
SX1…)
- accurat batteries (show up as
- JK BMS, Jikong, (HW version ≥ 6 required)
- Offgridtec LiFePo4 Smart Pro: type A & B (show up as
SmartBat-A… orSmartBat-B…) - LiTime, Power Queen, and Redodo batteries
- Seplos v2 (show up as
BP0?) - Seplos v3 (show up as
SP[0,1,4-6]…) - RoyPow batteries
- TDT BMS
Tip
New device types can be easily added via the plugin architecture of this integration. See the contribution guidelines for details.
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 |
*) 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.
| Quality | link quality [%] | RSSI [dBm] |
|---|---|---|
| excellent | 98 to 100 | -50 to high |
| good | 90 to 98 | -60 to -70 |
| fair | 80 to 90 | -70 to -80 |
| weak | 60 to 80 | -80 to -90 |
| bad | 0 to 60 | -90 to low |
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
- Using the tool of choice open the directory (folder) for your HA configuration (where you find
configuration.yaml). - If you do not have a
custom_componentsdirectory (folder) there, you need to create it. - In the
custom_componentsdirectory (folder) create a new folder calledbms_ble. - Download all the files from the
custom_components/bms_ble/directory (folder) in this repository. - Place the files you downloaded in the new directory (folder) you created.
- Restart Home Assistant
- In the HA UI go to Configuration > Integrations click + Add Integration and search for "BLE Battery Management"
This integration follows standard integration removal. No extra steps are required.
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
- Next to the entry, select the three-dot menu. Then, select Delete.
Daly BMS with WiFi, e.g. Bulltron
The connection cannot be established. The reason is most likely a violation of the Bluetooth specification, that is rejected by the Linux BlueZ daemon. Please raise a new issue if you have further information or observations.Elektronicx, Lithtech batteries
Bluetooth is turned off, when there is no current. Thus, device will get unavailble / cannot be added.Redodo MPPT
Currently there is no way to distinguish Redodo batteries from their MPPT chargers. Thus, the latter are also detected but cannot be read out. Please set these devices to `ignore`.Seplos v2
The internal Bluetooth adapter issuesAT commands in regular intervals which can interfer with BMS messages causing them to be corrupted. This impacts data availability (link quality).
- Check that your BMS type is listed as supported device
- If a name detection pattern is listed ("show up as"), make sure your device matches it.
- Make sure that no other device is connected to the BMS, e.g. app on your phone
- Check that your are running the latest release of the integration
- Open a terminal to Home Assistant and verify that your BMS is listed in the ouput of the command
bluetoothctl devices. - If you use a BT proxy, make sure you have set
active: trueand 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. - If above points did not help, please open an issue providing the advertisement data of the device. To get the data, please go to the bluetooth integration. On your BT adapter select
configure -> advertisement monitor, click the device in question and provide the information viacopy to clipboard.
- 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.
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.
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!
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
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') }}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.
Sure, use, e.g. a threshold sensor based on the current to/from the battery. Negative means discharging, positiv is charging.
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 devicesto 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.
- 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
@gkathan, @downset, @gerritb, @Goaheadz, @alros100, @majonessyltetoy, @snipah, @Gruni22, @azisto, @BikeAtor, @Karatzie, @SkeLLLa,@romanshypovskyi, @riogrande75, @ebagnoli, @andreas-bulling, @goblinmaks, @andreitoma-github, @hacsler, @ViPeR5000, @edelstahlratte, @nezra, @Fandu21, @rubenclark74
for helping with making the integration better.
- 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