Victron Battery-Inverter
The Victron Battery-Inverter template targets Victron Energy ESS systems monitored through a GX device (Cerbo GX or Venus GX) running Modbus TCP. The template reads the full system picture exposed by the com.victronenergy.system service: per-phase AC consumption, grid power, AC- and DC-coupled PV production, battery state of charge, voltage, current, time-to-go, and VE.Bus charger output. ESS Mode 2 control registers covering the grid setpoint, charge and discharge current limits, max feed-in power, and the PV power limiter flag are also captured. This gives installers a single, structured data source for energy-flow visibility across the entire Victron installation.
- Protocol
- Modbus TCP
- Connection
- Ethernet, Modbus TCP
- Registers
- 43, read only
- Brand
- Victron
- Last updated
Registers (43)
43 read, 0 write
| Name | Unit | Access | Address (Hidden until you enter your email) | Function (hidden) | Type (hidden) |
|---|---|---|---|---|---|
| serial_number | Read | ||||
| ccgx_relay1_state | Read | ||||
| ccgx_relay2_state | Read | ||||
| ac_pv_on_output_power_l1 | W | Read | |||
| ac_pv_on_output_power_l2 | W | Read | |||
| ac_pv_on_output_power_l3 | W | Read | |||
| ac_pv_on_input_power_l1 | W | Read | |||
| ac_pv_on_input_power_l2 | W | Read | |||
| ac_pv_on_input_power_l3 | W | Read | |||
| ac_consumption_power_l1 | W | Read | |||
| ac_consumption_power_l2 | W | Read | |||
| ac_consumption_power_l3 | W | Read | |||
| grid_power_l1 | W | Read | |||
| grid_power_l2 | W | Read | |||
| grid_power_l3 | W | Read | |||
| ac_genset_power_l1 | W | Read | |||
| ac_genset_power_l2 | W | Read | |||
| ac_genset_power_l3 | W | Read | |||
| active_input_source | Read | ||||
| dc_battery_voltage | V | Read | |||
| dc_battery_current | A | Read | |||
| active_power | W | Read | |||
| battery_soc | % | Read | |||
| battery_state | Read | ||||
| battery_consumed_amphours | Read | ||||
| battery_time_to_go | s | Read | |||
| dc_pv_power | W | Read | |||
| dc_pv_current | A | Read | |||
| charger_power | W | Read | |||
| dc_system_power | W | Read | |||
| ve_bus_charge_current | A | Read | |||
| ve_bus_charge_power | W | Read | |||
| ess_control_loop_setpoint | W | Read | |||
| ess_max_charge_current_percentage | % | Read | |||
| ess_max_discharge_current_percentage | % | Read | |||
| ess_control_loop_setpoint_scale_factor_2 | W | Read | |||
| ess_max_discharge_power | W | Read | |||
| system_max_charge_current | A | Read | |||
| max_feed_in_power | W | Read | |||
| feed_excess_dc | Read | ||||
| dont_feed_excess_ac | Read | ||||
| pv_power_limiter_active | Read | ||||
| max_charge_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 battery state of charge and time-to-go to detect unexpected overnight discharge patterns early.
- Track per-phase grid power on L1, L2, and L3 to verify feed-in compliance with local grid operator limits.
- Compare DC-coupled PV power against AC-coupled PV output to verify MPPT and inverter performance across seasons.
- Alert on active_input_source changes to catch unplanned generator or grid switchover events during mains outages.
- Report ESS max discharge power and max feed-in power readings to confirm ESS configuration matches site energy agreements.
Installation
Enable Modbus TCP on your GX device by navigating to Settings, then Services, and switching the Modbus TCP toggle to enabled.
Connect the ModbusCloud Gateway to the same LAN as your GX device, ensuring both can reach each other on TCP port 502.
In the ModbusCloud portal, add your Gateway, import the Victron Battery-Inverter template, and set the Unit ID to 100, which maps to the com.victronenergy.system service for system-wide registers.
Verify the connection by spot-checking register 843 (battery_soc): a value between 0 and 100 confirms the Gateway is polling the correct service and Unit ID.
Things to watch for
Battery voltage reads ten times too high. What is wrong?
Register 840 (dc_battery_voltage) uses a scale factor of 10 in the official Victron register list. If your integration applies raw uint16 values without dividing by 10, the voltage will appear ten times larger than the actual DC bus voltage. Divide the raw register value by 10 to obtain volts.
Grid power registers return large positive numbers instead of negative feed-in. Why?
Registers 820 to 822 are signed int16 types. Many Modbus clients default to reading registers as unsigned 16-bit integers. A negative value such as -500 W is encoded as 65036 when treated as unsigned. Configure your client to interpret these registers as signed 16-bit integers to read feed-in power correctly.
The Gateway connects but all registers return zero or unavailable. What now?
Modbus TCP is disabled by default on Victron GX devices. Confirm it is enabled under Settings, then Services, then Modbus TCP on the GX device. Also verify you are polling Unit ID 100. Unit ID 0 maps to the same service but many clients reject it; use 100 as recommended by Victron.
Is it safe to write to the ESS setpoint and limit registers from the portal?
The ESS control registers (addresses 2700 to 2710) are read-only in this template, but treat any external ESS setpoint writes with care. ESS Mode 2 has no automatic passthrough fallback if a controlling script stops updating values, meaning the inverter can continue acting on the last written setpoint until manually overridden. Always test setpoint changes in a controlled environment first.
Want to see how it works?
