
The Victron GX device family (Cerbo GX, Cerbo GX MK2, Venus GX, CCGX) are communication and monitoring platforms that provide Modbus TCP access to connected Victron VE.Bus inverter/chargers (MultiPlus, Quattro). The GX device itself is not an inverter — it acts as a Modbus TCP gateway to the VE.Bus system.
TapHome connects to the GX device over Ethernet via Modbus TCP. The template exposes battery SOC monitoring, 3-phase AC input and output metering, ESS (Energy Storage System) power setpoint control, inverter mode switching, PV inverter management and comprehensive alarm monitoring.
Network connection
The GX device connects to the local network via its Ethernet port. TapHome Core and the GX device must be on the same subnet.
- Protocol: Modbus TCP
- Port: 502
- Default Slave ID: 227 (Cerbo GX VE.Bus port)
- Function codes: 3 (ReadHoldingRegisters), 6 (WriteSingleRegister), 16 (WriteMultipleRegisters)
The default slave ID 227 applies to the Cerbo GX VE.Bus port. Other GX devices use different IDs: 246 for CCGX, 242 for Venus GX, 228 for EasySolar-II GX. Unit IDs have been dynamically assigned since Venus OS 2.60 — verify the actual ID on the GX device via Settings → Services → Modbus/TCP → Available services.
Configuration
Enabling Modbus TCP
Modbus TCP is disabled by default on all GX devices. To enable it:
- Navigate to Settings → Services on the GX device
- Enable Modbus-TCP
Once enabled, the GX device listens on TCP port 502.
TapHome template import
When importing the template in TapHome, provide:
- IP Address — the GX device’s IP on the local network
- Slave ID — VE.Bus unit ID (default: 227 for Cerbo GX)
Assign a static IP address to the GX device in the router’s DHCP settings, or configure a static IP directly on the GX device via Settings → Ethernet, to prevent the address from changing after a reboot.
Device capabilities
The template exposes 10 devices organized into battery monitoring, AC metering, mode control and protection switches.
Battery monitoring
- Battery — reads the VE.Bus state of charge (SOC) from register H:30 as a dimmer level. Service attributes show battery voltage (H:26), battery current with direction indicator (H:27), battery temperature (H:61), VE.Bus charge state (Off, Low Power, Fault, Bulk, Absorption, Float, Storage, Equalize, Passthru, Inverting, Power Assist, Power Supply) and BMS charge/discharge permissions (H:57–59). The readscript monitors H:32 for VE.Bus error codes (1–26) and H:60 for BMS errors. A VE.Bus Reset action (H:62) is available for system recovery.
AC input metering
Three electricity meter devices monitor AC input power per phase:
- Input Power L1 — AC input power phase 1 from H:12, with service attributes for voltage (H:3), current (H:6), frequency (H:9) and ESS power setpoint (H:37). The ESS setpoint is writable via a service action.
- Input Power L2 — AC input power phase 2 from H:13, with corresponding L2 service attributes and ESS setpoint L2 (H:40).
- Input Power L3 — AC input power phase 3 from H:14, with corresponding L3 service attributes and ESS setpoint L3 (H:41).
Each input power device includes an ESS power setpoint service action for its respective phase, allowing TapHome to control the ESS charge/discharge behaviour per phase.
AC output metering
Three electricity meter devices monitor AC output power per phase:
- Output Power L1 — AC output from H:18, with service attributes for voltage (H:15), current (H:18) and frequency (H:21). The readscript monitors per-phase alarms for temperature (H:44), low battery (H:45), overload (H:46) and ripple (H:47).
- Output Power L2 — AC output from H:24, with L2 voltage (H:16), current (H:19) and frequency (H:21). Monitors L2 alarms (H:48–51).
- Output Power L3 — AC output from H:25, with L3 voltage (H:17), current (H:20) and frequency (H:21). Monitors L3 alarms (H:52–55).
Current limit control
- Active Input Current Limit — reads and writes the active input current limit (H:22) in amps. The “Set Limit” service action accepts a float value (0–100 A).
Protection switches
- Feed DC Overvoltage into Grid — toggle switch (H:65) to control whether DC overvoltage is fed back into the grid. Service attributes show maximum overvoltage feed-in power per phase (H:66–68) and AC input ignored status (H:69–70). A service action allows setting the maximum feed-in power per phase.
- PV Inverter — toggle switch (H:56) to enable or disable PV inverter frequency shifting on AC-out. When enabled (switch OFF), the AC-out PV inverter operates normally; when disabled (switch ON), frequency shifting limits the PV output.
Module-level service attributes and actions
The module itself exposes several service attributes accessible from the gateway device in TapHome:
| Attribute | Register | Description |
|---|---|---|
| Phase Count | H:28 | Number of AC phases in the VE.Bus system |
| Switch Position | H:33 | Inverter mode — Charger Only, Inverter Only, On, Off |
| Active Input | H:29 | Active AC input source — AC Input 1, AC Input 2, Disconnected |
| ESS Disable Charge | H:38 | Charge flag — Charge enabled / Charge disabled |
| ESS Disable Feed-in | H:39 | Feed-in flag — Feed in enabled / Feed in disabled |
| ESS Power Setpoint L1–L3 | H:37, H:40, H:41 | Per-phase ESS power setpoint in watts |
Module-level service actions allow switching the inverter mode (Charger Only, Inverter Only, On, Off), toggling the ESS charge flag and toggling the ESS feed-in flag.
System alarm monitoring
The module readscript monitors 7 system-level alarms:
| Register | Alarm | Levels |
|---|---|---|
| H:34 | Temperature alarm | 0=Ok, 1=Warning, 2=Alarm |
| H:35 | Low battery alarm | 0=Ok, 1=Warning, 2=Alarm |
| H:36 | Overload alarm | 0=Ok, 1=Warning, 2=Alarm |
| H:42 | Temperature sensor alarm | 0=Ok, 1=Warning, 2=Alarm |
| H:43 | Voltage sensor alarm | 0=Ok, 1=Warning, 2=Alarm |
| H:63 | Phase rotation warning | 0=Ok, 1=Warning |
| H:64 | Grid lost alarm | 0=Ok, 1=Alarm |
Additional capabilities
The VE.Bus register set (H:3–H:231) provides additional registers beyond what the template currently implements. These include energy counters for AC-in/out/battery flows (H:74–92, volatile — reset on reboot), charge state enumeration (H:95), 32-bit ESS power setpoints for larger systems (H:96–100), advanced ESS settings like Prefer Renewable Energy (H:102), PowerAssist configuration (H:106–108), UPS function control (H:109) and microgrid/droop mode registers (H:200–231). These can be added to the TapHome template in a future update.
Troubleshooting
No Modbus communication
- Verify that Modbus TCP is enabled on the GX device (Settings → Services → Modbus-TCP)
- Confirm the GX device’s IP address — check the router’s DHCP lease table or the GX device’s network settings
- Ensure TapHome Core and the GX device are on the same subnet
- Check that no firewall is blocking TCP port 502
- Verify the correct unit ID — the default 227 applies to Cerbo GX; other GX models use different IDs
Incorrect power readings
The template uses a /100 scale factor for power registers (H:12–14, H:23–25), while Victron documentation specifies a scale factor of 0.1 (meaning raw value × 10 = actual watts). This may result in power readings that are lower than expected. If power values appear incorrect, this is a known template scale factor difference — the relative measurements remain proportionally correct.
VE.Bus error codes
The Battery device readscript checks register H:32 for VE.Bus error codes. Common errors include:
| Code | Description |
|---|---|
| 1 | Device switched off because another phase switched off |
| 5 | Overvoltage on AC-out |
| 10 | System time synchronisation problem |
| 14 | Device cannot transmit data |
| 16 | Dongle missing |
| 17 | A device assumed master status because the original master failed |
| 25 | Firmware incompatibility between connected devices |
| 26 | Internal error |
If persistent VE.Bus errors appear, the VE.Bus Reset action (available on the Battery device) can be used to attempt recovery.
Unit ID changed after Venus OS update
Since Venus OS 2.60, unit IDs are dynamically assigned. After a firmware update, the unit ID may change. Navigate to Settings → Services → Modbus/TCP → Available services on the GX device to verify the current VE.Bus unit ID, then update the TapHome template’s slave ID accordingly.
