dbus-serialbattery: teaching Venus OS to read a third-party BMS

The archive notice is the first thing you should read

The repository opens with a banner saying it was archived, and the reason given is that after many months of inactivity the repository has been archived for research purposes.

The next line is the one that matters operationally. Development of this driver continues in mr-manuel's repository, at github.com/mr-manuel/venus-os_dbus-serialbattery, and the README closes with thanks to all the users who have used this driver.

That split explains something about the documentation, because all of the documentation links in this README point at the mr-manuel documentation site rather than a local docs directory. The introduction, features, supported BMS, installation, troubleshooting and FAQ pages are all hosted under mr-manuel.github.io/venus-os_dbus-serialbattery_docs. The docs/ directory does exist in this repository, but the live documentation belongs to the fork.

The last push to this repository was on 2026-09-11, and the listed releases are v1.2.20240408 from 2024-04-08, a v1.2.20240227beta from 2024-02-28 and a v1.0.20240102beta from 2024-01-02. The version scheme embeds the date, which is a common pattern for a driver that ships as a package to be installed on a device rather than consumed as a library.

So the practical reading is that this repository is a historical snapshot. It is useful for understanding the design, for reading the developer remarks, and for anyone who pinned to a version from this line. It is not where you should file an issue or expect a fix.

What the driver does: a battery that the Victron stack did not know about

The driver is for Venus OS devices, meaning any GX device sold by Victron or a Raspberry Pi running the Venus OS image.

The mechanism is a three-step translation. The driver communicates with a Battery Management System that supports serial, RS232, RS485 or TTL UART, and Bluetooth communication. The data is then published to the Venus OS system over dbus. And the stated main purpose is to act as a Battery Monitor in your GX and supply State of Charge and other values to the inverter and charger.

That third point is the reason the project exists at all. A Victron GX device is the brain of an off-grid or marine power system, and it wants to know the state of charge, the current limits and the voltage setpoints of the battery attached to it. If you buy a third-party lithium battery with a good BMS but no Victron comms, the GX does not see it as a battery at all. This driver makes it visible.

The dependencies in requirements.txt show what that takes on the wire and the bus. There is pyserial for the serial transports, minimalmodbus for the Modbus protocol used by many BMSes, bleak for Bluetooth, and dbus-fast for the dbus side:

pyserial==3.5
minimalmodbus==2.0.1
bleak==0.21.0
dbus-fast==1.94.1

bleak is the interesting one, because it is what makes the Bluetooth variant possible at all, and Bluetooth is a transport you see on battery packs intended for mobile or marine installation where a serial cable is impractical.

The project is MIT licensed, and the primary language is Python, which is consistent with a driver that runs on the device alongside the rest of the Venus OS Python tooling.

How the driver finds and reads the battery, step by step

The developer remarks section describes the internals in enough detail to be useful, and the design is a straightforward plugin pattern.

Each supported BMS needs to implement the abstract base class Battery from battery.py. That is the extension point, and adding a new BMS means adding an implementation of that class.

The driver then works out which battery is connected by looping through all known implementations of Battery and executing their test_connection() method. If that returns true, dbus-serialbattery.py sticks with this battery.

From there the polling loop is periodic. It executes dbushelpert.publish_battery(), which calls Battery.refresh_data() to update the fields of the Battery object, and then publishes those fields to dbus using dbushelper.publish_dbus().

So the cycle is test once, then refresh and publish on a timer. There is no hot-swap detection, no rediscovery if a battery is unplugged, and no dynamic loading of implementations from a plugin directory. The set of BMSes is compiled into the driver, which is a reasonable trade for a device with a fixed installation, and a limitation worth knowing if you expect to swap batteries at runtime.

The Victron device is then controlled by the values published on the /Info/ paths, and the README lists them:

  * `/Info/MaxChargeCurrent `
  * `/Info/MaxDischargeCurrent`
  * `/Info/MaxChargeVoltage`
  * `/Info/BatteryLowVoltage`
  * `/Info/ChargeRequest` (not implemented in dbus-serialbattery)

The last one is marked as not implemented, which is a useful detail: the driver reads and reports charge limits and voltage setpoints, but it does not accept a charge request from the Victron side. The README points at the official Victron dbus documentation for the wider interface.

The two people behind it, and what each contributed

The README credits two contributors with distinct roles, and the split is informative about how the project evolved.

Louisvdw is listed as main developer, with the note that he added most of the BMS drivers. mr-manuel is credited with having added a lot of features, optimizations and improvements with v1.0.x, assistance with the issues and discussions of the forum, a lot of documentation to the config file and notes that are displayed after installation for better understanding, and introducing the new documentation page of the driver and reworking a great part of it for easier understanding.

The two release lines in the version list make the same point. The v1.0.x betas from January and February 2024 are mr-manuel's rewrite period, and the v1.2 release from April 2024 comes after that.

The documentation point deserves a second look, because it is a pattern worth copying. Writing notes that are displayed after installation means the user learns what the configuration options do at the moment they are most likely to need that, rather than in a wiki page they will not read. Combined with the config file documentation, that is a lot of effort spent on the part of a driver that users complain about when it goes wrong.

The support section is also unusually specific for a project of this size. It asks for a Ko-Fi donation, offers a PayPal link, and mentions donating hardware for development, which is the actual bottleneck when you are adding support for BMS protocols that are not publicly documented. The supported BMS list and the feature comparison are the two documentation pages to check first if you are considering a specific battery.

Setting up a development environment on the Velib side

The developer remarks cover the local setup, and the key dependency is one you get for free on the device.

The project makes use of velib_python, which is pre-installed on Venus OS devices under /opt/victronenergy/dbus-systemcalc-py/ext/velib_python. To use the python files locally, you clone the velib_python project into a velib_python directory and add velib_python to the PYTHONPATH environment variable.

That is a slightly awkward arrangement by modern standards, since it means the library is expected to sit beside your code rather than in site-packages, and it means a local checkout has to be pointed at by hand. But it is a consequence of the Velib library living inside the dbus-systemcalc-py package on the device, and the driver inherits that layout.

The rest of the setup is about CI rather than code. The README asks you to make sure the GitHub Actions run fine, and gives the two repository settings that are required: under Actions, then General, then Actions permissions, select Allow all actions and reusable workflows, and under Actions, then General, then Workflow permissions, check that Read and write permissions are selected. That second setting is needed because the workflow writes to the repository, for example to post lint results.

The purpose of that CI is stated: it checks your code for Flake8 and Black Lint errors, and the README links a short instruction on setting up Flake8 and Black checks in VS Code, with the comment that this will save you a lot of time. The Black configuration in pyproject.toml sets a line-length of 88, and there is a .flake8 file at the repository root.

For anyone adding a BMS, the README points at a checklist for exactly that, on the supported BMS documentation page, under the heading about adding by opening a pull request. The repository root also carries a CHANGELOG.md, an etc/ directory and a gui-v2 directory, which is where the device-side configuration and the interface work live.

Editorial conclusion

Adopt dbus-serialbattery only if you are running Venus OS on a Victron GX device or a Raspberry Pi with the Venus OS image and your battery speaks one of the supported BMS protocols, since it exists to feed a Victron inverter or charger. Do not start from this repository, because the README states it was archived after many months of inactivity and that development continues in the mr-manuel fork, which also carries the current documentation. Before you install anything, check the supported BMS list and the feature comparison in that documentation, and confirm your BMS supports the serial RS232, RS485 or TTL UART, or Bluetooth, transport the driver expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Louisvdw/dbus-serialbattery on GitHub
4. README
5. Releases