Monitor and control various Battery management systems (BMS) over Bluetooth. This add-on reads the BMS and sends sensor data through MQTT to Home Assistant. Using bluetooth on the Home Assistant host system, it does not need any additional hardware (no USB/Serial/RS485).
I created this to compare BMS readings for a detailed evaluation of BMS reliability and accuracy.
I tested the add-on on a Raspberry Pi 4 using Home Assistant Operating System.
https://github.com/fl4p/home-assistant-addons
The add-on can read multiple BMS at the same time. Add an entry for each device, such as:
- address: CC:44:8C:F7:AD:BB
type: jk
alias: battery1 # MQTT topic prefix (regex [\w_.-/])
pin: "12345" # pairing PSK, victron only (optional)
adapter: "hci0" # switch the bluetooth hw adapter (optional)
debug: true # verbose log for this device only (optional)
current_calibration: 1.0 # current [I] correction factor (optional)
address
is the MAC address of the Bluetooth device. If you don't know the MAC address start the add-on, and you'll
find a list of visible Bluetooth devices in the add-on log. Alternatively you can enter the device name here as
displayed in the discovery list.
type
can be jk
, jbd
, ant
, daly
, supervolt
, sok
, victron
or dummy
.
With the alias
field you can set the MQTT topic prefix and the name as displayed in Home Assistant.
Otherwise, the name as found in Bluetooth discovery is used.
If the device requires a PIN when pairing (currently Victron SmartShunt only) add pin: "123456"
(and replace 123456
with device's PIN).
Add adapter: "hci1"
to select a bluetooth adapter other than the default one.
With current_calibration
you can calibrate the current sensor. The current reading is multiplied by this factor. Set
it to -1
to flip the sign if you experience wrong charge/discharge meters.
For verbose logs of particular BMS add debug: true
.
core-mosquitto
.concurrent_sampling
tries to read all BMSs at the same time (instead of a serial read one after another). This can
increase sampling rate for more timely-accurate data. Might cause Bluetooth connection issues if keep_alive
is
disabled.keep_alive
will never close the bluetooth connection. Use for higher sampling rate. You will not be able to connect
to the BMS from your phone anymore while the add-on is running.sample_period
is the time in seconds to wait between BMS reads. Small periods generate more data points per time.publish_period
to a higher value than sample_period
to throttle MQTT data, while sampling BMS for accurate
energy meters. On publish, samples since previous publish are averaged. Periods shorter than 2s can slow down history
plots in HA.invert_current
changes the sign of the current. Normally it is positive during discharge, inverted its negative.expire_values_after
time span in seconds when sensor values become "Unavailable"watchdog
stops the program on too many errors (make sure to enable the Home Assistant watchdog to restart the add-on
after it exists)install_newer_bleak
to install bleak 0.20.2, which is more stable than the default version. The default
version is known to be working with Victron SmartShunt.Batmon implements energy metering by computing the integral of power values from the BMS with the trapezoidal rule. You can add theses meters to your Home Assistant Energy Dashboard or use them with the HA Helper Utility Meter, see doc/HA Energy Dashboard.md.
Total Energy Discharge
Meter: total Energy out of the battery (increasing only, use this for the Energy Dashboard)Total Energy Charge
: total Energy into the battery (increasing only, use this for the Energy Dashboard)Total Energy
: The total energy flow into and out of the battery (decreasing and increasing).
This equals to (Total Energy Charge) - (Total Energy Discharge)
. It will increase over time because batteries are
not ideal. You can create a derivative helper to compute energy flow within e.g. 24h.Total Cycles
: Total full cycles of the battery. One complete discharge and charge is a full cycle: SoC 100%-0%-100%.
This is not a value provided by the BMS, Batmon computes this by differentiating the SoC (
e.g. integrate(abs(diff(SoC% / 100 / 2)))
).The accuracy depends on the accuracy of the voltage and current readings from the BMS. Consider these having an error of 2~5%. Some BMS do not detect small currents (<200mA) and can miss high frequency peaks, leading to even greater error.
bt_power_cycle
. If it doesn't work, manually power cycle Bluetooth on the host you are running batmon
on #91.keep_alive
TimeoutError: timeout waiting
: put BT devices closer, disable inverters and other EMI sourcesverbose_log
and check the logs. If that is too noisy set debug: true
in the BMS configuration as described
aboveinstall_newer_bleak
optionadapter
parameter for each BMS individuallyYou can run the add-on outside of Home Assistant (e.g. on a remote RPI sending MQTT data of WiFI). All you need is an operating system supported by bleak. See doc/Standalone.md