Victron CCGX Modbus TCP FAQ: Configuration and Troubleshooting

Key Takeaways

• Modbus-TCP is disabled by default on Victron GX devices and must be enabled in the settings.
• Incorrect Unit-IDs or Register Addresses are the most common causes of Modbus communication failures.
• Always consult the official Victron Modbus-TCP Excel sheet for correct Unit-IDs and Register Addresses.
• If you cannot establish communication after verifying settings and documentation, consult Victron support.

How do I configure Modbus TCP on a Victron GX device?

Configuring Modbus TCP on a Victron GX device involves enabling the service, identifying the correct Unit-IDs for your devices, and selecting the appropriate Register Addresses for the data you wish to access. The first step is always to enable the Modbus-TCP service within the GX device's settings menu.

Diagnosis and Setup Steps

Follow these steps to set up and diagnose Modbus TCP communication with your Victron GX device, such as a Cerbo GX or Venus GX.

1. Enable Modbus-TCP Service:

• • Navigate to the settings menu on your GX device.
  • Scroll down and select 'Services'.
  • Locate and enable the 'Modbus-TCP service'.
  • Result: The Modbus-TCP service is now active on your GX device, allowing external systems to attempt communication.

2. Identify the Correct Unit-ID:

• • The Unit-ID is a device selector. It tells the GX device which connected component (e.g., inverter, charger, battery monitor) you want to communicate with.
  • For overall system data, which includes information displayed on the GUI System Overview and VRM Dashboard, use Unit-ID 100. This corresponds to com.victronenergy.system.
  • For specific devices, such as requesting the input voltage of a Multi or Quattro connected via VE.Bus, use Unit-ID 246.
  • A list of available devices and their Unit-IDs can be found under Settings -> Services -> Modbus/TCP -> Available services on your GX device, and also in the 'Unit ID mapping' tab of the official Victron Modbus-TCP Excel sheet.
  • Result: You have identified the specific Unit-ID for the Victron component you intend to query or control. Note that Unit-ID 0 and Unit-ID 100 map to the same internal address.

3. Determine the Register Address:

• • The Register Address specifies the particular parameter you want to read or write (e.g., voltage, current, state of charge).
  • For example, to read the input voltage of a Multi or Quattro (using Unit-ID 246), the register address is 3.
  • The comprehensive list of all available register addresses for various Victron products is located in an Excel sheet. This document is available for download from the Whitepapers section of the Victron Energy website.
  • Result: You have the specific register address corresponding to the data point you need.

4. Apply Scaling Factors (if necessary):

• • Some register values require scaling to represent the actual physical quantity.
  • For instance, when reading the input voltage of a Multi or Quattro from register address 3, the raw value must be divided by 10 to get the actual voltage in Volts AC.
  • The necessary scaling factor is specified in the Modbus-TCP Excel sheet for each register.
  • Result: You understand how to convert the raw Modbus register value into its real-world measurement.

5. Understand Modbus Function Codes:

• • Victron GX devices support standard Modbus TCP function codes for reading and writing data.
  • Supported codes include: ReadHoldingRegisters (3), ReadInputRegisters (4), WriteSingleRegister (6), and WriteMultipleRegisters (16).
  • Note that there is no functional difference between ReadHoldingRegisters (3) and ReadInputRegisters (4) when communicating with Victron GX devices.
  • Result: You know which function codes to use for your Modbus client software.

Cause/Fix Table

Modbus TCP Communication Basics

Modbus TCP is an industry-standard protocol that allows Programmable Logic Controllers (PLCs) or other third-party equipment to interface with Victron Energy products via GX devices. This section details the core concepts for establishing reliable communication.

Protocol Overview

Modbus TCP operates over standard Ethernet networks. Your Victron GX device acts as a Modbus server, responding to requests from Modbus client devices. Communication relies on correctly specifying three main parameters:

1. IP Address: The network address of your GX device.
2. Unit-ID: Identifies the specific Victron component (e.g., inverter, battery monitor, or the overall system) you want to interact with.
3. Register Address: Pinpoints the exact data point (e.g., battery voltage, AC input current, inverter state) within that component.

Enabling the Service

As noted, the Modbus-TCP service is disabled by default on all Victron GX devices. You must manually enable it through the device's user interface:

• Access the GX device's menu.
• Navigate to Settings.
• Select Services.
• Toggle the Modbus-TCP service to 'Enabled'.

Locating Unit-IDs and Register Addresses

Accurate Unit-IDs and Register Addresses are critical for successful communication.

• Unit-IDs: You can view a list of available devices and their corresponding Unit-IDs directly on your GX device under Settings -> Services -> Modbus/TCP -> Available services. For comprehensive mapping, refer to the 'Unit ID mapping' tab within the official Victron Modbus-TCP Excel sheet. Remember that Unit-ID 100 is recommended for overall system data (com.victronenergy.system) as some Modbus-TCP clients may not work with Unit-ID 0, though both map to the same internal address.
• Register Addresses: The full list of available registers, including their data types and scaling factors, is provided in a dedicated Excel sheet. This essential document can be downloaded from the Whitepapers section of the Victron Energy website. Always consult this sheet for the most accurate and up-to-date register information.

Supported Function Codes

Victron GX devices support the following Modbus TCP function codes:

• ReadHoldingRegisters (3): Used to read the current value of one or more holding registers.
• ReadInputRegisters (4): Used to read the current value of one or more input registers. (Note: Functionally equivalent to code 3 on GX devices).
• WriteSingleRegister (6): Used to write a single value to a holding register.
• WriteMultipleRegisters (16): Used to write multiple values to a sequence of holding registers.

Safety: General System Interaction

While configuring Modbus TCP is primarily a software task, it involves interacting with your solar energy system. Incorrect write commands via Modbus TCP could potentially alter system behavior.

• Understand Write Operations: Be cautious when using Modbus TCP function codes 6 (WriteSingleRegister) or 16 (WriteMultipleRegisters). Ensure you fully understand the function of any register you intend to write to, as incorrect values could lead to unintended system operation.
• Consult Documentation: Always cross-reference the official Victron Modbus-TCP Excel sheet and product manuals before attempting to write values to registers.
• Physical Safety: Modbus TCP configuration does not typically require physical interaction with wiring. If troubleshooting leads to inspecting physical connections or opening enclosures, ensure all power sources (PV, battery, AC) are isolated and appropriate safety precautions are taken. This type of work should only be performed by qualified personnel.

When to call a technician instead

If you have followed all configuration steps, verified Unit-IDs and Register Addresses against the official Victron documentation, and still cannot establish reliable Modbus TCP communication, it may be time to seek professional assistance.

Consider calling a qualified technician or contacting Victron Energy support if:

• You suspect a network hardware issue that you cannot diagnose.
• You are unable to locate the necessary documentation or interpret the Modbus-TCP Excel sheet.
• Communication issues persist across multiple Modbus client applications.
• You need to diagnose complex interactions between your Victron system and third-party PLCs or control systems.
• Any physical intervention with the GX device or connected components is required, especially if it involves opening enclosures or modifying wiring. Such actions should only be performed by authorized service personnel to avoid voiding warranties or creating safety hazards.