esphome-ant-bms

June 16, 2026 · View on GitHub

GitHub actions GitHub stars GitHub forks GitHub watchers "Buy Me A Coffee"

ESPHome component to monitor and control a ANT-BMS via UART or BLE

Lovelace entities card

Supported devices

Untested devices

  • ANT H-24S 180A

Requirements

Schematics

                UART-TTL
┌──────────┐                ┌─────────┐
│          │<----- RX ----->│         │
│ ANT-BMS  │<----- TX ----->│ ESP32/  │
│          │<----- GND ---->│ ESP8266 │<-- 3.3V
│          │<----- 3.3V --->│         │<-- GND
└──────────┘                └─────────┘



│                ANT-BMS                 │
│                                        │
│  Comm                            Temp  │
└─[oooo]──[oooooooo]──[oooooooo]──[oooo]─┘
   ││││
   ││││      (ESP32)    /    (ESP8266)
   ││││
   │││└─ TXD (GPIO16)        (GPIO4)
   ││└── RXD (GPIO17)        (GPIO5)
   │└─── GND (GND)           (GND)
   └──── VCC (3.3V)          (3.3V)

The connector is a 4 Pin JST 1.25mm. It's important to connect VCC too because the BMS doesn't respond/start if you connect TXD, RXD and GND only.

https://github.com/syssi/esphome-ant-bms/issues/1#issuecomment-1049048825

Installation

You can install this component with ESPHome external components feature like this:

external_components:
  - source: github://syssi/esphome-ant-bms@main

or just use the esp32-example.yaml as proof of concept:

# Install esphome
pip3 install esphome

# Clone this external component
git clone https://github.com/syssi/esphome-ant-bms.git
cd esphome-ant-bms

# Create a secrets.yaml containing some setup specific secrets
cat > secrets.yaml <<EOF
wifi_ssid: MY_WIFI_SSID
wifi_password: MY_WIFI_PASSWORD

mqtt_host: MY_MQTT_HOST
mqtt_username: MY_MQTT_USERNAME
mqtt_password: MY_MQTT_PASSWORD

bms0_mac_address: MY_BMS_MAC_ADDRESS
# The esp32-ble-example-multiple-devices.yaml additionally expects a bms1_mac_address.
bms1_mac_address: MY_BMS_MAC_ADDRESS_1
EOF

# Validate the configuration, create a binary, upload it, and start logs
# If you use a esp8266 run the esp8266-examle.yaml
esphome run esp32-example.yaml

Example response all sensors enabled

[sensor:125]: 'ant-bms total voltage': Sending state 54.10000 V with 2 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 1': Sending state 4.13800 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 2': Sending state 4.13800 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 3': Sending state 4.13500 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 4': Sending state 4.13800 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 5': Sending state 4.13800 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 6': Sending state 4.13600 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 7': Sending state 4.13600 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 8': Sending state 4.13600 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 9': Sending state 4.13400 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 10': Sending state 4.13700 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 11': Sending state 4.13600 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 12': Sending state 4.13700 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms cell voltage 13': Sending state 4.14000 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms current': Sending state 0.00000 A with 1 decimals of accuracy
[sensor:125]: 'ant-bms soc': Sending state 100.00000 % with 0 decimals of accuracy
[sensor:125]: 'ant-bms total battery capacity setting': Sending state 39.00000 Ah with 2 decimals of accuracy
[sensor:125]: 'ant-bms capacity remaining': Sending state 38.99547 Ah with 2 decimals of accuracy
[sensor:125]: 'ant-bms battery cycle capacity': Sending state 575.37402 Ah with 2 decimals of accuracy
[sensor:125]: 'ant-bms temperature 1': Sending state 21.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms temperature 2': Sending state 21.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms temperature 3': Sending state 20.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms temperature 4': Sending state 20.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms temperature 5': Sending state 20.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms temperature 6': Sending state 20.00000 °C with 0 decimals of accuracy
[sensor:125]: 'ant-bms charge mosfet status code': Sending state 1.00000  with 0 decimals of accuracy
[text_sensor:067]: 'ant-bms charge mosfet status': Sending state 'On'
[sensor:125]: 'ant-bms discharge mosfet status code': Sending state 1.00000  with 0 decimals of accuracy
[text_sensor:067]: 'ant-bms discharge mosfet status': Sending state 'On'
[sensor:125]: 'ant-bms balancer status code': Sending state 0.00000  with 0 decimals of accuracy
[text_sensor:067]: 'ant-bms balancer status': Sending state 'Off'
[sensor:125]: 'ant-bms power': Sending state 0.00000 W with 1 decimals of accuracy
[sensor:125]: 'ant-bms min cell voltage': Sending state 4.14000 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms max cell voltage': Sending state 4.13400 V with 3 decimals of accuracy
[sensor:125]: 'ant-bms average cell voltage': Sending state 4.13600 V with 2 decimals of accuracy
[sensor:125]: 'ant-bms battery strings': Sending state 13.00000  with 0 decimals of accuracy
[switch:037]: 'ant-bms charging': Sending state ON
[switch:037]: 'ant-bms discharging': Sending state ON
[switch:037]: 'ant-bms balancer': Sending state OFF
[text_sensor:067]: 'ant-bms total runtime formatted': Sending state '6d 7h '
[sensor:124]: 'ant-bms total runtime': Sending state 546592.00000 s with 0 decimals of accuracy

