batmon-ha

Home Assistant Add-on: BatMON

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 or ESP32). It can also run without HA on Linux, macOS and Windows.

I created this to compare BMS readings for a detailed evaluation of BMS reliability and accuracy.

Features

• Uses Bluetooth Low-Energy (BLE) for wireless communication
• Captures SoC, Current, Power, individual cell voltages and temperatures
• Monitor multiple devices at the same time
• Energy consumption meters (using trapezoidal power integrators)
• Integrates with Home Assistant Energy dashboard and Utility Meter sensor helper
• Control BMS charging and discharging switches
• Set the SOC gauge from HA via a set SOC number entity, e.g. to reset a drifted gauge to 0 % after a low-voltage cut-off: Daly (daly, daly_uart) and JK with firmware >= 11 (jk, jk_32s) (#144)
• Home Assistant MQTT Discovery
• Can run as stand-alone app without Home-Assistant and directly write to InfluxDB
• Battery Groups for parallel batteries, see doc/Groups.md
• Charge Algorithms, see doc/Algorithms.md
• Low latency for responsive automation (fast load shedding)
• Experimental serial communication for JK and Daly BMS
• Current sensor gain calibration
• Custom bluetooth stack for increased reliability

Supported BLE Devices

Batmon comes with connectors for some popular BMS. It also wraps aiobmsble, which includes many other BMS for read-only access.

batmon device connectors:

• JK BMS / jikong with JK02 protocol (jk over BLE, jk_uart over RS485 — see Serial / RS485)
• JK-PB inverter BMS (PB1A16S, PB2A16S, …; jk over BLE, jk_pb_uart over RS485)
• Daly BMS (daly, daly2, daly_ble over BLE, daly_uart over RS485 — see Serial / RS485)
• JBD / Xiaoxiang / LLT BMS (jbd over BLE, jbd_uart over TTL UART or RS485)
• Seplos V2 BMS, 48 V rack packs (seplos_ble, seplos_v2_ble over BLE, seplos_uart over RS485)
• Renogy smart lithium batteries (renogy_ble over BLE via the BT-2 dongle, renogy_uart over RS485)
• Felicity Solar 48 V LiFePo4 packs (FLB48314TG1, FLB48100, LPBF48/LPBA48; felicity over BLE, felicity_uart over RS485)
• JBD / Jiabaida/ Xiaoxiang / Overkill Solar BMS (jbd)
• ANT BMS (ant)
• Supervolt BMS (supervolt)
• SOK / ABC-BMS (sok, routed through the aiobmsble abc_bms decoder; use sok_legacy for the pre-2023 native driver)
• Basen BMS (basen), ported from syssi/esphome-basen-bms
• LiTime BMS (litime)
• Legacy Offgridtec OGT-12200 / Topband batteries (offgridtec): unsolicited FFE4 ASCII-hex protocol
• BM6 Bluetooth car battery monitor and the Ancel BM200 (bm6): voltage, temperature, SOC and charging/low-voltage state, no current (#160, #41)
• Quicklynks BM2 and rebrands (bm2): voltage and SOC. An Ancel BM200 reads with bm6, not bm2 (#41)
• Generic no-name Chinese BMS with Modbus RTU over Nordic UART (noname_modbus) — see issue #131
• Victron SmartShunt (make sure to update to the latest firmware and enable GATT in the VictronConnect app) (victron)

More aiobmsble device connectors:

• CBT Power / Creabest smart BMS (cbtpwr)
• Seplos smart BMS V3 (seplos), Seplos smart BMS V2 (seplos_v2)
• TianPwr smart BMS (tianpwr)
• ATORCH CW20 DC Meter (cw20)
• TDT smart BMS (tdt; tdt_nocrc for units with broken CRC firmware, e.g. Humsienk golf-cart batteries — see issue #394)
• E&J Technology smart BMS (ej)
• Chunguang Song ABC-BMS (abc)
• D-powercore smart BMS (dpwrcore)
• ECO-WORTHY BW02 (ecoworthy)
• Ective smart BMS (ective)
• Felicity Solar LiFePo4 battery (felicity)
• Offgridtec LiFePo4 Smart Pro (ogt)
• Redodo Bluetooth battery (redodo)
• RoyPow smart BMS (roypow)
• Braun Power smart BMS (braunpwr)
• Neey Balancer (neey)
• Pro BMS Smart Shunt (pro)
• Renogy Bluetooth battery (renogy), Renogy BT battery pro (renogy_pro)
• all other devices aiobmsble supports

You can switch from the batmon to the aiobmsble connectors, just append a _ble to the type field, e.g. instead of type: daly (batmon), write type: daly_ble (aiobmsble). This can help if you experience connection issues, because some of the aiobmsble connectors are more up to date.

I tested the add-on on a Raspberry Pi 4 and 5 using Home Assistant Operating System.

Installation

• Go to your Home Assistant Add-on store and add this repository: https://github.com/fl4p/home-assistant-addons
• Install Batmon add-on
• Install, configure and start Mosquitto MQTT broker (don’t forget to configure the MQTT integration)

Configuration

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 PIN, victron and newer JBD firmware (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)
  display_name: House battery     # device name in HA; topics stay (optional)
  temperature_names: Cell 1,Cell 2 # probe names in HA, in order (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, jk_24s, jk_32s, jk_uart, jk_pb_uart, jbd, jbd_uart, ant, daly, daly2, daly_ble, daly_uart, pace_uart, seplos_uart, braunpwr_uart, renogy_uart, felicity_uart, supervolt, sok, sok_legacy, basen, basen_uart, litime, offgridtec, bm6, bm2, victron, or any tag listed under Supported BLE Devices. For a mock BMS use dummy.

type: auto (Bluetooth only) asks the device at every start which protocol it speaks and logs the type: to put in the config instead. It knows daly (A5), daly2 (Modbus), jbd, jk, ant, bm2 and bm6, and accepts a type only on a valid reply to a read request, sent to that driver’s own characteristic (bm2 is detected by listening only, the device pushes its frames). A device that doesn’t answer is skipped with an error, never guessed. Any other BMS still needs its type: set by hand.

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.

display_name sets the device name shown in Home Assistant, and temperature_names names the temperature probes in order. Neither changes MQTT topics or unique IDs, so entity history is kept.

For jbd, batmon also reads the identity and settings registers (manufacturer, model, manufacture date, capacity, protection thresholds, balancing, voltage curve) once per start and publishes them under jbd/. These registers need factory mode, which batmon leaves without saving, so no setting is changed.

jbd charge and discharge switches write the MOS register inside factory mode, keep the other MOSFET’s state, and read the state back, so a refused change is logged as an error. On firmware 3.2 this re-enabled charging after an undervoltage cut-off. It does not override an active protection; a state a protection holds is not rewritten for 10 minutes, since each write saves to the BMS’s EEPROM. With keep_alive: false a switch command waits for the next poll.

If the device requires a PIN when pairing add pin: "123456" (and replace 123456 with the device’s PIN). This is the case for the Victron SmartShunt and for newer JBD firmware (Liontron and other packs whose app asks for a 6-digit password): those BMS only answer after a passkey pairing, batmon pairs with the given pin and then talks the normal JBD protocol (#217). Felicity packs whose firmware update renamed them from F07… to SolarB_… need this too (#415, upstream BMS_BLE-HA#735). Three FLB48314TG1-H packs were confirmed working once every pack was bonded — but bonding alone was not enough there: one pack was already bonded and still failed with failed to discover services, device disconnected until Home Assistant’s own Bluetooth integration was disabled, which frees the adapter from scan contention. If a bonded pack still fails, try that next.

The bond is made by BlueZ (the same operation as bluetoothctl pair), before the add-on starts sampling, and stays in place afterwards. It needs a local Bluetooth adapter: an ESPHome proxy can be asked to pair, but has no agent to answer a PIN prompt, so a device with a pin: has to be reached through an adapter on the machine running the add-on.

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.

• Set MQTT user and password. MQTT broker is usually 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. It does not change how long a BMS is given to answer — see ble_request_timeout for that.
• ble_request_timeout is how long an aiobmsble device (felicity, daly_ble, any tag from Supported BLE Devices) gets to answer one request, in seconds. The default is the library’s 5 s, split over three attempts with doubling waits (0.71 s, 1.43 s, 2.86 s), so a pack slower than 0.71 s only answers on a retry. Raise it (e.g. 12) if a device times out in _await_msg while others on the same adapter are being polled. Note that a device whose write mode aiobmsble has not pinned down yet runs that sequence twice (once per mode), so a fully silent pack takes about twice the configured value before it gives up — and a slow poll pushes out the whole cycle, since sample_period is slept after the poll, not instead of it. It is necessarily global: aiobmsble holds the value on its base class, so it applies to every _ble device at once, and a per-device setting would be a lie (#415).
• Set 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”
• impedance_estimator (experimental, off by default) estimates the per-cell resistance of LiFePO4 packs and publishes it as a Cell Resistance sensor in mΩ. See doc/Cell Resistance.md.
• soh_estimator (experimental, off by default) estimates the present capacity of LiFePO4 packs from long rests and the charge counted between them, as Qmax (est.) (Ah) and SoH (est.) (%) sensors, against the per-device capacity: (Ah, the nameplate of this one pack, not of the bank), without which it publishes nothing. On its built-in OCV curve it gives no value yet; see doc/SoH.md.
• pack_temp_estimator (experimental, off by default) estimates the cell temperature of packs whose BMS only reports a MOSFET temperature, as a Pack Temp (RC est.) sensor. pack_temp_room_topic / pack_temp_outdoor_topic are MQTT topics carrying ambient temperatures (e.g. from HA’s mqtt_statestream); both are optional, without them the estimate follows the MOSFET temperature, damped. See bmslib/PACK_TEMP_RC_INTEGRATION.md.
• jk_settings (off by default) reads the settings of JK BMSes (BLE, firmware ≥ 11) and shows them in Home Assistant. A device’s settings_write (all and/or a comma list of names; all leaves out critical settings) makes them changeable, with backup and read-back check. See doc/JK-Settings.md.
• watchdog stops the program on too many errors (make sure to enable the Home Assistant watchdog to restart the add-on after it exits)
• For JK bms: set type to jk_24s for the older 24s version (firmware<11.x), jk_32s for the newer 32s version (fw> =11.x), or jk if you don’t know (might cause invalid battery data when detection fails)
• type daly2 is for Daly BMS that speak Modbus over BLE (H/K/M/S series, frames start with D2). Reads, cell voltages and MOSFET switches work, see issue #356. The GATT layout doesn’t tell the two Daly protocols apart: both use service fff0 with fff1/fff2. If daly2 only times out, use daly (classic A5 frames, J/T/A/U/W series), or run type: snoop:daly and check whether the replies start with a5 (#416)

Serial / RS485

Some BMS expose an RS485 (or TTL UART) port in addition to BLE. Batmon can read those directly with a USB-to-RS485 adapter, no Bluetooth needed. This path is independent of ble_stack and works even with Bluetooth disabled.

Supported types (baud rate in parentheses):

• jk_uart (115200) — JK / Jikong, native UART TLV protocol (4E 57 …), distinct from the BLE format.
• daly_uart (9600) — Daly, same A5 … 13-byte frames as Daly BLE.
• pace_uart (9600) — PACE ASCII “paceic” protocol (~2501…\r) used by PACE server-rack packs (SOK, SunGoldPower, Sunsynk rebrands, PbmsTools); distinct from the BLE pace_aiobmsble (#276).
• basen_uart (9600) — Basen binary 7E … 0D protocol; distinct from the BLE basen.
• jbd_uart (9600) — JBD / Xiaoxiang / LLT, same DD … 77 frames as the BLE jbd (the BLE module is a UART bridge); TTL UART header or RS485 port.
• jbd_hv_uart (9600) — JBD / LWS high-voltage BMS (HVBMS, up to 200 cells) on its RS485 port: binary 3F 55 … 55 3F replies to 01 A1 A5 B5, the protocol of the vendor PC tool (not the supplier’s Modbus document). Cell voltages and temperatures, current, SOC, pack and P+/P- voltage, MOS and ambient temperature, insulation resistance. jbd_hv_uart:<addr> for the pack address (default 1) (#424).
• jk_pb_uart (115200) — JK-PB inverter BMS (PB1A16S, PB2A16S, …) on its RS485-1 port: a Modbus FC16 trigger, answered with the JK02_32S frame the BLE driver decodes. jk_pb_uart:<n> selects the RS485 address set in the JK app (default 1). The older jk_uart TLV protocol does not work on PB models.
• seplos_uart (19200) — Seplos V2 (BMS 1.0/2.0 hardware) ASCII protocol (~2000 46 42 …\r); seplos_uart:<addr> for the pack address (default 0), seplos_uart:<addr>:9600 for the RS232 console port. Seplos V3 (Modbus) is not covered.
• braunpwr_uart (9600) — BraunPWR packs with the KS48100 rack BMS: YD/T 1363 ASCII protocol (>22 01 4A 42 …\r, command 42H). braunpwr_uart:<addr> for the pack address (default 1). It follows the DIP switch, but how is unverified; if nothing answers, try 1 to 16. Connect a USB-RS485 adapter to the packs’ RS485 port: in #403 two parallel packs answered on one bus as addresses 1 and 2, so add one device per pack on the same adapter. Needs the BMS’s inverter protocol set to Voltronic: in Pylontech mode the packs answer only Pylontech ~ system-summary requests. The BMS’s internal 4-pin UART header (where its FC41D WiFi/BLE module plugs in) speaks the same protocol, but avoid it: its GND is the battery’s, not the host’s earth, and four plain USB-TTL adapters burned out on it in #403. Decoder checked against real reply frames (#403).
• renogy_uart (9600) — Renogy smart lithium (RBT100LFP12, RBT200LFP12S, …) Modbus RTU; renogy_uart:<id> for the slave id (default 0x30; the RBT100LFP12SH-G1 uses 0xF7).
• felicity_uart (9600) — Felicity Solar 48 V packs (FLB48314TG1, FLB48100, LPBF48/LPBA48) on the RS485 pins 5/6 of their RJ45 port: the Voltronic “LIB” protocol, Modbus RTU function 0x03 with a 16-bit register count in place of Modbus’s byte count. felicity_uart:<addr> for the bus address (default 1); several packs share one adapter, one device entry each. The FLB48314TG1 has no DIP switches — the packs auto-assign consecutive addresses, so start at 1 and add entries until one stops answering. The assignment is stable across a power cycle and survives adding or removing a pack (a pack joining a running bus takes the next free address), but it does not follow the wiring order, so identify each pack by its readings rather than its position before giving it an alias. Address 0 never answers. An alternative to the BLE felicity for setups troubled by bonding or adapter scan contention (#415); it has not been run on hardware yet, so no claim that it is the more reliable path.

pace_uart, basen_uart, jbd_uart, jbd_hv_uart, jk_pb_uart, seplos_uart, braunpwr_uart, renogy_uart and felicity_uart decoders are unit-tested against captured or reference frames but not yet confirmed on live hardware — feedback welcome. The protocols were ported from dbus-serialbattery, aiobmsble and the syssi ESPHome components; see the module docstrings for the exact sources.

Example config:

- address: serial
  adapter: /dev/ttyUSB0   # serial port path; required when address=serial
  type: jk_uart
  alias: battery1

address: serial selects the wired transport; adapter is then the serial port path (/dev/ttyUSB0, /dev/ttyAMA0, COM3, …) instead of a Bluetooth HCI index. As an HA add-on this works out of the box (the manifest sets uart: true, mapping the host’s serial devices into the container) — prefer the stable /dev/serial/by-id/... path so the port survives re-plugging. Running standalone on Linux, add your user to the dialout group.

A serial adapter on a network serial server (ser2net, an ESP USB gateway, …) works as adapter: tcp://192.168.1.108:8880 (raw TCP) or rfc2217://host:port. With raw TCP, set the baud rate on the server.

Daly board number

Daly puts the board number in the request, so a BMS whose board number isn’t the factory default 1 answers nothing at all. Append it to the type:

- address: serial
  adapter: /dev/ttyUSB0
  type: daly_uart:2       # RS485 board number 2 (omit `:2` for board 1)
  alias: battery2

Daly’s PC tool calls this “Board No”.

Several Daly on one RS485 bus

Give each unit a distinct board number in Daly’s PC tool, then point them all at the same adapter: — one USB adapter for the whole string, not one each:

- address: serial
  adapter: /dev/ttyUSB0
  type: daly_uart:1
  alias: battery1
- address: serial
  adapter: /dev/ttyUSB0     # same port
  type: daly_uart:2
  alias: battery2

Batmon opens the port once, shares it, and routes each reply to the unit whose board number it carries. Requests are serialized across the bus, so this is safe with concurrent_sampling too (RS485 is half duplex — only one unit may transmit at a time).

Two units configured with the same board number are rejected at connect: they would answer each other’s requests and publish each other’s readings. Mixing families on one port (say jk_uart at 115200 and daly_uart at 9600) is rejected for the same reason — one wire cannot run two baud rates.

Troubleshooting a silent wired link

timeout awaiting result for cmd=0x93, got 0/1 responses means no reply was decoded. The message now says whether any bytes arrived at all — 0 bytes received is a wiring/adapter/port problem, while a non-zero count with 0 valid frames points at the baud rate or the board number.

For Daly, tools/daly_serial_probe.py sweeps board numbers, payload fill bytes and RTS/DTR states and dumps every raw byte, so one run tells you which board answers (or that nothing does):

python3 tools/daly_serial_probe.py /dev/serial/by-id/usb-FTDI_...-port0

Wiring, as confirmed on a Daly 4S in #398: the Daly-supplied XH 5-pin RS485/CAN cable is pin 1 = B−, pin 2 = A+, pin 3 = GND, pins 4–5 = CAN. GND must be connected — without it there is no communication at all. A plain FTDI USB-RS485 adapter works.

Daly’s UART (TTL) and RS485 are separate ports with different pinouts. On some boards they share one UART with the Bluetooth module, so BT and a wired link cannot both be used; on others (including recent ones with two UART headers) they run at the same time. If in doubt, unplug the BT module and retest.

To request another BMS family over RS485, open an issue with a captured frame (tcpdump of the USB-serial line, or a wireshark log from the vendor’s PC tool).

Adding a new BMS

If your BMS isn’t supported yet, set type: snoop (optionally type: snoop:jbd,jk,daly,ant,sok,supervolt to also write known probe frames) on the device entry. Batmon will connect, dump the GATT tree, and log every notification byte the device sends — enough to reverse-engineer the protocol or share with us in an issue. See doc/SNOOP.md.

BLE Stack

Batmon can talk to your BMS through one of four Bluetooth backends. Pick one with the global ble_stack option:

• bleak (default) — uses bleak, a cross-platform Python BLE library that wraps the OS’s native stack: BlueZ on Linux, CoreBluetooth on macOS, WinRT on Windows. On Linux (and therefore inside the HA add-on) it talks to bluetoothd over D-Bus and coexists with Home Assistant’s Bluetooth integration — the adapter stays in the HA Bluetooth pool and is shared. This is the most compatible option and what you want unless you’re chasing a specific problem.

• bumble — uses bumble, a pure-Python BLE stack that talks HCI directly (no BlueZ, no D-Bus). Cross-platform (Linux/macOS/Windows via HCI socket, USB dongle, or serial transports). Always needs exclusive HCI access to its controller — on Linux that means bumble brings the BlueZ-managed adapter down, so it leaves the HA Bluetooth pool. You need to dedicate one adapter to it and disable it in HA under Integrations / Bluetooth; Use it for best reliability and if you have many BMS.

• bluek — talks to the kernel BlueZ stack directly over L2CAP and mgmt sockets (no D-Bus). Coexists with bluetoothd, so the adapter stays in the HA Bluetooth pool. Useful when D-Bus is the bottleneck but you don’t want to take the adapter away from HA. Linux only (BlueZ is Linux-specific). fl4p/bluek

• esphome — routes all BLE through one or more ESPHome Bluetooth Proxy devices (typically a cheap ESP32 flashed with the upstream bluetooth-proxies firmware). The add-on doesn’t touch any local Bluetooth adapter — you can extend BLE reach to wherever your BMSes physically live (other rooms, outdoors) just by powering an ESP32 there. An ESPHome proxy serves BLE to one client only: its advertisements and the data of every BLE connection go to whichever API client subscribed last (ESPHome ≥ 2026.7; before that, the first). If Home Assistant also uses the proxy, whichever of HA and the add-on reconnects last takes it over, and the other silently gets nothing: an HA restart stops every BMS on the proxy until the add-on reconnects, and the add-on winning cuts off HA’s own BLE devices there. Use proxies dedicated to the add-on: remove them from HA’s ESPHome integration or leave them out of HA. To share one proxy between HA and the add-on, flash nimble-ble-proxy ≥ 0.2.0 instead (browser flasher): it serves up to 4 API clients at once, and each BLE link belongs to the client that opened it, so an add-on restart frees its BMS links. Each proxy has 3 BLE connection slots by default (see esphome_proxy/README.md). Configure the proxies under the bluetooth_proxies: add-on option:

  ble_stack: esphome
  bluetooth_proxies:
    - host: garage-proxy.local
      noise_psk: "<base64 Noise key from the proxy's ESPHome config>"
      name: "garage"          # diagnostic label only
    - host: 192.168.1.43
      noise_psk: "<another key>"
  

  Proxy firmware should set bluetooth_proxy: { active: true, cache_services: false } — see bmslib/esphome_proxy/README.md for the rationale and a known incompatibility (ANT-BLE20PHUB BMS).

bumble, bluek and esphome are experimental — try bleak first. Users have already reported that bluek helps in case of connection timeouts.

adapter: per BMS

The per-device adapter: option only applies to backends that have a notion of a local Bluetooth adapter:

(For address: serial / RS-485 BMSes, adapter: is the serial port path like /dev/ttyUSB0 or a network port like tcp://host:8880, independent of ble_stack.)

adapter: can also be set once at the top level of the configuration, next to ble_stack:. It is then the default for every device that doesn’t carry its own, and the log says which devices inherited it. Because the value means two different things, only matching devices inherit: a controller (hci1, or its MAC) goes to BLE devices, an absolute port path (/dev/ttyUSB0) to wired ones. Groups and commented-out devices never inherit. A top-level adapter: that reaches no device — or that is neither a controller nor an absolute path — is reported instead of quietly doing nothing (#414).

Energy Meters

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.

Troubleshooting

• Power cycle (turn off and on) the BMS Bluetooth hardware/dongle (or BMS)
• Enable bt_power_cycle. If it doesn’t work, manually power cycle Bluetooth on the host you are running batmon on #91.
• When experiencing unstable connection enable keep_alive
• TimeoutError: timeout waiting: put BT devices closer, disable inverters and other EMI sources
• Try another ble_stack: bumble for exclusive adapter access (you need to remove it from HA Integration first), or bluek to bypass D-Bus on Linux (has helped with timeouts)
• Enable verbose_log and check the logs. If that is too noisy set debug: true in the BMS configuration as described above
• Try to find the BMS with a BLE scan (Chrome Browser, linux)
• After a long-lasting bluetooth connection is lost both Daly and JBD dongles occasionally refuse to accept new connections and disappear from bluetooth discovery. Remove wires from the dongle and reconnect for a restart.
• Some users reported unstable Bluetooth connection with Raspberry Pi 4 onboard bluetooth hardware and WiFi enabled. It appears that disabling WiFi helps. (#42)
• Cheap inverters might cause heavy EMI (electromagnetic interference). Turn them off or keep them away from the bluetooth hardware
• Either bleak or bluetooth support in HA docker seems unstable. see related issues 106 109
• Try another bluetooth hardware. Note you can choose the adapter with adapter parameter for each BMS individually
• doc/Downgrade.md to an earlier version
• to see more log entries, run this in the Terminal add-on: ha host logs --identifier addon_<slug>_batmon. You’ll find the slug in the URL of the add-on page.
• to see logs during installation: Settings / System / Logs / Supervisor (choose from the menu at the top-right corner), link

TODO

• Implement daly2 #33
• Port to MicroPython for MCU (ESP32 etc.)
• make this a custom integration? home-assistant-bms-tools-integration
• use the new Bluetooth integration since HA 2022.8 ?
• Implement BMS data push (JK)
• Read device bt info see
• Implement RS485 for more BMS families #22 — JK (jk_uart) and Daly ( daly_uart) are done; JBD, ANT still TODO
• Implement old JK04?
• web interface (export, import bms meter data)

Stand-alone

You 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

To run it in a container instead, see doc/Docker.md: prebuilt multi-arch images (ghcr.io/fl4p/batmon-ha), compose examples, and a Helm chart.

Contribute / Donate

• PayPal
• Patreon (Donations & News)

References

• daly bms: similar add-on
• JK-BMS: similar add-on using ESP-Home (needs extra hardware)
• Daly_RS485_UART_Protocol.pdf
• JK-bms esphome
• JK02 protocol