patman15/bms_ble-ha

This integration allows to monitor Bluetooth Low Energy (BLE) battery management systems (BMS) from within Home Assistant.

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

• Offgridtec LiFePo4 Smart Pro: type A & B (show up as SmartBat-A… or SmartBat-B…)
• Daly BMS (show up as DL-…)
• JK BMS, Jikong, (HW version >=11 required)
• JBD BMS, Jiabaida
• Supervolt batteries (JBD BMS)
• Seplos v3 (show up as SP0…)

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

Provided Information

The integration provides the following information about the battery

Platform	Description	Unit	Details
sensor	SoC (state of charge)	%	range 100% (full) to 0% (battery empty)
sensor	stored energy	Wh	currently stored energy
sensor	voltage	V	overall battery voltage
sensor	current	A	positive for charging, negative for discharging
sensor	power	W	positive for charging, negative for discharging
sensor	temperature	°C
sensor	(remaining) runtime	s	remaining discharge time till SoC 0%
sensor	charge cycles	#
sensor	delta voltage	V	maximum difference between any two cells; individual cell voltage are available as attribute to this sensor
binary_sensor	battery charging indicator	bool	true if battery is charging

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"

Outlook

• Add option to only have temporary connections (lowers reliability, but helps running more devices via ESPHome Bluetooth proxy)
• Add further battery types from Home Assistant Add-on: BatMON on request

Troubleshooting

In case you have severe troubles,

• please enable the debug protocol for the 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.

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:

Field	Content
State template	{{ state_attr("sensor.smartbat_..._delta_voltage", "cell_voltages")[0] }} 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_...

I want to know the maximum cell voltage!

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

Field	Content
State template	{{ state_attr("sensor.smartbat_..._delta_voltage", "cell_voltages") | max }}

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.

Thanks to

@downset, @gerritb, @Goaheadz

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

bms_ble-ha's Issues

some minor things missing on type A

hi sir,

I gave it a final look and detected following issues here in my setup (type-A battery)

1. two values are always "0" (Current and Power) - it looks like "Current" matches what I see in the offgridtec app (see screenshot), "Power" is not shown in the app ... but should also not be zero

2. very important (at least for me) is to see (as displayed in the app) that the battery is either "charging", "discharging" or "idling" => but I suspect that this is just a calculated value derived from simple rule to check whether "Current" is positive, negative or zero value => but would be nice to gave that as an entity too in the integration

3. the switching between using your integration and the offgridtec is currently also a bit quirky => tested to disable the integration => this worked after some time (30 min) that the offgridtec app again could connect BUT from then on it was no longer possible to re-enable succesfully the integration => it just showed "unavailable error" => only removing the device and the integration and re-adding the integration cured the situation

OK thats it from my side - i hope we can fix these last glitches => then it will be perfect and maybe even point 3) is irrelevant as all relevant data is provided by HA

cheerz
greetings from vienna

Support for JK BMS

Checklist

• I have filled out the template to the best of my ability.
• I have understood that this integration is only about battery management systems with Bluetooth Low Energy support.
• This only contains 1 feature request (if you have multiple feature requests, open one feature request for each feature request).
• This issue is not a duplicate feature request of previous feature requests.

Is your feature request related to a problem? Please describe.

I would love to see support for the new JK Inverter BMS.

Describe the solution you'd like

Found your project through the Offgrid Garage video and have the same problem as Andy with the Batmon addon, because i would like to use the ESPHome BLE proxy.
So your project would be a perfekt solution.
Are you planing to add the JK Inverter BMS to your solution?
I opened this Feature Request to track the progress (if integration is planed) and maybe can help Beta testing
Best Regards

Additional context

No response

Supervolt BMS

I want to add support for Supervolt BMS. I have two Supervolt POLAR LiFePO4 100Ah.
There is an implementation in the reference project batmon-ha and this seems to be replicated from WoMoAtor.

I'm able to connect to the batteries through HomeAssistant on RPi4 but struggle to setup the "start_notify" callback in the connect function.

The initial device debug shows 5 service-uuids:

