UPDATE 1.9.2 - fixes, cleanups, improving addon log output, battery readings output to console now turnable from configuration and by default turned off.
UPDATE 1.9.2.4 - HOTFIX SETTED BACK DEFAULT read_timeout to 15 SECONDS, because testing on my setup - 2x5.1 Rittar batteries (SMA protocol) what connected over CAN bus to Deye 6K-SG03LP1-EU (LiBMS protocol 00), show what with less than 15 sec read_timeout - CAUSE LOST CONNECTION WITH INVERTER, change this option by your opinion, but be awared about possible issues ! Different fixes in almost all code parts. Added switch into configuration, for turn on not critical warnings in console output (turned off by default).
UPDATE 1.9.2.5 - HOTFIX Fixed in Ritar ESS - SOC Average and Voltage Average spikes on graphs. Structure improvements.
UPDATE 1.9.4 - MAJOR UPDATE. Big amount code optimizations, structure reworks, fixes. Added new functional for read BMS EEPROM presets, what show in addon console log most important BMS parameters, in setups with more than one battery - check parameters betwen batteries, publish they into mqtt Ritar ESS device, for more information. In case if parameters different betwen batteries - draw tables for analyse to addon console log, remove EEPROM preset from Ritar ESS. Keep in mind, what Homeassistant round values by default. Change Voltages round to 2 symbols, eg. 58.40, etc
Known issue - x_pack_full_charge_voltage - displayed to mqtt as mV (5840), but must be showed in V like 58.40. Will be fixed in close 1-2 days.
UPDATE 1.9.4.1 - HOTFIX Fixed wrong measurement unit for x_pack_full_charge_voltage. Please delete mqtt logic device “Ritar ESS”, and restart addon. It will repair wrong graphs. AND/OR delete entity missvalues graphs - HOWTO
UPDATE 1.9.5 - Code cleanups, optimizations, structure reworks. Fixed wrong understanding by Homeassistant mqtt, EEPROM parameter x_soc_alarm_threshold, now showed right.
UPDATE 1.9.5.6 - Structure rework for better source code understanding. Fixed properly forgoten config option “zero_pad_cells” - now it works how was expected and switch cell numeration with cleanup in mqtt entities. Improved graphs spikes filtering in Ritar ESS device for multibattery setups.
UPDATE 1.9.6 - Structure rework, code cleanups. Preparing for changing version numeration from “current” to “stable”. At this moment, during tests, not found any issues, if you know what works not properly or not how expected - let me know, please.
Later, i will find time, for clean here not needed current updates and patches notifications. For better topic readability.
UPDATE 1.9.7 - Introducing new feature - United BMS - this feature give you ability customize Ritar BMS addon. Or create by self, BMS addon for batteries manufactured by other vendors ! README . After update do double addon restart, or just reistall, for properly changing work structure.
United BMS Feature for Ritar BMS Addon
This feature allows you to extend and customize your Ritar BMS Home Assistant addon by loading override Python modules from a fixed folder in your Home Assistant config directory.
What is United BMS Feature?
The United BMS feature provides a custom modules directory (/config/united_bms) where you can place your own versions of key Python modules that the addon loads dynamically at runtime.
This lets you create by self, BMS addon for batteries manufactured by other vendors ! and:
Customize battery parsing logic
Override Modbus register definitions
Adjust temperature parsing or any other core logic without rebuilding the addon
Test new features or bug fixes easily by editing Python files directly in your Home Assistant config
How it Works
At startup, the addon tries to load modules in this order:
From the fixed override path /config/united_bms (e.g. /config/united_bms/modbus_registers.py)
If not found, fallback to the internal default module bundled in the addon
This means if you provide a custom modbus_registers.py in /config/united_bms/, your version will be used instead of the built-in one.
Getting Started
Prerequisites
You already have the Ritar BMS addon installed in Home Assistant
You have access to your Home Assistant configuration directory (usually /config)
Step 1: Create the override directory
Using your favorite file editor or Samba share, create the directory:
/config/united_bms
Step 2: Place your custom Python files
Copy or create any of the following files you want to override inside /config/united_bms:
modbus_registers.py
parser_battery.py
parser_temperature.py
main_settings.py
modbus_inverter.py
modbus_eeprom.py
You do not need to override all files — only the ones you want to customize.
Step 3: Restart the addon
After placing your override files, restart the Ritar BMS addon. You should see logs indicating that your override modules were loaded from /config/united_bms.
Step 4: Verify
Check the addon logs for messages like:
[INFO] Loaded override modbus_registers.py from /config/united_bms/modbus_registers.py
If you do, your overrides are active.
Notes
The directory /config/united_bms is fixed in the addon and cannot be changed via configuration options.
The addon falls back to internal modules if no override file is found.
Changes to override files require an addon restart to take effect.
Make sure your custom Python files are syntactically correct to avoid import errors.
Troubleshooting
If overrides are not loaded, verify your files are correctly placed in /config/united_bms inside the Home Assistant container.
Use docker exec or the Home Assistant terminal addon to inspect files inside the container.
Check file permissions to ensure the addon can read the override files.
Example Docker Volume Mapping
If you are running the addon via Docker Compose manually, mount your override directory like this:
volumes:
- ./config.yaml:/workdir/config.yaml
- ./united_bms:/config/united_bms
- /dev:/dev
known issue in 1.9.7 - homeassistant hang, if you put into united_bms zero sized empty custom files… i dont think what someone will guess to do this, but im will fix it in future update.
UPDATE 1.9.7.5 - Improvements and fixes for introduced United BMS framework. Updated logic, fallbacks, now modbus_battery.py module also available for custom modification. Feature marked stable, if you use properly structured modules templates. Also added protection from zero size modules.
[1.9.7.8]
Fixed and improved logic of the parser_battery module. Fixed typo in the parser_temperatures module.
[1.9.8]
Container Update & New Debugger Feature
-
Switched the base image from Alpine to Debian for better compatibility and extensibility.
-
Refactored container structure for improved maintainability and easier customization.
-
Introduced a built-in interactive debugger for the United BMS framework, accessible via SSH inside the container - READ MORE
This update lays the foundation for more powerful diagnostics and development tools in future releases.
Finally I can mark project as successfull stable. Bellow - current readme files about project parts and current changelist
Ritar BMS for Home Assistant
A Home Assistant Addon for Ritar BAT-5KWH-51.2V BMS and compatible batteries
Current version: [1.9.8] 
See Update Details for full version history.
Supported Devices
Ritar Power 5KWH / 10KWH / 15KWH models- Partial support: YHI Energy, Hollandia Power
- Others via United BMS
Visual & Documentation
RITAR POWER Site- Official Documentation
Official Ritar BMS Software
Official Android Bluetooth App
Battery Review Pictures
RS485 Adapters and Ethernet Gates Software and Documentation- Wiring to RS485 Basics, example equipment - Deye 6K-SG03LP1-EU + VKmodule ENET-485 gate
- Wiring with Deye Inverters Over CAN Bus
Home Assistant Screenshots Installation
- Add this repo to Home Assistant Add-on Store
https://github.com/mamontuka/ritar-bms-ha - Install the Ritar BMS Addon
- Open Addon settings:
- Set your RS485 Ethernet Gateway IP/Port
- Define how many batteries (1–15)
- Set your MQTT broker info
- Restart addon
- Enjoy automatically discovered sensors in Home Assistant!
United BMS Framework
Create your own BMS addon for other manufacturers
Read More about United BMS
Embedded United BMS Debugger/CLI
Features
RS485 & Serial Communication
Up to 15 battery unit support
MOS/Environment/Cell temperatures- SOC, Block Voltage, Current, Power
Graph filtering, spike protection
EEPROM preset analysis & alerts
Unified Modbus debugger CLI
MQTT Discovery + HA Integration
United BMS Framework for custom BMS logic
Compatible Inverter Protocols
This addon supports setting inverter protocols via Home Assistant UI:
| Code | Protocol |
|---|---|
| 0 | RITAR_RS485 (RITARV1_8) |
| 1 | DEYE_RS485 (Deye BMS Protocol 12), PLY(DEYE,SMK,FIRMAN,Hollandia) |
| 2 | GROWATT_RS485 |
| 3 | VOLTRONIC_RS485, LIB05(VOLTRONIC,XUNZEL,TESLA,GSB SOLAR,PCE) |
| 4 | UPOWER_RS485 |
| 5 | VERTIV_RS485 |
| 6 | ELTEK_RS485 |
| 7 | RITAR_MODBUSV1_9_RS485 |
| 8 | VICTRON_CAN |
| 9 | RITAR_CAN |
| 10 | SMA_CAN (Deye Protocol 00) |
| 11 | MEGAREVO_CAN |
| 12 | TBB_CAN |
| 13 | SOLIS_CAN |
| 14 | INHENERGY_RS485 |
| 15 | MUST_CAN |
| 16 | PYON_CAN |
| 17 | LUXPOWERTEK_RS485 |
| 18 | PHOCOS_RS485 |
United BMS Feature for Ritar BMS Addon
This feature allows you to extend and customize your Ritar BMS Home Assistant addon by loading override Python modules from a fixed folder in your Home Assistant config directory.
What is United BMS Feature?
The United BMS feature provides a custom modules directory (/config/united_bms) where you can place your own versions of key Python modules that the addon loads dynamically at runtime.
This lets you create by self, BMS addon for batteries manufactured by other vendors ! and:
Customize battery parsing logic
Override Modbus register definitions
Adjust temperature parsing or any other core logic without rebuilding the addon
Test new features or bug fixes easily by editing Python files directly in your Home Assistant config
How it Works
At startup, the addon tries to load modules in this order:
From the fixed override path /config/united_bms (e.g. /config/united_bms/modbus_registers.py)
If not found, fallback to the internal default module bundled in the addon
This means if you provide a custom modbus_registers.py in /config/united_bms/, your version will be used instead of the built-in one.
Getting Started
Prerequisites
You already have the Ritar BMS addon installed in Home Assistant
You have access to your Home Assistant configuration directory (usually /config)
Step 1: Create the override directory
Using your favorite file editor or Samba share, create the directory:
/config/united_bms
Step 2: Place your custom Python files
Copy or create any of the following files you want to override inside /config/united_bms:
modbus_registers.py
parser_battery.py
parser_temperature.py
main_settings.py
modbus_inverter.py
modbus_eeprom.py
modbus_battery.py
You do not need to override all files — only the ones you want to customize.
Step 3: Restart the addon
After placing your override files, restart the Ritar BMS addon. You should see logs indicating that your override modules were loaded from /config/united_bms.
Step 4: Verify
Check the addon logs for messages like:
[INFO] Loaded override modbus_registers.py from /config/united_bms/modbus_registers.py
If you do, your overrides are active.
Notes
The directory /config/united_bms is fixed in the addon and cannot be changed via configuration options.
The addon falls back to internal modules if no override file is found.
Changes to override files require an addon restart to take effect.
Make sure your custom Python files are syntactically correct to avoid import errors.
Troubleshooting
If overrides are not loaded, verify your files are correctly placed in /config/united_bms inside the Home Assistant container.
Use docker exec or the Home Assistant terminal addon to inspect files inside the container.
Check file permissions to ensure the addon can read the override files.
Example Docker Volume Mapping
If you are running the addon via Docker Compose manually, mount your override directory like this:
volumes:
- ./config.yaml:/workdir/config.yaml
- ./united_bms:/config/united_bms
- /dev:/dev
Embedded United BMS Shell Interface
This shell utility is part of the United BMS Framework, providing a convenient and interactive CLI tool for configuring and reading data from RS485-connected BMS devices directly within a Home Assistant add-on environment.
Usage Screenshots: HERE
How to Access the Shell
The United BMS shell runs inside the add-on container and is accessible via SSH.
Enable Shell Access
- Go to Home Assistant > Settings > Add-ons > Ritar BMS.
- Open the Configuration tab.
- Enable the following option:
enable_shell: true
- Save and restart the add-on.
Connect via SSH Client
Use any SSH client (e.g. ssh, PuTTY, MobaXterm) and connect to your Home Assistant host:
ssh debug@<HOME_ASSISTANT_IP> -p <EXPOSED_PORT>
- Username:
debug - Password:
debug(can be changed in the shell) - Port: must be mapped in your add-on or container settings
First-Time Configuration
After connecting via SSH, you’ll enter the interactive United BMS shell.
1. Configure your BMS connection:
united-bms> config debug
You will be prompted to:
- Select connection type:
tcporserial - Enter connection details (e.g.,
192.168.0.100:50500or/dev/ttyUSB0) - Specify how many BMS batteries (slaves) are connected
The configuration will be saved and automatically reused next time.
Reading Data from Your BMS
Once configured, you can read data from a connected BMS:
united-bms> read 1 soc 16
Where:
1is the slave address (battery number)socis the name of the register (defined inregister_map.yaml)16is how many registers to read
You can also use raw register numbers:
united-bms> read 1 2 16
Customization and Overrides
The shell interacts with a folder on your Home Assistant host:
/config/united_bms/
This directory is used to store:
- Your custom override files (
.yaml,.py) - A
register_map.yamlfile that maps friendly names likesocto raw register numbers
If no register_map.yaml exists, a default one will be created on first launch.
You can safely place your custom logic here to extend or override default behavior.
Shell Usage Tips
The shell is user-friendly and supports:
- Tab completion for commands and filenames
- Arrow keys (↑ and ↓) to navigate through previous commands
- Inline help using the
helpor?command
Available Commands:
united-bms> help
| Command | Description |
|---|---|
password |
Change debug user password |
config debug |
Start connection setup wizard |
config print |
List available custom override files |
config edit <filename> |
Edit an override file directly in the shell |
read <slave> <block> <count> |
Read registers from a BMS slave |
help or ? |
Show command help |
exit |
Exit the shell |
Change Debug User Password
To change the SSH password:
united-bms> password
You will be asked to enter and confirm the new password.
Internally it uses standard Linux password utilities inside the container.
Home Assistant Add-on Integration
If you’re running outside the Supervisor (e.g., in Docker manually), make sure your container has access to:
volumes:
- /PATH/TO/ha/config:/config
- /dev:/dev
Replace /PATH/TO/ha/config with the actual Home Assistant config path.
Extending Support
To support new BMS protocols or register formats:
- Place your custom
.pyor.yamllogic into/config/united_bms/ - You can define your own register maps, protocol logic, or override behavior
- The framework will automatically use your customizations
Summary
The United BMS Shell is a powerful and flexible interface for working directly with RS485-connected batteries in a Home Assistant environment. Whether you’re debugging, testing, or building custom support — the CLI makes it fast and safe.
If you REALY KNOW what you do, in standalone version you have --write option.
Standalone United BMS debugger/commandline tool
“–write” option USE AT OWN RISK ! THAT OPTION CAN DAMAGE YOUR EQUIPMENT !
Require python modules - pyyaml, pyserial
Modbus registers map in register_map.yaml can be ajusted for any BMS what works over modbus, or setted another one by option:
--map file_name.yaml
First use :
Be sure what .py file have execute rights for your user/group, if not - chmod 777 ./cli.py
python3 cli.py -h
options:
-h, --help show this help message and exit
--tcp TCP TCP address like 192.168.0.100:50500
--serial SERIAL Serial port like /dev/ttyUSB0
--slave SLAVE Modbus slave ID (default: 1)
--read READ Register name or address to read
--count COUNT Number of registers to read (default: 1)
--write WRITE Write format: <register=value>
--map MAP YAML file with register name -> address map
--mode {rtu_tcp,rtu_serial}
Modbus connection mode: rtu_tcp (default), or rtu_serial
--timeout TIMEOUT Connection timeout in seconds (default: 3)
How to Use
Read registers over RTU TCP (raw RTU frame over TCP):
./cli.py --tcp 192.168.0.100:50500 --slave 1 --read SOC --mode rtu_tcp
Read registers over Serial RTU:
./cli.py --serial /dev/ttyUSB0 --slave 1 --read SOC --mode rtu_serial
Write a value:
./cli.py --tcp 192.168.0.100:50500 --slave 1 --write SOC=85.0 --mode rtu_tcp
Example usage for get cells voltages :
./cli.py --tcp 192.168.0.100:50500 --slave 1 --read 40 --count 16 --mode rtu_tcp
Result output
[READ] Register 40 values: [3370, 3410, 3396, 3410, 3418, 3393, 3428, 3403, 3408, 3373, 3417, 3398, 3414, 3380, 3420, 3420]
Example usage for get SOC, SOH, remain capacity, full capacity values :
./cli.py --tcp 192.168.0.100:50500 --slave 1 --read SOC --count 6 --mode rtu_tcp
[READ] Register 2 values: [1000, 1000, 10000, 10000, 10000, 16]
“–count 6” option mean what we read 6 registers, with start from “SOC” (register 2) and end on “Battery_cycle_count” (register 7) (watch in register_map.yaml)
and for example :
./cli.py --tcp 192.168.0.100:50500 --slave 1 --read 1 --count 7 --mode rtu_tcp
[READ] Register 1 values: [5448, 1000, 1000, 10000, 10000, 10000, 16]
mean what we read from 1st register (block voltage) to 7 (cycles) on “–slave 1” (battery number 1 by DIP switches)