Skip to main content

FAQ (Frequently Asked Questions)

How to change the default limits​

See this page.

What is the config.ini and config.default.ini?​

The config.ini is a file where you can specify your own configuration changes. Like when you want to change default values, e.g. increase the charge and discharge limits. This file is preserved after a version update. Lookup the config.default.ini to see which settings are available.

The config.default.ini is a file where all possible configuration settings are stored with their default values. Every setting is also well documented in order to understand what the setting does. This file is overwritten every time you update the driver.

Click here to see the config.default.ini.

How to edit utils.py or config.ini​

See this page.

How to enable a disabled BMS​

See this page.

What is the username and password of the SSH connection?​

See the Victron Energy documentation how to get root access.

Which version do I have installed?​

You check the installed version in the driver log files or in the remote console/GUI under SerialBattery -> Device -> Firmware version

How to aggregate multiple batteries?​

You need an additional driver for that. Here are a few listed:

Automatically merges connected batteries. Takes consideration of SmartShunt, Multies, Quattros, SmartSolars, BlueSolars and MPPT for current calculation. Additional configuration possible.

💡 Currently the only driver, which switches to float AFTER all batteries are fully charged. See KEEP_MAX_CVL, default is False.

BatteryAggregator by pulquero​

Automatically merges connected batteries. Additional configuration for excluded batteries, total capacity and custom merging possible.

Can be installed through the SetupHelper of kwindrem.

venus-os_dbus-mqtt-battery by mr-manuel​

Virtual battery that has to be fed over MQTT in case you want to merge your data how you'd like. Venus OS Large with Node-RED recommended.

Why do I need a BMS for lithium batteries?​

Lithuim cells are great at storing energy, but they can be dangerous. An overcharged cell can cause a fire. A Battery Management System (BMS) first priority is to protect the cells in your battery from any potential hazards.

The BMS will prevent your battery reaching an unsafe situation (it will disconnect the charge or discharge) and help with the state of each cell inside the battery so that your battery will last longer.

Which BMS should I buy?​

Most of the BMS that the driver support will work fine and the driver does support most features for all the BMS brands. See the comparison table for any small differenaces.

Find the BMS that fits your budget with the features that you need.

The balancers on Smart Daly BMS don't seem to work that well so many users have opted to add an external balancer to help with that.

Also the way that Daly implemented their communication protocol gives for a much slower data retrial which means slower response to events by the driver.

If you own a Daly, then it will work just fine, but if you still need to buy your BMS then one of the other supported BMS would be a better choice.

Which serial adapter/cable should I use?​

Most USB serial adapters and cables should work fine. You need to use the adapter for the UART type that your BMS use, which is normally TTL, RS232, RS485 or even SPI.

Those adapters based on the FDTI or CH340 chips are the easiest to use because the GX opperating system already include drivers for them.

Cable preferences:

  1. Best option is the UART cable/box for your BMS. These use connectors matching your BMS and minimise potential problems with errors from loose connections.
  2. Isolated (galvanic isolation) cables. These are more expensive, but have electrical protection built in making them safer.
  3. Any adapter that work with your BMS UART.

🚨 NB! Only connect Rx & Tx or A & B to the BMS, if you are NOT using an isolated (galvanic isolation) cable or adapter. This prevents the current to flow through the adapter, if the BMS cuts the ground. Else it will destroy your BMS, GX device or Raspberry Pi.

Which UART connection is the best to use (TTL/RS232/RS485)?​

The driver works the same with all the supported UART types. Most BMS will use the 3.3V TTL (which some would lable as UART) and/or RS485 (5V). Victron's VE.Direct is RS232 (12V), but not many BMS use that.

You need to match the UART type with what your BMS support.

If the Bluetooth module for your BMS use the UART, then you will need to remove that to plug in your USB adapter, if you do not have another UART available. After your initial setup you do not need the Bluetooth, but you will not be able to connect to it with the phone app.