['00001800-0000-1000-8000-00805f9b34fb', 
 '00001801-0000-1000-8000-00805f9b34fb', 
 '0000180a-0000-1000-8000-00805f9b34fb', 
 '00002600-0000-1000-8000-00805f9b34fb', 
 '0000ff00-0000-1000-8000-00805f9b34fb']

Not sure which one to use in the code.

Pushed my first few changes here:
https://github.com/gerritb/BMS_BLE-HA/tree/feature/supervolt_bms

I also added

logger:
  default: info
  logs:
    custom_components.bms_ble: debug

to my configuration.yaml but can't find a dedicated log file in the HA folders. Any advise on that?

Additional context

https://github.com/fl4p/batmon-ha/blob/master/bmslib/models/supervolt.py

https://github.com/BikeAtor/WoMoAtor/blob/main/src/main/python/supervolt/supervoltbatterybleak.py)

Hi this looks perfect having BLE proxy support

Checklist

• I need support with using the integration.
• My issue is not a feature request
• I'm not avoiding to fill out the bug report form.

Describe the issue

Hi, I have auto installed using HACS (Do have other HACS add on running) I'v restarted HA. When I go to add the BLE Battery integration. It just pops up instantly with "No devices found on the network" There doesnt appear to be any way to configure a MAC address or let it know to look via BT Proxy. Thanks

Failed to initialize BMS

Hello!

I see a warning after every HA restart, but the readings seem to be ok.

Sorry that it's partly in German, despite I changed the language in several places to English. The BMS number shown below is partly redacted:

Dieser Fehler wurde von einer benutzerdefinierten Integration verursacht

Logger: custom_components.bms_ble
Quelle: custom_components/bms_ble/__init__.py:46
Integration: BLE Battery Management (Dokumentation, Probleme)
Erstmals aufgetreten: 20:42:32 (1 Vorkommnisse)
Zuletzt protokolliert: 20:42:32

Failed to initialize BMS x6xx10xx6xx, continuing

Do you have an idea for the reason? Shall I simply ignore it, or is there something I should do about it? Shall I add some log file?

Thanks for your help! 👍

PS:
The log file ends with this (number partly redacted):

[custom_components.bms_ble] Finished fetching x6xx10xx6xx data in 0.120 seconds (success: True)

Seplos BMS V3

Checklist

• I have filled out the template to the best of my ability.
• I have understood that this integration is only about battery management systems with Bluetooth Low Energy support.
• This only contains 1 feature request (if you have multiple feature requests, open one feature request for each feature request).
• This issue is not a duplicate feature request of previous feature requests.

Is your feature request related to a problem? Please describe.

Need help to start integration with Seplos BMS 3.0

Describe the solution you'd like

Guidance to implement this.

Additional context

I have Bluetooth proxy near BMS, but I dont see MAC adress. Should I see one?
If it is not suposed to see results in scan/esp32 logs, then file known_devices.yaml should log the BMS mac?
I can connect with no problems via Seplos Android app, but app does not show mac adress.

From the begining..what should I try first?

GUI not updating data

Checklist

• I have enabled debug logging for my installation.
• I have filled out the issue template to the best of my ability.
• This issue only contains 1 issue (if you have multiple issues, open one issue for each issue).
• This issue is not a duplicate issue of any previous issues.

Describe the issue

GUI not updating battery information although query to BMS is successfull. Caused by ea9bd2c#75-76

Reproduction steps

1. run the integration
2. change, e.g. current to/from battery
3. wait at least 30 seconds
4. observe no change

Debug logs

cannot be seen from the logs as they are ok.

Gas level sensor

Checklist

• I have filled out the template to the best of my ability.
• I have understood that this integration is only about battery management systems with Bluetooth Low Energy support.
• This only contains 1 feature request (if you have multiple feature requests, open one feature request for each feature request).
• This issue is not a duplicate of any previous feature requests.

Is your feature request related to a problem? Please describe.

Hello!

Understanding that this is indeed about battery management systems (BMS) and not about gas level sensors (I should not have ticked the 2nd tick box 🫢), I hope that my question here does not annoy you. If it does, please kindly delete my post and forgive me.

