User Tools

Site Tools


ccgx:modbustcp_faq

This is an old revision of the document!


ModbusTCP FAQ

Introduction

ModbusTCP is a feature on our Color Control GX. ModbusTCP is an industry standard protocol, that can be used to interface PLCs or other equipment with Victron products. For example to enable a heat pump when there is excess solar power, or create a fully integrated glass bridge on a yacht.

Besides reading this FAQ, make sure to also read the ModbusTCP section in our Data communication whitepaper.

Supported ModbusTCP function codes

The supported function codes are:

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

Note that there is no difference between function code 3 and 4.

Error codes

CodeNameDescription
0x01IllegalFunctionThe requested function is not supported
0x02IllegalDataAddressThe unid it is available, but one or more of the requested register(s) do not exist
0x03IllegalDataValueThe requested quantity of registers is invalid. See the modbus specs, http://www.modbus.org/specs.php, for the limits per function code
0x0AGatewayPathUnavailableUnit id is defined in the mapping list, but there is no device found on the mapped port. double check the unit id mapping list in the excel sheet, and make sure that the device is properly connected to the CCGX, switched on, and that its data is available on the CCGX display.
0x0BGatewayTargetDeviceFailedToRespondRequested unit id not found in the mapping list, double check the unit id mapping list in the excel sheet

Mapping example

The purpose of this example is to show how to interpret the information in the worksheets of the excel sheet containing the modbustcp mapping. This excel sheet is available for download from our website on the Color Control page.

To request the input voltage of a Multi or Quattro, connected to the VE.Bus sockets on the CCGX, use the following settings: unit-id 246, and set the data address of the first request register to 3.

The ModbusTCP reply will contain 2302. Divide it by 10, as specified in cell E3, and then you have the voltage: 230.2 Volts AC.

Enabling ModbusTCP on the CCGX

By default, ModbusTCP is disabled. To enable it, go into the settings menu, scroll down to 'Services', and then enable the ModbusTCP service.

Which products can be interfaced via Modbus TCP?

Check the latest datasheet of our Color Control GX on our website.

Which parameters can I control via Modbus TCP?

com.victronenergy.vebus /Ac/ActiveIn/CurrentLimit
com.victronenergy.vebus /Mode 1=Charger Only;2=Inverter Only;3=On;4=Off
com.victronenergy.solarcharger /Mode 0=Off;1=On;2=Error;3=Unavailable, Unknown
com.victronenergy.bms /SystemSwitch 0=Disabled;1=Enabled
com.victronenergy.charger /Ac/In/CurrentLimit
com.victronenergy.charger /Mode 0=Off;1=On;2=Error;3=Unavailable, Unknown

Can I change a configuration setting in a Multi, for example the absorption voltage?

No not yet.

Can I request multiple registers at the same time?

Yes, you can! Though make sure not to include non existing registers in your query. Querying register 1 to 100 for example will not work, since registers 1 and 2 do not exist.

Can I implement more features myself?

Yes, you can! We are, slowly, making the Color Control code open source, and the Modbus-TCP sources are already available on https://github.com/victronenergy.

In a parallel or three phase system, how can I address a single unit?

You cannot interface to them individually if they are configured to be in parallel or as a three phase system. Note that is also not necessary to address the units individually, since ModbusTCP provides system totals as well as per phase information.

I have two or more different VE.Bus systems connected, how can I address each of them?

If you have, for example, two Multis in parallel, and also a separate Quattro, you have two VE.Bus systems:

  1. System 1: two Multis configured as a parallel system
  2. System 2: the Quattro

Each of them will have a different unit id. The unit id of the system connected to the VE.Bus port on the back of the CCGX will have unit id 246. The unit id of the other one, connected to the VE.Can ports via a VE.Bus to VE.Can interface, depends on the device instance. The default is device instance 0, which also maps to unit id 0.

To connect multiple VE.Bus systems connected via VE.Can, you need to have multiple VE.Bus to VE.Can interfaces. To make them addressable, each of those canbus interfaces needs to have a unique device instance. For changing the device instance, see this page: Changing NMEA2000 instances.

Will unit ids change after a reboot or loss of power?

Only for vedirect Devices via USB it can change. But even then our experience is that it only changes in the first reboot.

Unit ids of products not connected via USB will not change.

After upgrading the CCGX to v1.16 or later, ModbusTCP no longer works?

After learning from our first ModbusTCP experiences with v1.14, we have changed a few things in v1.16:

  1. Instead of having to login to SSH to start/stop modbustcp, you can enable/disable it from the main menu
  2. Some PLCs do not accept a unit id above 247. Therefore we changed a few unitids:
    • VE-Bus port was 254, is now 246
    • VE.Direct port 1 was 255, is now 247
    • VE.Direct port 2 was 253, is now 245

Best is to change your PLC program to the new unit ids. If you can’t do that, change unitid2di.csv in /opt/color-control/dbus-modbustcp. But then also make sure to disable autoupdating, because otherwise it will be overwritten again.

There are two ways of enabling ModbusTCP:

  1. use the menu and the buttons to find the services menu (last one in the list), and then enable ModbusTCP.
  2. login via ssh (only available if remote support is enabled), and then execute the following command:
 dbus -y com.victronenergy.settings /Settings/Services/Modbus SetValue 1

Our apologies for this change, we know how much hassle this can cause.

Does Modbus TCP support Hub4?

Yes. These registers were created to take control of Hub-4 behavior:

  • Hub4 grid target. Used by hub4 control loop (register 2700, unit-id 239 (first USB device) to 233 (last USB device), unit Watts).
    • Positive: take power from grid.
    • Negative: send power to grid.
    • Default: 0W.
  • Max charge percentage (register 2701). Reduces the charge current relative to the maximum charge current. Note that this settings has higher priority than Hub4 grid target.
    • Min value 0%
    • Max value 100%
    • If 0% is set, charging will be disabled, otherwise the AC-In target will be adjusted whenever necessary.
  • Max discharge percentage (register 2702). Reduces discharge current. At this moment, discharging will be disabled completely when the value set is smaller than 50%. Otherwise discharging will be allowed.

See modbustcp excel sheet for scaling and datatypes, available here.

Notes:

  • Three/split-phase is not possible yet.
  • The update mechanism is slow, which to our opinion is not perfect, but also no problem.

Disqus

~~DISQUS~~

ccgx/modbustcp_faq.1439878514.txt.gz · Last modified: 2015-08-18 08:15 by edevries

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki