Victron GX Modbus-TCP: Common Questions and Troubleshooting

Key Takeaways

• Victron GX Modbus-TCP is disabled by default and must be enabled in settings.
• Correct Unit-ID and Register Address are critical for successful data communication.
• Specific error codes like 0x01 or 0x0A point to distinct communication problems.
• For detailed register mapping, consult the official Victron Modbus-TCP Excel sheet.

Why is my Victron GX Modbus-TCP connection not working?

The most common reason for a non-functional Victron GX Modbus-TCP connection is that the service is disabled by default, or there is an issue with the Unit-ID or Register Address combination. The first step is always to ensure the Modbus-TCP service is enabled in your GX device's settings.

Diagnosis

Follow these steps to diagnose common Victron GX Modbus-TCP communication problems.

1. Check Modbus-TCP Service Status:

• • What to do: Navigate to the settings menu on your GX device, scroll down to 'Services', and check if the Modbus-TCP service is enabled.
  • What it means: By default, Modbus-TCP is disabled. If it is disabled, communication will not be possible.
  • Action: If disabled, enable the Modbus-TCP service.

2. Verify Unit-ID:

• • What to do: Confirm the Unit-ID used in your Modbus-TCP client matches the intended device on the GX system. For overall system data, use Unit-ID 100. For specific devices like a Multi or Quattro connected to VE.Bus, Unit-ID 246 is used.
  • What it means: The Unit-ID is the device-selector: it tells the GX Device which connected device you want to read, or write from. An incorrect Unit-ID will result in communication failure or incorrect data.
  • Action: Adjust the Unit-ID in your client to match the target device. Note that while Unit-ID 0 and Unit-ID 100 map to the same internal address, Unit-ID 100 is recommended as many Modbus-TCP clients and PLCs do not work with ID 0.

3. Verify Register Address:

• • What to do: Check that the Register Address used in your Modbus-TCP client corresponds to the specific parameter you wish to read or write. For example, to request the input voltage of a Multi or Quattro, set the data address of the first request register to 3.
  • What it means: The Register Address determines the parameter to read or write, such as voltage or current. An incorrect address will lead to failed reads/writes or irrelevant data.
  • Action: Consult the Victron Modbus-TCP Excel sheet for the correct register addresses for your desired parameters.

4. Interpret Error Codes:

• • What to do: If your Modbus-TCP client receives an error code, identify the code (e.g., 0x01, 0x02, 0x0A).
  • What it means: Each error code indicates a specific type of communication problem.
  • • 0x01 (IllegalFunction): The requested function is not supported.
    • 0x02 (IllegalDataAddress): The requested Unit-ID is available, but one or more of the requested registers does not exist.
    • 0x03 (IllegalDataValue): The requested quantity of registers is invalid.
    • 0x0A (GatewayPathUnavailable): The requested Unit-ID is defined in the mapping list, but no device is found on the mapped port.
    • 0x0B (GatewayTargetDeviceFailedToRespond): The requested Unit-ID is not found in the mapping list.
  • Action: Use the table below to identify the likely cause and fix for the specific error code received.

Cause/fix table

Understanding Victron GX Modbus-TCP Communication

Modbus-TCP is an industry standard protocol that allows you to interface PLCs or other third-party equipment with Victron products. Through the Modbus-TCP interface, you can read and write data to chargers, battery monitors, inverter/chargers, and other products connected to the GX device.

Enabling the Service

By default, Modbus-TCP is disabled on Victron GX devices like the Cerbo GX and Venus GX. To enable it, you must go into the settings menu, scroll down to 'Services', and then enable the Modbus-TCP service.

Unit-ID and Register Address

Successful Modbus-TCP communication relies on correctly specifying the Unit-ID and Register Address:

• Unit-ID: This is the device-selector. It tells the GX Device which connected device (e.g., which charger, inverter, or battery-monitor) you want to read or write from. For overall system data, use Unit-ID 100. While Unit-ID 0 also maps to the same internal address, Unit-ID 100 is recommended because many Modbus-TCP clients and PLCs do not work with ID 0. For specific requests, like the input voltage of a Multi or Quattro connected to the VE.Bus sockets on the GX device, use Unit-ID 246.
• Register Address: This determines the specific parameter to read or write, such as voltage or current. For example, to request the input voltage of a Multi or Quattro, set the data address of the first request register to 3.

Supported Function Codes

The Victron GX Modbus-TCP interface supports the following function codes:

• ReadHoldingRegisters = 3
• ReadInputRegisters = 4
• WriteSingleRegister = 6
• WriteMultipleRegisters = 16

Note that there is no functional difference between function code 3 and 4 for Victron GX devices.

System Data Service

Besides registers for individual connected products, there is also a set of registers that represent the entire system, identified as com.victronenergy.system. This service is where the System Overview pages in the GUI and the VRM Dashboard get their data.

Detailed Register Mapping

The specific register addresses for various parameters are not provided directly in the general FAQ. Victron Energy provides a detailed Modbus-TCP Excel sheet that lists all available registers and their corresponding Unit-IDs for different products. This sheet is the primary resource for advanced Modbus-TCP integration.

Safety

No specific safety facts for the hardware class are stated in the provided documentation for Modbus-TCP communication. Always follow general electrical safety practices when working with solar power systems.

When to call a technician instead

If you have followed all troubleshooting steps, verified your Unit-IDs, Register Addresses, and function codes, and are still unable to establish reliable Modbus-TCP communication, it may be time to contact a qualified Victron Energy technician. Issues could stem from network configuration, firmware problems, or underlying hardware faults within the GX device or connected components. Attempting advanced diagnostics without proper training could void warranties or damage equipment.