Home assistant Custom Component for reading data from BYD Battery Box system series like HVL, HVM, HVS, LVS. This integration uses a local modbus connection.
Note
This is a fork of redpomodoro/byd_battery_box. This fork has diverged from the original project and includes additional features, bug fixes, and improvements that are not available upstream.
Caution
This is a work in progress project - it is still in early development stage, so there are still breaking changes possible.
This is an unofficial implementation and not supported by BYD. It might stop working at any point in time. You are using this module (and it's prerequisites/dependencies) at your own risk. Not me neither any of contributors to this or any prerequired/dependency project are responsible for damage in any kind caused by this project or any of its prerequsites/dependencies.
Important
The battery must be connected by LAN cable as the wireless connection disables itself after a timeout. The default IP address of the BYD battery is 192.168.16.254. Later firmware versions seem to support DHCP and will use the assigned IP address. In the later case you will need to look up the address. Depending on your network configuration a static route might be added. You can test connectivity to the battery in the browser by using the batteries address for example http://192.168.16.254 and should get a login page.
Important
Note using other applications connecting to battery simulatousnely might give unexpected results.
This card is available in HACS (Home Assistant Community Store).
HACS is a third party community store and is not included in Home Assistant out of the box.
-
Download and copy Installation to your home-assistant config/custom_components folder.
-
After reboot of Home-Assistant, this integration can be configured through the integration setup UI.
The key BMU Status data will by default refreshed 30 seconds.
Detailed BMS data will be refreshed by default every 10 minutes.
The log data is by default updated every 10 minutes. Log data is stored in /config/custom_components/byd_battery_box/logs folder. The integration uses the json file for storage and for convenience a CSV file is being stored as well.
Use the buttons on the devices to retrieve additional log history, during the update all other data updates will be suspended. The integration writes warnings into log to see progress of the updates.
FAQ: Why isn’t the dashboard under custom_components? The dashboard is a Lovelace frontend plugin (HACS category "plugin"). Frontend resources are JavaScript files, not Python integrations. Therefore it correctly lives under
byd_battery_box_dashboard/and will be installed by HACS into/www/community/byd_battery_box_dashboard/.
| Entity | Description | Unit |
|---|---|---|
| State of charge | Battery state of charge | % |
| State of health | Battery state of health | % |
| BMU temperature | BMU board temperature | °C |
| BMU cell temperature max | Highest cell temperature across all towers | °C |
| BMU cell temperature min | Lowest cell temperature across all towers | °C |
| BMU cell voltage max | Highest cell voltage across all towers | V |
| BMU cell voltage min | Lowest cell voltage across all towers | V |
| BMU current | Battery current (positive = charging) | A |
| BMU battery voltage | Battery bus voltage | V |
| BMU output voltage | Output voltage to inverter | V |
| BMU power | Current power (positive = charging) | W |
| Charge total energy | Lifetime total energy charged | kWh |
| Discharge total energy | Lifetime total energy discharged | kWh |
| Efficiency | Charge/discharge efficiency | % |
| Entity | Description |
|---|---|
| Inverter | Connected inverter model |
| BMU version | BMU firmware version |
| BMU version A / B | BMU firmware version per slot |
| BMS version | BMS firmware version |
| Towers | Number of battery towers |
| Modules | Number of modules per tower |
| Application | Application type |
| Phase | Connection phase |
| Errors | Current error codes |
| Total capacity | Total battery capacity (kWh) |
| Param table version | Parameter table version |
| Cells per module | Number of cells per module |
| Temperature sensors per module | Number of temperature sensors per module |
| Updated | Last data update timestamp |
| BMU last log | Last BMU log entry |
| Log entries | Total log entries (with log list as attribute) |
| Entity | Description | Unit |
|---|---|---|
| Cell voltage max / min | Highest/lowest cell voltage in tower | V |
| Cell voltage max/min number | Cell ID with highest/lowest voltage | - |
| Cell temperature max / min | Highest/lowest cell temperature in tower | °C |
| Cell temperature max/min number | Cell ID with highest/lowest temperature | - |
| State of charge | Tower SOC | % |
| State of health | Tower SOH | % |
| Current | Tower current | A |
| Battery voltage | Tower battery voltage | V |
| Output voltage | Tower output voltage | V |
| Charge total energy | Tower lifetime charge energy | kWh |
| Discharge total energy | Tower lifetime discharge energy | kWh |
| Efficiency | Tower charge/discharge efficiency | % |
| Cells balancing | Number of cells currently balancing | - |
| Cells average voltage | Average cell voltage | V |
| Cells average temperature | Average cell temperature | °C |
| Max/Min history cell voltage | Historical max/min cell voltage | V |
| Balancing total | Total balancing events | - |
| Entity | Description |
|---|---|
| Warnings | Current warning codes |
| Errors | Current error codes |
| Updated | Last BMS data update timestamp |
| Last log | Last BMS log entry |
| Entity | Description | Unit |
|---|---|---|
| Connection Quality | Modbus connection success rate | % |
| Last Latency | Last measured Modbus round-trip time | ms |
| Average Latency | Average Modbus round-trip time | ms |
| Consecutive Failures | Number of consecutive connection failures | - |
| Connection Health | Overall connection health status | - |
For a rich, interactive dashboard experience, check out the companion Lovelace card: BYD Battery Box Visualization
Features:
- Visualize modules and cells with current, min/max voltages and temperatures
- Per-cell voltage bars with balancing indicators
- SOC bar with animated charge/discharge status
- Support for up to 3 battery towers
- Toggle between voltage (mV) and temperature view
- Interactive tooltips on hover/click
- Install via HACS as a Frontend/Lovelace plugin
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% if states('sensor.log_entries') | is_number %} {% set log =
state_attr('sensor.log_entries','log')%} | Timestamp | Unit | Code |
Description | Details |
|:---|:---|---:|:---|:---|
{% for l in log %} |{{ l['ts'] }}|{{ l['u'] }}|{{ l['c'] }}|{{
l['d'] }}|{{ l['detail'] }}|
{% endfor %} {% endif %}
title: Log
grid_options:
columns: full
rows: auto
column_span: 2
Voltages Table in mV
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% if states('sensor.bms_1_cells_average_voltage') | is_number %}
{% set
sensors=['sensor.bms_1_cells_average_voltage','sensor.bms_2_cells_average_voltage','sensor.bms_3_cells_average_voltage']%}
{% set cell_count = int(states('sensor.cells_per_module')) %} {%
for u in range(1,int(states('sensor.towers'))+1)%}
{% set modules = state_attr(sensors[u-1],'cell_voltages')%} | BMS
{{u}} |{% for i in range(1,cell_count+1)%}Cell {{i}}|{%- endfor %}
|:---|{% for i in range(1,cell_count+1) %}---:|{% endfor %}
{% for m in modules %}{% set cells = m['v'] %}|Module {{ m['m']
}}|{% for v in cells %}{{ v }}|
{%- endfor %}
{% endfor %}
{%- endfor %} {% endif %}
title: Cell Voltages in mV
grid_options:
columns: full
rows: auto
column_span: 2
Voltages Table in V
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% set
sensors=['sensor.bms_1_cells_average_voltage','sensor.bms_2_cells_average_voltage','sensor.bms_3_cells_average_voltage']%}
{% set cell_count = int(states('sensor.cells_per_module')) %} {%
for u in range(1,int(states('sensor.towers'))+1)%}
{% set modules = state_attr(sensors[u-1],'cell_voltages')%} | BMS
{{u}} |{% for i in range(1,cell_count+1)%}Cell {{i}}|{%- endfor %}
|:---|{% for i in range(1,cell_count+1) %}---:|{% endfor %}
{% for m in modules %}{% set cells = m['v'] %}|Module {{ m['m']
}}|{% for v in cells %}{{ '%.3f' | format(v/1000) }}|
{%- endfor %}
{% endfor %}
{%- endfor %}
title: Cell Voltages in V
grid_options:
columns: full
rows: auto
column_span: 2
Temperatures Table
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% if states('sensor.bms_1_cells_average_temperature') | is_number
%} {% set
sensors=['sensor.bms_1_cells_average_temperature','sensor.bms_2_cells_average_temperature','sensor.bms_3_cells_average_temperature']%}
{% set cell_count = int(int(states('sensor.cells_per_module')) /
2) %} {% for u in range(1,int(states('sensor.towers'))+1)%}
{% set modules = state_attr(sensors[u-1],'cell_temps')%} | BMS
{{u}} |{% for i in range(1,cell_count+1)%}Cell
{{i*2-1}}-{{i*2}}|{%- endfor %}
|:---|{% for i in range(1,cell_count+1) %}---:|{% endfor %}
{% for m in modules %}{% set cells = m['t'] %}|Module {{ m['m']
}}|{% for t in cells %}{{ t }}|
{%- endfor %}
{% endfor %}
{%- endfor %} {% endif %}
title: Cell Temperatures in °C
grid_options:
columns: full
rows: auto
column_span: 2
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% if states('sensor.bms_1_balancing_total') | is_number %} {% set
sensors=['sensor.bms_1_balancing_total','sensor.bms_2_balancing_total','sensor.bms_3_balancing_total']%}
{% set cell_count = int(states('sensor.cells_per_module')) %} {%
for u in range(1,int(states('sensor.towers'))+1)%}
{% set modules = state_attr(sensors[u-1],'total_cells')%} | BMS
{{u}} |{% for i in range(1,cell_count+1)%}Cell {{i}}|{%- endfor %}
|:---|{% for i in range(1,cell_count+1) %}---:|{% endfor %}
{% for m in modules %}{% set cells = m['bct'] %}|Module {{ m['m']
}}|{% for v in cells %}{{ v }}|
{%- endfor %}
{% endfor %}
{%- endfor %} {% endif %}
title: Cell Balancing Totals
grid_options:
columns: full
rows: auto
column_span: 2
- type: grid
cards:
- type: markdown
style: |
ha-card {
width: 100%;
}
content: >
{% if states('sensor.bms_1_cells_balancing') | is_number %} {% set
sensors=['sensor.bms_1_cells_balancing','sensor.bms_2_cells_balancing','sensor.bms_3_cells_balancing']%}
{% set cell_count = int(states('sensor.cells_per_module')) %} {%
for u in range(1,int(states('sensor.towers'))+1)%}
{% set modules = state_attr(sensors[u-1],'cell_balancing')%} | BMS
{{u}} |{% for i in range(1,cell_count+1)%}Cell {{i}}|{%- endfor %}
|:---|{% for i in range(1,cell_count+1) %}---:|{% endfor %}
{% for m in modules %}{% set cells = m['b'] %}|Module {{ m['m']
}}|{% for b in cells %}{% if b == 1%}on{%else%}-{%endif%}|
{%- endfor %}
{% endfor %}
{%- endfor %} {% endif %}
title: Cells Balancing
grid_options:
columns: full
rows: auto
column_span: 2
- https://github.com/redpomodoro/byd_battery_box - Original project (upstream)
- https://github.com/TimWeyand/byd_battery_box_visualization - Companion Lovelace visualization card
- https://github.com/sarnau/BYD-Battery-Box-Infos/blob/main/Read_Modbus.py
- https://github.com/christianh17/ioBroker.bydhvs/blob/master/docs/byd-hexstructure.md
- https://github.com/smarthomeNG/plugins/tree/develop/byd_bat