Protocol

Status frame

OffsetLenExample valueFieldDecoded valueCoeff./Unit
040xAA 0x55 0xAA 0xFFHeader
420x02 0x1DTotal voltage541 * 0.1 = 54.1V0.1 V
620x10 0x2ACell voltage 14138 * 0.001 = 4.138V0.001 V
820x10 0x2ACell voltage 24138 * 0.001 = 4.138V0.001 V
1020x10 0x27Cell voltage 34135 * 0.001 = 4.135V0.001 V
1220x10 0x2ACell voltage 40.001 V
1420x10 0x2ACell voltage 50.001 V
1620x10 0x28Cell voltage 60.001 V
1820x10 0x28Cell voltage 70.001 V
2020x10 0x28Cell voltage 80.001 V
2220x10 0x26Cell voltage 90.001 V
2420x10 0x29Cell voltage 100.001 V
2620x10 0x28Cell voltage 110.001 V
2820x10 0x29Cell voltage 120.001 V
3020x10 0x2CCell voltage 130.001 V
3220x00 0x00Cell voltage 140.001 V
3420x00 0x00Cell voltage 150.001 V
3620x00 0x00Cell voltage 160.001 V
3820x00 0x00Cell voltage 170.001 V
4020x00 0x00Cell voltage 180.001 V
4220x00 0x00Cell voltage 190.001 V
4420x00 0x00Cell voltage 200.001 V
4620x00 0x00Cell voltage 210.001 V
4820x00 0x00Cell voltage 220.001 V
5020x00 0x00Cell voltage 230.001 V
5220x00 0x00Cell voltage 240.001 V
5420x00 0x00Cell voltage 250.001 V
5620x00 0x00Cell voltage 260.001 V
5820x00 0x00Cell voltage 270.001 V
6020x00 0x00Cell voltage 280.001 V
6220x00 0x00Cell voltage 290.001 V
6420x00 0x00Cell voltage 300.001 V
6620x00 0x00Cell voltage 310.001 V
6820x00 0x00Cell voltage 320.001 V
7040x00 0x00 0x00 0x00Current0.0 A0.1 A
7410x64SOC100 %1.0 %
7540x02 0x53 0x17 0xC0Total Battery Capacity Setting390000000.000001 Ah
7940x02 0x53 0x06 0x11Battery Capacity Remaining0.000001 Ah
8340x00 0x08 0xC7 0x8EBattery Cycle Capacity575374 * 0.001 = 575.374 Ah0.001 Ah
8740x00 0x08 0x57 0x20Uptime in seconds546.592 s1.0 s
9120x00 0x15Temperature 121°C1.0 °C
9320x00 0x15Temperature 221°C1.0 °C
9520x00 0x14Temperature 320°C1.0 °C
9720x00 0x14Temperature 420°C1.0 °C
9920x00 0x14Temperature 520°C1.0 °C
10120x00 0x14Temperature 620°C1.0 °C
10310x01Charge MOSFET Status
10410x01Discharge MOSFET Status
10510x00Balancer Status
10620x03 0xE8Tire lengthmm
10820x00 0x17Number of pulses per week
11010x01Relay switch
11140x00 0x00 0x00 0x00Current power0W1.0 W
11510x0DCell with the highest voltageCell 13
11620x10 0x2CMaximum cell voltage4140 * 0.001 = 4.140V0.001 V
11810x09Cell with the lowest voltageCell 9
11920x10 0x26Minimum cell voltage4134 * 0.001 = 4.134V0.001 V
12120x10 0x28Average cell voltage4136 * 0.001 = 4.136V0.001 V
12310x0DCell count13
12420x00 0x00Discharge MOSFET, voltage between D-S0.1 V
12620x00 0x73Drive voltage (discharge MOSFET)0.1 V
12820x00 0x6FDrive voltage (charge MOSFET)0.1 V
13020x02 0xA7When the detected current is 0, the initial value of the comparator
13240x00 0x00 0x00 0x00Battery is in balance bitmask (Bit 1 = Cell 1, Bit 2 = Cell 2, ...)
13620x11 0x62System log / overall status bitmask?
13820x0B 0x00CRC

Known issues

  • ESP32: Adding all supported sensors can lead to a stack overflow / boot loop. This can be solved by increasing the stack size. (#36)
  • A command queue / command scheduling would be nice. At the moment changing settings via the switch entities isn't reliable.

Debugging

If this component doesn't work out of the box for your device please update your configuration to enable the debug output of the UART component and increase the log level to the see outgoing and incoming serial traffic:

logger:
  level: DEBUG

uart:
  id: uart_0
  baud_rate: 19200
  rx_buffer_size: 384
  tx_pin: ${tx_pin}
  rx_pin: ${rx_pin}
  debug:
    direction: BOTH

References