Victron Battery
Victron Battery is a Modbus TCP template for battery monitors and CAN-bus BMS-connected battery systems integrated through a Victron GX device. The template covers the full com.victronenergy.battery register space: real-time readings for voltage, current, temperature, state of charge, and state of health; a comprehensive alarm set covering low and high voltage, temperature, cell imbalance, fuse, and charge current conditions; deep history data including cycle count, deepest discharge, and lifetime energy throughput; and BMS-reported charge and discharge limits. Use this template in ModbusCloud to centralise battery health monitoring across any Victron installation without custom scripting.
- Protocol
- Modbus TCP
- Connection
- Ethernet, Modbus TCP
- Registers
- 84, read only
- Brand
- Victron
- Last updated
Registers (84)
84 read, 0 write
| Name | Unit | Access | Address (Hidden until you enter your email) | Function (hidden) | Type (hidden) |
|---|---|---|---|---|---|
| voltage | V | Read | |||
| starter_battery_voltage | V | Read | |||
| current | A | Read | |||
| temperature | °C | Read | |||
| mid_voltage | V | Read | |||
| mid_voltage_deviation | Read | ||||
| consumed_amphours | Read | ||||
| soc | % | Read | |||
| alarm | Read | ||||
| low_voltage_alarm | Read | ||||
| high_voltage_alarm | Read | ||||
| low_starter_voltage_alarm | Read | ||||
| high_starter_voltage_alarm | Read | ||||
| low_state_of_charge_alarm | Read | ||||
| low_temperature_alarm | Read | ||||
| high_temperature_alarm | Read | ||||
| mid_voltage_alarm | Read | ||||
| low_fused_voltage_alarm | Read | ||||
| high_fused_voltage_alarm | Read | ||||
| fuse_blown_alarm | Read | ||||
| high_internal_temperature_alarm | Read | ||||
| relay_status | Read | ||||
| deepest_discharge | Read | ||||
| last_discharge | Read | ||||
| average_discharge | Read | ||||
| charge_cycles | count | Read | |||
| full_discharges | count | Read | |||
| total_amphours_drawn | Read | ||||
| history_min_voltage | V | Read | |||
| history_max_voltage | V | Read | |||
| time_since_last_full_charge | h | Read | |||
| automatic_syncs | count | Read | |||
| low_voltage_alarms | count | Read | |||
| high_voltage_alarms | count | Read | |||
| low_starter_voltage_alarms | count | Read | |||
| high_starter_voltage_alarms | count | Read | |||
| min_starter_voltage | V | Read | |||
| max_starter_voltage | V | Read | |||
| low_fused_voltage_alarms | count | Read | |||
| high_fused_voltage_alarms | count | Read | |||
| min_fused_voltage | V | Read | |||
| max_fused_voltage | V | Read | |||
| dc_discharged_energy | Wh | Read | |||
| dc_charged_energy | Wh | Read | |||
| time_to_go | h | Read | |||
| soh | % | Read | |||
| charge_max_voltage | V | Read | |||
| discharge_min_voltage | V | Read | |||
| charge_max_current | A | Read | |||
| discharge_max_current | A | Read | |||
| capacity_in_amphours | Read | ||||
| timestamp_1st_last_error | Read | ||||
| timestamp_2nd_last_error | Read | ||||
| timestamp_3rd_last_error | Read | ||||
| timestamp_4th_last_error | Read | ||||
| min_cell_temperature | °C | Read | |||
| max_cell_temperature | °C | Read | |||
| high_charge_current_alarm | Read | ||||
| high_discharge_current_alarm | Read | ||||
| cell_imbalance_alarm | Read | ||||
| internal_failure_alarm | Read | ||||
| high_charge_temperature_alarm | Read | ||||
| low_charge_temperature_alarm | Read | ||||
| low_cell_voltage_alarm | Read | ||||
| victron_state | Read | ||||
| error | Read | ||||
| system_switch | Read | ||||
| balancing | Read | ||||
| number_of_batteries | count | Read | |||
| batteries_parallel | count | Read | |||
| batteries_series | count | Read | |||
| number_of_cells_per_battery | count | Read | |||
| min_cell_voltage | mV | Read | |||
| max_cell_voltage | mV | Read | |||
| shutdowns_due_error | count | Read | |||
| diagnostics_1st_last_error | Read | ||||
| diagnostics_2nd_last_error | Read | ||||
| diagnostics_3rd_last_error | Read | ||||
| diagnostics_4th_last_error | Read | ||||
| allow_to_charge | Read | ||||
| allow_to_discharge | Read | ||||
| external_relay | Read | ||||
| history_min_cell_voltage | V | Read | |||
| history_max_cell_voltage | V | Read |
Loading registers…
Send your device list
If a device is not in the library yet, we build the template for free as soon as we have the register data.
Use cases
- Monitor state of charge and state of health trends over months to detect capacity fade in aging battery banks.
- Alert on low-state-of-charge or cell imbalance alarm registers before they trigger a protective shutdown.
- Track cumulative dc_charged_energy and dc_discharged_energy to verify round-trip efficiency across seasons.
- Compare min_cell_voltage and max_cell_voltage over time to identify cells diverging from pack average.
- Report charge cycle count and full discharge count to maintenance teams for warranty and lifecycle planning.
Installation
Enable Modbus TCP on the Victron GX device by navigating to Settings, then Services, and switching Modbus TCP to enabled; the service listens on TCP port 502 by default.
Connect the ModbusCloud Gateway to the same LAN as the GX device, ensuring the gateway can reach the GX device IP address on port 502.
In the ModbusCloud portal, add the Gateway, import the Victron Battery template, and set the unit ID to match the battery device instance shown in the GX device list under Settings, then Services, then Modbus TCP, then Available services.
Verify the connection by spot-checking the soc register (address 266) and voltage register (address 259) in the portal live view; confirm the values match what the GX device display shows.
Things to watch for
Voltage and current readings look ten or hundred times too large. Why?
Victron Modbus TCP registers use scale factors. Voltage values are transmitted multiplied by 100, and current values by 10. If your client does not apply these scale factors automatically, divide the raw register value accordingly. The ModbusCloud template handles this internally, so raw inflated values indicate the template is not applied or the wrong unit ID is in use.
The gateway connects but all registers return zero or unavailable. What now?
The most common cause is an incorrect unit ID. The GX device assigns a unit ID per connected battery based on its device instance, not a fixed value. Open the GX device interface, go to Settings, then Services, then Modbus TCP, then Available services, and locate the com.victronenergy.battery entry to find the correct unit ID for your battery.
History registers like deepest_discharge and charge_cycles return empty values on a CAN-bus battery. Is the template broken?
No. History registers such as deepest discharge, charge cycles, and mid-voltage are populated only by BMV battery monitors. CAN-bus BMS-connected batteries do not expose those fields over the com.victronenergy.battery service. The corresponding registers will return no data on BMS batteries; this is expected behaviour documented by Victron.
The time_to_go register reads zero. Does this mean the battery is empty?
A value of zero in the time_to_go register is a special case that means the battery is currently charging, not that runtime is exhausted. A genuinely low remaining runtime will return a small positive value. Cross-check with the soc register to confirm the battery state before raising an alert.
Want to see how it works?