My question is if you think it is possible to hook into a Bluetooth gas level sensor like from Truma or Mopeka? I have one from Truma, and there does not seem to be any HA integration for it. I can read the level (in % and kg gas) with Truma's native Android app ("Level Control"), and I can see the sensor (attached to the bottom of the gas bottle) via the Android app "nRF Connect", which is a very powerful tool regarding BLE (incl. server mode), but its possibilities are way beyond my capabilities, I'm afraid.

Describe the solution you'd like

If you see a way how I could dig deeper into this, I would welcome your hints pointing me into the right direction.

Please accept my apologies that this is not really a feature request. I posted this here, because I was not sure how else I could ask you. And you seem to know already a lot about BLE. 👍

Additional context

No response

JBD BMS

Checklist

• I have filled out the template to the best of my ability.
• I have understood that this integration is only about battery management systems with Bluetooth Low Energy support.
• This only contains 1 feature request (if you have multiple feature requests, open one feature request for each feature request).
• This issue is not a duplicate feature request of previous feature requests.

Is your feature request related to a problem? Please describe.

no

Describe the solution you'd like

Support for JBD BMS

Additional context

I think JBD are among the most used BMS, are there plans to integrate JBD?

HA complaining about blocking import

Describe the issue

Hello,

I'm trying to port the BMS addon for Supervolt batteries and wanted to get started today. I added the bluetooth device name pattern in manifest.json like this
{
"local_name": "SX100P-*",
"service_uuid": "0000fff0-0000-1000-8000-00805f9b34fb"
}
I wanted to check if I can get a connection to the BMS and start debugging/developing from there. The integration immediately fails with "No devices found on the network" and this is what I found in the HA logs.

Added my HW setup in the repro steps.
Also added
logger:
default: info
logs:
custom_components.bms_ble: debug
to my configuration.yaml but couldn't find the component log output.

Any help is appreciated, wanna get my batteries into the van HA instance.

Thank you for the base work on this project

Best,
Gerrit

Reproduction steps

HA on RPi4
Core 2024.6.2
Supervisor 2024.06.0
Operating System 12.3
Frontend 20240610.0

Install integration through HACS
Start integration config flow

Debug logs

Detected blocking call to import_module inside the event loop by custom integration 'bms_ble' at custom_components/bms_ble/config_flow.py, line 47: bms_plugin = importlib.import_module( (offender: /config/custom_components/bms_ble/config_flow.py, line 47: bms_plugin = importlib.import_module(), please create a bug report at https://github.com/patman15/BMS_BLE-HA/issues

Max number of devices

Checklist

• I have filled out the template to the best of my ability.
• I have understood that this integration is only about battery management systems with Bluetooth Low Energy support.
• This only contains 1 feature request (if you have multiple feature requests, open one feature request for each feature request).
• This issue is not a duplicate feature request of previous feature requests.

Is your feature request related to a problem? Please describe.

I only seem to be able to access 3 devices with ESP Bluetooth Proxy. I have 8 BMS boards. Is there any way to access more than 3. If I use more than 1 ESP bluetooth proxy esp32 can I specify which devices they connect to?

Describe the solution you'd like

Some way to specify which BLE mac ids you access.

Additional context

No response

Unique sensor ID is based on device name not MAC address

Checklist

• I have enabled debug logging for my installation.
• I have filled out the issue template to the best of my ability.
• This issue only contains 1 issue (if you have multiple issues, open one issue for each issue).
• This issue is not a duplicate issue of any previous issues.

Describe the issue

The unique_id of a BMS sensor is generated with the name of the device and not a MAC address. This can lead to

• duplicate entries or
• if BT device is renamed to duplicated entries

Issue is here:

BMS_BLE-HA/custom_components/bms_ble/sensor.py

Line 144 in ac58f05

self._attr_unique_id = f"{format_mac(bms.name)}-{descr.key}"

Reproduction steps

1. run the integration with a device
2. check /config/.storage/core.entity_registry

Debug logs

{"config_entry_id":null,"entity_id":"sensor.myjbd_test_current","id":"f19b49849ba7118843b294e854d3338d","orphaned_timestamp":-----------.8892846,"platform":"bms_ble","unique_id":"myJBD-test-current"}