Ritar BAT-5KWH-51.2V LiFePo4 Battery

Share your Projects!
63

:clipboard: Changelog

All notable changes to the Ritar BMS Home Assistant Addon are documented here.

[1.9.8]

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

[1.9.7.8]

Fixed and improved logic of the parser_battery module. Fixed typo in the parser_temperatures module.

[1.9.7.6]

Cleanup and rework repository structure, readme files and docs.

[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]

Introducing new feature - United BMS - this feature gives you the ability to customize Ritar BMS addon or create your own BMS addon for batteries manufactured by other vendors! README. After update do double addon restart, or just reinstall, for properly changing work structure.

[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.

[1.9.5.6]

Structure rework for better source code understanding. Fixed properly forgotten config option zero_pad_cells - now it works as expected and switches cell numeration with cleanup in MQTT entities. Improved graphs spikes filtering in Ritar ESS device for multi-battery setups.

[1.9.5]

Code cleanups, optimizations, structure reworks. Fixed wrong understanding by Home Assistant MQTT, EEPROM parameter x_soc_alarm_threshold, now shown correctly.

[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 misvalues graphs – HOWTO

[1.9.4]

MAJOR UPDATE. Big amount of code optimizations, structure reworks, fixes.
Added new functional for reading BMS EEPROM presets, which shows in addon console log most important BMS parameters.
In setups with more than one battery - checks parameters between batteries, publishes them into MQTT Ritar ESS device for further information.
If parameters differ - draw comparison tables in console and remove EEPROM preset from Ritar ESS.
Note: Home Assistant rounds values by default — change voltage round to 2 digits, e.g. 58.40.

[1.9.2.5] - HOTFIX

Fixed in Ritar ESS – SOC Average and Voltage Average spikes on graphs. Structure improvements.

[1.9.2.4] - HOTFIX

Set back default read_timeout to 15 SECONDS due to lost connection issue with Deye inverter using CAN.
Fixes across multiple code parts.
Added configuration switch to enable non-critical warnings (off by default).

[1.9.2]

Fixes, cleanups, improved addon log output.
Battery readings output to console now toggleable from configuration (default: off).

[1.9.1]

Added protocol selector directly from Home Assistant for “Ritar ESS” logic device.
Supported inverter protocols:

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 BMS 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"

[1.9]

MAJOR UPDATE.
Reworked protocol.py, refined queries, added logic protections from invalid values reaching MQTT.
Reduced default read_timeout to 10s. Can operate in real-time with 1s timeout (more CPU required).
“Ritar ESS” logic prepared for future writable registers.
Battery ID 0 no longer supported, max: 15 batteries.

[1.8.12]

Minor fixes.

[1.8.10]

New MQTT device Ritar ESS with:

  • Summary SOC
  • Average battery voltage
  • Average temperatures (MOS/env)
  • Summary current and power sensors

Also includes general logic and parsing fixes.

[1.8.8]

Refactored modbus_gateway.py for compatibility with United BMS Debugger/CLI

[1.8.7]

Informational. See BMS Settings README

[1.8.6]

Added config option to enable zero-padded cell numbering (cell_01, cell_02, …)

[1.8.4]

Improved temperature filtering before MQTT publish.
Changed default read timeout to 15 seconds.

[1.8.2]

Config hotfix – added uart: true and usb: true.

[1.8.1]

Docker hotfix – included /dev/ttyUSB0 and /dev/ttyUSB1.

[1.8]

MAJOR UPDATE – serial connection support.
Refactoring and performance improvements.

[1.7.3]

Added support for up to 16 batteries (IDs 1–15).
Added CAN-BUS wiring method with Deye inverters

[1.7.2]

Support for up to 14 batteries.
Important Modbus & DIP info

[1.7]

MAJOR UPDATE – Refactor for large setups.
Please reinstall addon with data wipe.

[1.6]

MAJOR UPDATE – moved fully to MQTT.
No more configuration.yaml edits required.
Restart Home Assistant after setup.

[1.5]

Support for up to 4 batteries.
More config options and improved templates.

[1.4]

  • Added WATTmeter (charge/discharge power)
  • RS485 timeout and delay options
  • Improved SOC/Voltage MQTT announcement
  • Updated example templates

[1.3]

  • Added Current sensor (Amps)
  • Updated templates

[1.2]

  • Added MOS & Env temperature sensors
  • Stability fixes, improved config
  • Updated templates

[1.1]

  • Added cell temperature sensors 1–4 for batteries 1–2
  • Updated example templates
64

Future plans :

  • Fixes and patches, if will be founded any issues and bugs.
  • Will try to add bridge for Bluetooth LE IP-gates and local dongles.
  • Merge into project custom batteries presets, if someone will sent me they for other vendors and models.
65

[1.9.8.3]

Still fighting against publishing defective values on charts. Filtering logic has been improved once again. Filtering deltas have been moved to the main_settings module and are now also available for customization.

66

I think many people here can guess how many times I had to correct or delete defective values that appeared on the charts during the development of the framework… I didn’t do it manually, I created a special tool for this, but decided not to formalize it as part of the framework, but to post it in a separate repository.

I think this thing can be useful to many, because as far as I understand, for some reason no one before me has made a sensible editor for the homeassistant recorder database.

Home Assistant Recorder DB Editor (CLI)

:wrench: A command-line tool for direct editing of Home Assistant’s home-assistant_v2.db SQLite database.
Primarily used to clean up unwanted sensor values — including all traces from states, statistics, and statistics_short_term — so they disappear even from mini-graphs.

:warning: WARNING

Before using this tool, make sure you have a backup of your database.
This add-on does NOT provide backup or restore functionality, and is not responsible for any data loss.

:wrench: Installation

  1. Add this repo to Home Assistant Add-on Store
    :round_pushpin: https://github.com/mamontuka/ha-recorder-db-editor
  2. Install the Home Assistant Recorder DB Editor

:white_check_mark: Enable Shell Access

  1. Go to Home Assistant > Settings > Add-ons > Home Assistant Recorder DB Editor.
  2. Open the Configuration tab.
  3. Enable the following option (if disabled):
enable_debug_shell: true
  1. Save and restart the add-on.

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

:rocket: Quick Start

When launched, you’ll see a warning message:

===  IMPORTANT NOTICE ===
BEFORE YOU USE THIS TOOL:
MAKE SURE TO BACKUP YOUR HOME ASSISTANT DATABASE USING STANDARD BACKUP METHODS!
THIS TOOL DOES NOT PROVIDE BACKUP OR RESTORE FUNCTIONALITY AND IS NOT RESPONSIBLE FOR DATA LOSS.

Type 'agree' and press Enter to continue, or 'exit' to quit.

Type agree to proceed to CLI mode.
Enter path to HA database or press ENTER key for confirm default /config/home-assistant_v2.db.

:laptop: Available Commands

Sensor Commands

Command Description
sensor list_all List all sensors and their metadata_id.
sensor find <entity_id> Show metadata_id and recent state records.
sensor values <entity_id> List all unique values stored for the sensor.
sensor raw <entity_id> Show 200 recent raw states records.
sensor delete <entity_id> <value> Completely delete value from states, statistics, and statistics_short_term.

System Commands

Command Description
password Change password for debug user.
clear Clear the screen.
help Show command help.
exit Exit the CLI.

:spouting_whale: Details

  • Written in Python 3.9
  • Uses sqlite3 for direct database access
  • CLI powered by prompt_toolkit with autocompletion and history support
  • Can be extended or embedded in larger add-ons

:open_file_folder: Example Usage

fixer> sensor find sensor.outdoor_temperature
metadata_id for 'sensor.outdoor_temperature' is 42

fixer> sensor values sensor.outdoor_temperature
Found 3 unique values:
  21.2
  21.3
  -72.4

fixer> sensor delete sensor.outdoor_temperature -72.4
Deleted 3 entries from states.
Deleted 1 entry from statistics.
Deleted 2 entries from statistics_short_term.

:brain: Notes

  • If values still show up on mini-graphs after deletion, check statistics_short_term entries — especially min, max, mean.
  • Restart Home Assistant after modifications to ensure the frontend reflects the changes.

:test_tube: Tested On

  • Home Assistant Core 2024.6+
  • SQLite database schema version 43+
  • Container uses python:3.9-slim and Dropbear for optional SSH

Built for Home Assistant power users. Use with care.

67

[1.9.8.4]

Fixed basic parameters for calculating filtering values in the main_settings module. The default configuration parameter next_battery_delay has been increased to 1 second to reduce the chance of incorrect SOC and unit voltage values appearing on the graphs in multi-battery installations (it is recommended to increase it from the previous default of 0.5 seconds to 1 second if you have not made fine-tuning and are using default values).

68

[1.9.8.5]

Fixed incorrect calculation of average values in the ESS device, for multi-battery installations - in the main_settings module, set coarser values for delta filtering by default. We are looking for a balance between garbage on the graphs and adequate readings.

69

[1.9.8.6]

Fix for ESS units total voltage filtering delta. Comments in main_settings and main_arrays modules.

70

[1.9.8.7]

Again patching main_settings and main_arrays modules.

71

[1.9.8.8]

Still catching and fine tuning values in main_settings and main_arrays modules. About spikedowns in multibattery installations.

72

[1.9.8.9]

  • Added spike filtering to suppress sudden jumps in voltage and state of charge (SOC) readings for all batteries.
  • Implemented median-based filtering comparing new values against recent history to improve telemetry stability.
  • Applied configurable maximum allowed deltas (2.0 for voltage, 3.0 for SOC) to detect and reject spikes.
  • Fixed erratic voltage and SOC spikes previously observed, now uniformly handled for all batteries.
73

[1.9.9]

  • Added comments to improve code readability in parser_battery.py.
  • Clarified parameters, return values, and main data structures in battery parsing and handling functions.
  • Explained spike filtering logic and data validation steps, including role of filter_spikes.
  • Enhanced comments on Modbus query handling and exception catching blocks.
  • Refactored helper functions by moving some from parser_battery.py to main_helpers.py for better code organization.
  • Updated usage of constants in main_settings.py related to spike filtering and thresholds.
74

confirmed support for Predator PR48-100-XBH-3U batteries : https://www.reddit.com/r/SolarDIY/comments/1lbz5dk/inside_a_ritar_xplfp48v100ah_predator/

Difference betwen bluetooth app and rs485 data - its ok, because BT works like email listing (send,wait,receive… no autoupdate), and direct rs485 works in realtime, every 15 sec (by addon default value), in addon hardcoded minimal cells count is 8 cells. Its can be checked by original vendor software, what works in realtime too, even with more faster delay in 0.1 sec by default (better turnoff addon when use original software, for prevent missreads and garbage on graps due modbus flood. Protects what i done works even in this case, but no 100% warranty what garbage not became on graphs in HA)

P.S. also difference in values betwen BT app and rs485 - can be from homeassistant rounding values or upsidown - BT app rounding ))