Do I need a SmartShunt as well?​

No you don't. All BMS do measure the total battery voltage and most do use a shunt to do that already.

The Smartshunt is very well build and most likely better calibrated, but it can only measure the total battery voltage and the current input/output. There are no sensors for the cells inside the battery so the Smartshunt have much less information to work with.

It is best to let the BMS be the Battery Monitor.

You can add both to your system and in the newer Venus OS firmwares you can select to upload both values to the VRM cloud.

Can the driver be used as monitor only?​

Please also read Should I set the Smartshunt or the BMS as the Battery Monitor?

Yes it can, but there are certain limitations.

Venus OS < v3.00​

Select another or No battery monitor in the remote console under Settings -> System setup -> Battery monitor and disable DVCC in the remote console under Settings -> DVCC.

The DVCC has to be disabled since Venus OS selects the first BMS available in Venus OS < v3.00. Pay attention, that in this case also other BMS cannot control the charger (CVL, CCL, DCL). Please consider to upgrade to the latest Venus OS version in this case.

Venus OS >= v3.00​

Select another or No battery monitor in the remote console under Settings -> System setup -> Battery monitor and another or No BMS control in the remote console under Settings -> DVCC -> Controlling BMS.

Why no SoC is displayed in the overview page?​

Navigate to Settings -> System Setup and check that under Battery monitor your BMS or battery aggregator is selected.

Should I set the Smartshunt or the BMS as the Battery Monitor?​

Set the BMS as the Battery Monitor of your system so that it can read the alarm and cell data to manage your GX system. If you don't, then these alarms will be ignored and the system will keep on (dis)charging the battery even if a problem alarm is raised. The BMS will react by disconnecting the battery for protection and your inverter will go offline.

Why is the max cell voltage set to 3.45V?​

Most home power systems use LiFePo4 cells that are 3.2V. This explanation is the same but with different voltages for a 3.7V cell system.

The default MAX_CELL_VOLTAGE and MIN_CELL_VOLTAGE that is set in the driver is to get your battery to full charge without any cell going into protection. This is used to calculate the max voltage for the battery that we ask the chargers to charge the battery too.

3.65V will be the protection voltage of a cell for most BMS while 3.45V is considered full charge.

If you set your charger to aim for 3.65V it means you are aiming to reach the protection voltage (which it will, and raise an alert). Even 3.64V is too close.

If you look at your cells you will see that it takes hours of charging to go from 3.2V to 3.4V, but from 3.45V to 3.6+V can be in just a second. This give no time for balancing to kick in, thus one cell will reach 3.65V while most of the rest will still be around 3.45V (assuming all your cells are closely balanced. This is much worse if they are not). This all gets multiplied by the cell count that you have.

An example might help (using a 8 cell battery):

  • If we aim for 3.45V per cell that will tell the charger to charge to 27.60V (3.45V x 8)
  • If we aim for 3.64V per cell that will tell the charger to charge to 29.12V (3.64V x 8)

Now say all our cells are almost full. That would mean they are close to 3.45V or 27.6V while we are requesting the battery to go up to 29.12V or another 1.52V.

The first cell that is a bit more full than the rest will jump from 3.45V to 3.65V and raise an alarm, but it is only an increase of 0.2V which mean while one cell should be protected we are asking the charger to increase the voltage another 1.32V cause it thinks we are not full yet.

If this continues the BMS will disconnect and your power will trip.

Now, if you still do want to aim for 3.65V per cell you will have to change the setting on your BMS so that the BMS protection only kick in at a higher voltage (e.g. 3.85V), but I WOULD NOT RECOMMEND THIS, if you want your battery to last a long time.

You get most of the power from the cells between 3.1V - 3.45V and you will have less issues.

lfp-charge-discharge-curves

Why is the charging/discharging current limit (CCL/DCL) smaller than the set one?​

