United BMS Framework

Framework focused on creating custom Homeassistant addons, for control and logging different battery management systems (BMS), produced by different manufacturers. Born from: GitHub - mamontuka/ritar-bms-ha: Homeassistant Addon for Ritar BAT-5KWH-51.2V BMS

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
1 Like

If someone will do custom modules for own batteries - let me know, and send me modules templates please. Im will merge they into main code as supported native.

Main discussion and anouncements here : Ritar BAT-5KWH-51.2V LiFePo4 Battery - #54 by mamontuka

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


:door: How to Access the Shell

The United BMS shell runs inside the add-on container and is accessible via SSH.

:white_check_mark: Enable Shell Access

  1. Go to Home Assistant > Settings > Add-ons > Ritar BMS.
  2. Open the Configuration tab.
  3. Enable the following option:
enable_shell: true
  1. Save and restart the add-on.

:closed_lock_with_key: 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

:brain: 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: tcp or serial
  • Enter connection details (e.g., 192.168.0.100:50500 or /dev/ttyUSB0)
  • Specify how many BMS batteries (slaves) are connected

The configuration will be saved and automatically reused next time.


:test_tube: Reading Data from Your BMS

Once configured, you can read data from a connected BMS:

united-bms> read 1 soc 16

Where:

  • 1 is the slave address (battery number)
  • soc is the name of the register (defined in register_map.yaml)
  • 16 is how many registers to read

You can also use raw register numbers:

united-bms> read 1 2 16

:file_folder: 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.yaml file that maps friendly names like soc to 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.


:compass: 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 help or ? 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

:closed_lock_with_key: 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.


:package: 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.


:speech_balloon: Extending Support

To support new BMS protocols or register formats:

  • Place your custom .py or .yaml logic into /config/united_bms/
  • You can define your own register maps, protocol logic, or override behavior
  • The framework will automatically use your customizations

:white_check_mark: 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.