75

[1.9.9.1]

  • Dockerfile: Removed DSS key generation for Dropbear to fix build errors.
  • mqtt_core.py: Adjusted spike filtering logic for cycles and temperatures to improve data accuracy.
76

[1.9.9.2]

  • Battery Session Mode Toggle: Added a new configuration switch in the add-on. By default, now each battery is read in its own separate session. When the switch is disabled, all batteries are read in a single Modbus session as before.
77

[1.9.9.4]

  • Configurable number of battery cells: Users can now set the number of cells per battery (from 8 up to 16) in the Home Assistant addon configuration. Useful for compatible batteries with fewer than 16 cells to ensure correct readings and proper operation.
  • Centralized settings: All important parameters previously hardcoded in battery and temperature parsers are now moved to a main_settings.py.
    This allows easy adjustment for other battery types via the United BMS framework by creating and editing a custom main_settings.py with enhanced capabilities.
  • Temperature spike filtering: MOSFET and environmental temperature filtering remains centralized in parser_temperature.py, ensuring consistent and stable readings.
  • Battery readings results processing, filter values and accumulate sums function moved from main.py to main_helpers.py module, for better modularity.
78

[1.9.9.5]

  • Dummy Modbus Read Fix: Added a short “dummy” Modbus read for all secondary batteries (slaves with ID ≠ 1) immediately after opening their communication session.
    This prevents corrupted or invalid first-read values (voltage, current, power, cycle count) that could occasionally appear on graphs after long uptime.
    Implemented directly in modbus_gateway.py inside the open() method — safe, minimal change, no impact on the rest of communication logic.
    The dummy request reads one register (0x0000) and discards the result, stabilizing the connection before real data collection begins.