Driver version <= v0.14.3​

Check in the utils.py, if you have set one of this to true. If yes, then you also have to change the corresponding limits.

  • CCCM_CV_ENABLE = True then modify the highest value (60) MAX_CHARGE_CURRENT_CV = [0, 2, 30, 60] to the same value or bigger as MAX_BATTERY_CHARGE_CURRENT
  • DCCM_CV_ENABLE = True then modify MAX_DISCHARGE_CURRENT_CV = [0, 5, 30, 60]
  • CCCM_T_ENABLE = True then modify MAX_CHARGE_CURRENT_T = [0, 28, 60, 60, 28, 0]
  • DCCM_T_ENABLE = True then modify MAX_DISCHARGE_CURRENT_T = [0, 28, 60, 60, 28, 0]

Driver version >= v1.0.0​

The limits are based on percentages of MAX_BATTERY_CHARGE_CURRENT and MAX_BATTERY_DISCHARGE_CURRENT values, so there is no need for additional modifications. Additionaly you see in the remote console/GUI under SerialBattery → Parameters why it's limited.

VenusOS

Why is the displayed charging/discharging current limit (CCL/DCL) not applied?​

Navigate to Settings -> DVCC, check that DVCC is enabled and that under Controlling BMS your BMS or battery aggregator is selected. On this page normally only DVCC should be enabled.

Why is my battery not switching to float/bulk?​

Make sure you have set this options in the config.ini:

LOGGING = DEBUG  # needed to show debugging in the remote console/GUI
CVCM_ENABLE = True

Go to the remote console/GUI under SerialBattery -> Parameters and go to the bottom. Here you see the requirements which are met/not met to do the switch. The advanced pages are available since v1.3.20240527dev.

VenusOS

Does the driver work for 3.7V based cells also?​

Yes, but you will need to adjust the MAX_CELL_VOLTAGE and MIN_CELL_VOLTAGE values for 3.7V cells instead of the default 3.2V cells.

Recommended values for 3.7V cells are:

MAX_CELL_VOLTAGE = 4.0
MIN_CELL_VOLTAGE = 3.6

Why do I get a Low Voltage alarm?​

Not elaborated completely, in the meanwhile see infos below

Why is DCL jumping from/to 0?​

Not elaborated completely, in the meanwhile see infos below

What is happening is that as soon as no more current is drawn the cell values starts to recover and the BMS release (the charger should only kick in when you are below the min SoC value you have set in the ESS settings).

What helped me here was reducing the Cut-off voltages in the ESS asisstant (there are 4 voltages for different currents) - when the battery voltage dropped to this cut-off voltage, the discharging will stop and the "sustain voltage" will jump in until the battery voltage rises up over the "above-cut-off" value.

Important!!! - When the ESS asisstant is activated, all the 3 "DC input low voltage" settings under the "Inverter" tab are completely ignored by the MP2.

How to solve this:

  1. Current setting > 0 (but I did not test this)
  2. Reducing the ESS "Cut-off voltage" like I mentioned above

Why do I get a high voltage alarm?​

If you receive high voltage alarms that would indicate your battery is:

  1. Not set up correctly and you are using the wrong charge voltages
  2. It has cell imbalance issues

So asuming you have set the max battery voltage for what the battery require, you then need to help the battery to get the cells balanced. You do that by lowering the max voltage to a level where you don’t get high voltage alarms anymore and then slowly over a few weeks you can increase the max voltage to where it should be. This will give the balancers time to work.

In your GX settings go to the DVCC menu and activate the "Limit managed battery charge voltage" feature and lower the "Maximum Charge Voltage". Drop your voltage to 0.2V lees that normal and then increase it every day by 0.05V if you did not get a high voltage alarm during the previous day. If you did get an alarm leave it unchanged for another day.

Do this until you get to the original max charge voltage for your battery.

This will be much faster to do if you use the Keep Batteries changed in ESS option while you are doing this.

