Victron Venus OS: Integrate Lithink Batteries via Bluetooth

1) What Is Venus OS and What Does dbus-serialbattery Do?

Venus OS is the operating system for Victron GX devices such as Cerbo GX, Ekrano GX, or a Raspberry Pi with Venus OS installed. It collects measurement and status data from the entire energy system, including battery, inverter, chargers, and PV controllers, and displays them centrally in the Remote Console and VRM portal.

dbus-serialbattery is an additional battery driver that enables BMS data from third-party batteries to be integrated into Venus OS. This includes battery voltage, charge and discharge current, state of charge (SoC), and — depending on the specific BMS — cell voltages and temperature values.

For Bluetooth-enabled batteries, this integration is wireless via BLE. This makes the solution especially suitable for retrofits in RVs, boats, and off-grid systems where no direct serial connection is available.

2) Requirements

1. Victron GX device: Cerbo GX, Ekrano GX, or a Raspberry Pi with Venus OS installed.
2. Network connection: GX device and computer are on the same local network, either LAN or Wi-Fi.
3. SSH / root access: Root Access must be enabled according to Victron documentation.
4. Bluetooth support: The GX device has integrated or compatible Bluetooth.
5. Prepared battery: The battery is switched on, Bluetooth is active, and the battery is within range of the GX device.

3) Step 1: Enable SSH and Find the IP Address

1. Enable SSH: Open the Remote Console of the GX device and enable SSH access. Depending on the version, you can find this option under Settings → Services → SSH on LAN.
2. Find the IP address: Under Settings → Ethernet / Wi-Fi, the current IP address is displayed, for example 192.168.1.55.
3. Check root access: Make sure Root Access is configured according to the Victron instructions.

4) Step 2: Connect to the GX Device via SSH

Windows

1. Tool: Install PuTTY or use Windows Terminal.
2. Connection: Enter the IP address of the GX device as the host name, port 22, protocol SSH.
3. Login: Log in with the root user credentials.

macOS / Linux

1. Open Terminal.
2. Run the SSH command:

ssh root@192.168.1.55

Replace the IP address with the one for your GX device.

5) Step 3: Install dbus-serialbattery

1. Download the installation script:

wget -O /tmp/install.sh https://raw.githubusercontent.com/mr-manuel/venus-os_dbus-serialbattery/master/dbus-serialbattery/install.sh

2. Run the installation script:

bash /tmp/install.sh

3. Select version: In most cases, Latest release is the recommended option.
4. Restart the GX device:

reboot

6) Step 4: Read the Bluetooth MAC Address of the Battery

The MAC address of the battery is required for Bluetooth integration. It will be entered into the configuration file in the next step.

1. Start the Bluetooth tool:

bluetoothctl

2. Enable scanning:

scan on

3. Display detected devices:

devices

Example output:

Device AA:BB:CC:11:22:33 Battery-BLE

4. Note the MAC address: for example AA:BB:CC:11:22:33.
5. Stop scanning:

scan off
quit

7) Step 5: Create config.ini and Configure Bluetooth

The driver uses the config.ini file. The first line must be exactly [DEFAULT]; otherwise, the configuration will not be loaded correctly.

7.1 Open config.ini

nano /data/apps/dbus-serialbattery/config.ini

7.2 Minimal Bluetooth Configuration

[DEFAULT]
BLUETOOTH_BMS = <DriverName> AA:BB:CC:11:22:33

The correct driver name can be found in the following file:

/data/apps/dbus-serialbattery/config.default.ini

7.3 Save and Close

1. Save: Ctrl + O, then Enter.
2. Exit: Ctrl + X.

8) Step 6: Enable Services and Restart the Driver

1. Run the enable script:

bash /data/apps/dbus-serialbattery/enable.sh

2. Restart the driver:

bash /data/apps/dbus-serialbattery/restart.sh

3. Optional: When changing BLUETOOTH_BMS, a restart is recommended:

reboot

9) Step 7: Display the Battery in Venus OS

1. Open Remote Console.
2. Under Settings → System setup, select the Battery Monitor.
3. After successful setup, an entry from dbus-serialbattery appears with the current battery values.

10) Troubleshooting

Problem A: Battery Is Not Displayed

1. Check the MAC address.
2. Compare the driver name with config.default.ini.
3. Reduce the distance between the battery and the GX device.
4. Run enable.sh, restart.sh, and reboot again.

Problem B: Bluetooth Scan Finds No Devices

1. Is the battery switched on and Bluetooth active?
2. Disconnect smartphone Bluetooth.
3. Start the scan again.

Problem C: Values Drop Out Sporadically

1. Check the Bluetooth environment.
2. Avoid parallel connections.
3. Restart the GX device or driver.

11) Notes for Lithink Bluetooth Batteries

In practice, stable integration depends not only on the software but also on the BMS design of the battery.

Lithink Bluetooth LiFePO₄ batteries are designed to work with clear data structures and stable factory settings. In Victron Venus OS, they can usually be integrated without extensive adjustments.

• Factory-configured BMS parameters for RV and off-grid applications
• Bluetooth data structure compatible with dbus-serialbattery
• No repeated manual BMS adjustments required
• Stable data updates with a single connection

For initial setup, it is recommended to connect only the GX device to the battery and use smartphone apps only after successful integration.

Acknowledgement