79

[1.9.9.6]

  • modbus_gateway.py enhancement: Added short pre- and post-delays around the initial dummy Modbus read executed immediately after opening a connection.
    This prevents corrupted first responses from certain slaves. The dummy read now includes ~100 ms delay before and after execution for improved line stabilization.
    Applied only to non-primary batteries (slave != 1), ensuring full compatibility with both “separate sessions” and “single session” modes.
    Results in a noticeable reduction of random garbage values (cycle_count, current, power) for the second battery without affecting normal Modbus communication or performance.
80

[1.9.9.7]

  • Added Bluetooth development tool for Ritar compatible batteries : README HERE
81

Ritar compatible batteries Bluetooth developer tool

Development board:
ESP32-S3-DEV-KIT-N8R8

Description

Works as a long-range, wide-area repeater between native apps and the real master battery.
It intercepts and logs packets between the battery and the app, outputting detailed logs
to a web interface accessible via the device’s IP address.
Covers a long distance between the phone and the battery.

ESP32 BLE MITM — logs → WebSocket + SPIFFS (no reliance on Serial)

  • Peripheral (ESP emulates battery) ↔ App
  • Central (ESP connects to real battery) ↔ Battery
  • APP → ESP writes are forwarded to battery (immediate if connected, otherwise queued)
  • Battery notifications are forwarded to APP
  • Logs: WebSocket (port 81) + SPIFFS (/ble_proxy_log.txt)
  • ArduinoOTA password: 1234