Balancing works when ever 1 cell go above the balance threshold, so you are trying to find the battery voltage where that one cell is above the threshold but below the high voltage alarm (e.g. 3.45V - 3.65V) and then giving the balancers time to work down the high cell with the small balance currents (50mA to 200mA).

Daly BMS - High voltage alarm​

For a high voltage alarm on Daly BMS check also Daly BMS - High voltage alarm.

The Daly BMS alarms did not work in driver versions before v1.0.20230531 and therefore in 99% of the cases the BMS is not setup correctly.

Why is the battery current inverted?​

Some Daly BMS send the current as inverted value. This can be corrected by setting INVERT_CURRENT_MEASUREMENT to -1 in the utils.py or config.ini (depending on the installed driver version). See How to edit utils.py or config.ini.

What can I do, if the BMS communication is unstable?​

Most unstable communications arise due to:

  • Cabeling: Check your cables again and make sure that all solder points are making good connection.
  • Missing shielded cable: If the connection gets unstable on greater battery currents and your serial cable is near or along the battery cable, then try to use a shielded cable.
  • Damaged/Defective serial adapters: Try another serial adapter.
  • Cheap USB Hubs: Make sure you are using a qualitative USB Hub with enough power.
  • Raspberry Pi: Do not use a charger for powering the Raspberry Pi. Instead buy a power supply with enough power.

How can I reset the SOC to 100%?​

See the SOC sections on the features page.

Why is my config.ini always reset to default values?​

Probably you forgot to remove the USB/SD card with the venus-data.tar.gz after successful installation. Please delete the file or remove the USB/SD card. This is fixed with >= v1.0.20230512.

Why is the custom name lost after a reboot?​

This feature is only available in and after v1.0.20230724beta.

Fix white screen after install​

Normally this will happen, if you were on an older firmware for your GX.

You can remove the GUI changes or update your GX firmware to solve this.

Remove GUI changes​

Execute the command (matching your driver version) below to restore the GUI.

If you don't know which version of the driver you have installed then try first the option for >= v1.0.0. If you get the error bash: /data/etc/dbus-serialbattery/restore-gui.sh: No such file or directory try the option for <= v0.14.3.

Driver version <= v0.14.3​

# restore original qml
cp -f /opt/victronenergy/gui/qml/PageBattery.qml.backup /opt/victronenergy/gui/qml/PageBattery.qml
# restart gui
svc -d /service/gui && sleep 1 && svc -u /service/gui

Driver version >= v1.0.0​

bash /data/etc/dbus-serialbattery/restore-gui.sh

Update to the latest firmware​

If the removal of the GUI changes did not help, you can force a reinstall/update of the firmware. This takes about 5-15 minutes depending on your device and internet connection.

/opt/victronenergy/swupdate-scripts/check-updates.sh -update -force

If this also did not help then execute this command to prevent any driver to auto install after firmware update.

mv /data/rc.local /data/rc.local.backup
mv /data/rcS.local /data/rcS.local.backup

Now run again the reinstall/update of the firmware.

How many USB to serial adapters can I connect?​

It seems that the Victron GX device has a limit of maximum 8 USB to serial adapters. See Serial battery driver not found if other VE.direct-USB devices are present

$'\r': command not found or syntax error: unexpected end of file​

This indicates, that the line endlings were changed during the upload from LF to CRLF. Run this commands to repair the files:

sed -i 's/\r//' /data/etc/dbus-serialbattery/*.sh
sed -i 's/\r//' /data/etc/dbus-serialbattery/*.py
sed -i 's/\r//' /data/etc/dbus-serialbattery/service/run
sed -i 's/\r//' /data/etc/dbus-serialbattery/service/log/run

Now reboot the device. If this doesn't help, then download/unpack and reinstall the driver again.

tar: conf/serial-starter.d: Cannot open: File exists​

See this page.