Configuration

// ---------- CONFIG ----------
const char* WIFI_SSID = "Your_WiFi_SSID"; // Your WiFi AP SSID, for connect this device to your network
const char* WIFI_PASS = "Your_Wifi_Pass"; // Your WiFi AP password, for connect this device
const char* OTA_PASSWORD = "1234";

const char* ADVERT_NAME = "RDAC_PROXY"; // this device name, what you will see in native BT App
const char* TARGET_BATTERY_ADDR = "AC:23:3F:9E:E7:79"; // real battery MAC or "" to scan. Set master battery MAC (DIP swithes modbus ID 1)

static BLEUUID SERVICE_UUID("0000fff0-0000-1000-8000-00805f9b34fb");
static BLEUUID CHAR1_UUID ("0000fff1-0000-1000-8000-00805f9b34fb"); // notify/read
static BLEUUID CHAR2_UUID ("0000fff2-0000-1000-8000-00805f9b34fb"); // write

const char* LOG_FILE_PATH = "/ble_proxy_log.txt";

// Time / NTP
bool g_timeSynced = false;          // becomes true after successful NTP
const char* NTP_POOL1 = "pool.ntp.org";
const char* NTP_POOL2 = "time.google.com";
// POSIX TZ string for Kyiv (handles DST). If issues, you can use simpler "Europe/Kyiv".
const char* TZ_STRING = "EET-2EEST,M3.5.0/3,M10.5.0/4";

Usage

Prepare source variables for your local equipment

Upload source to board via Arduino IDE. OTA updates are available using OTA_PASSWORD (default "1234")

Connect to the RDAC_Proxy battery by native Bluetooth App from store :

Bluetooth Li

Neuton Power

Open the web interface at http://<ESP_IP>/ to monitor logs.

All packets are intercepted and relayed between the app and battery.

Example logs:

screenshot
screenshot

82

[1.9.9.8]