User Tools

Site Tools


ccgx:modbustcp_faq

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
ccgx:modbustcp_faq [2015-09-04 16:03] ictbeheerccgx:modbustcp_faq [2023-10-31 10:32] (current) jpasop
Line 1: Line 1:
-====== ModbusTCP FAQ ======+====== GX Modbus-TCP Manual ======
  
-==== Introduction ==== +==== 1. Introduction ==== 
-ModbusTCP is a feature on our [[http://www.victronenergy.com/panel-systems-remote-monitoring/colorcontrol|Color Control GX]]. ModbusTCP is an industry standard protocolthat can be used to interface PLCs or other equipment with Victron productsFor example to enable a heat pump when there is excess solar power, or create a fully integrated glass bridge on a yacht.+Modbus-TCP is a feature on all our [[venus-os:start|GX devices]] eg [[https://www.victronenergy.com/panel-systems-remote-monitoring/cerbo-gx|Cerbo GX]], and [[https://www.victronenergy.com/panel-systems-remote-monitoring/venus-gx|Venus GX]].
  
-Besides reading this FAQmake sure to also read the ModbusTCP section in our  [[http://www.victronenergy.com/upload/documents/Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication whitepaper]].+Modbus-TCP is an industry standard protocolthat can be used to interface PLCs or other third party equipment with Victron products. Through the Modbus-TCP interface you can read and write data to the chargers, battery monitors, inverter/chargers and other products connected to the GX device.
  
-==== Supported ModbusTCP function codes ====+Besides reading this GX Modbus-TCP Manual, make sure to also read the Modbus-TCP section in our  [[https://www.victronenergy.com/upload/documents/Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication whitepaper]]. 
 + 
 +By default, Modbus-TCP is disabled. To enable it, go into the settings menu, scroll down to 'Services', and then enable the Modbus-TCP service. 
 + 
 +==== 2. Addressing, Unit-ID and Registers ==== 
 + 
 +=== 2.1 Definitions === 
 +The Modbus-TCP protocol has two fields for addressing. There is the Unit-id, also referred to as Address, Station address or Slave-address in some PLC software. And the other field is the Register address. 
 + 
 +  * The **Unit-ID** is the device-selector: it tells the GX Device which connected device (ie. which charger, inverter, or battery-monitor) you want to read, or write from. The GX Device then acts as a Modbus-TCP gateway. 
 +  * The **Register Address** then determines the parameter to read or write: ie. voltage, or current, and so forth. 
 + 
 +=== 2.2 Unit-IDs === 
 + 
 +To see a list of available devices, and their Address, go to Settings -> Services -> Modbus/TCP -> Available services: 
 + 
 +{{ :ccgx:modbus-tcp-services.png?nolink&600 |}} 
 + 
 +Additionally this information is also documented on the ‘Unit ID mapping’ tab in the Modbus-TCP excel sheet. 
 + 
 +For the overall system data, look for com.victronenergy.system in the excel sheet, and use Unit-ID 100. 
 + 
 +Note that both Unit-ID 0 and Unit-ID 100 map to the same internal address. We recommend to use ID 100, since many Modbus-TCP clients and PLCs do not work with ID 0. 
 + 
 +=== 2.3 Register addresses === 
 + 
 +The list of available registers is in an Excel sheet, available for download on the [[https://www.victronenergy.com/support-and-downloads/whitepapers|Whitepapers section on our website]]. 
 + 
 +Besides registers for connected Chargers, Inverters, and other products, there is also a set of registers that represent the entire system: com.victronenergy.system. This service is also where the //System Overview// pages in the GUI, and the VRM Dashboard get their data. 
 + 
 +Note that not all list registers are available for each device. For example a BMV Battery Monitor has lots of readings: historical data such as maximum/minimum, for example. A canbus-connected lithium battery might not have all those parameters available. There is no information available on what type of product has what data available. 
 + 
 +Use this table to map the definition in the 'dbus-service-name' in the Excel sheet to a product type: 
 + 
 +^ Device class                   ^ Product types                                              ^ Registers    ^ 
 +| com.victronenergy.vebus        | Inverters (VE.Bus), Multis, and Quattros                   | 3 to 60      | 
 +| com.victronenergy.solarcharger | Solar chargers (both VE.Can and VE.Direct connected)       | 771 to 790   | 
 +| com.victronenergy.pvinverter   | Grid-tie PV Inverters (Fronius, or Energy Meter)           | 1026 to 1039 | 
 +| com.victronenergy.battery | BMVs, CAN-Bus BMS connected batteries \\ Extra parameter set for Lynx Ion and Lynx BMS product family | 259 to 319 \\ 1282 to 1301 | 
 +| com.victronenergy.charger      | Skylla-i and Skylla-IP44                                   | 2307 to 2322 |  
 +| com.victronenergy.inverter     | Inverters (with a VE.Direct connection)                    | 3100 to 3128 | 
 +| com.victronenergy.tank         | Tank levels                                                | 3000 to 3005 | 
 +| com.victronenergy.grid | Energy meters configured to measure the grid | 2600 to 2609 | 
 +| com.victronenergy.gps | GPS | 2800 to 2807 | 
 +| com.victronenergy.tank | Tank sensors | 3000 to 3007 | 
 +| com.victronenergy.genset | Generators  | 3200 to 3223 | 
 +| com.victronenergy.temperature | Temperature sensors <sup>(1)</sup> | 3300 to 3305 | 
 +| com.victronenery.meteo | IMT solar irradiation sensors | 3600 to 3603 | 
 + 
 +(1): These are the auxiliary temperature sensors built-in to our GX devices, such as the Venus GX. For details, see [[venus-os:start|the GX devices datasheet]]. Battery temperatures as measured by an Inverter/charger, Charger or Solar Charger are available together with the rest of that device's data, not under com.victronenergy.temperature. 
 + 
 +==== 3. Supported Modbus-TCP function codes ====
  
 The supported function codes are: The supported function codes are:
Line 16: Line 67:
 Note that there is no difference between function code 3 and 4. Note that there is no difference between function code 3 and 4.
  
-==== Error codes ==== +==== 5. Mapping example ==== 
-^Code^Name^Description^ +
-|0x01|IllegalFunction|The requested function is not supported| +
-|0x02|IllegalDataAddress|The unid it is available, but one or more of the requested register(s) do not exist| +
-|0x03|IllegalDataValue|The requested quantity of registers is invalidSee the modbus specs, http://www.modbus.org/specs.php, for the limits per function code| +
-|0x0A|GatewayPathUnavailable|Unit 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.| +
-|0x0B|GatewayTargetDeviceFailedToRespond|Requested 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  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 [[http://www.victronenergy.com/panel-systems-remote-monitoring/color-control#whitepapers|Color Control page]].+excel sheet containing the Modbus-TCP mapping. This excel sheet is available for download from our website on the [[https://www.victronenergy.com/panel-systems-remote-monitoring/color-control#whitepapers|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. +To request the input voltage of a Multi or Quattro, connected to the VE.Bus sockets on the GX device, 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.+The Modbus-TCP 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 ==== +==== 6. Error codes and trouble shooting ====
-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? ==== +=== 6.1 The common cause: Unit-ID / Register combination ===
-Check the latest [[http://www.victronenergy.com/upload/documents/Datasheet-Color-Control-GX-EN.pdf|datasheet of our Color Control GX]] on our website.+
  
-==== Which parameters can I control via Modbus TCP? ====+In case a certain read or write is not successful, most likely there is an issue in the unitid/registerid combination.
  
-| com.victronenergy.vebus        | /Ac/ActiveIn/CurrentLimit | | +Besides double checking the mappingthere are two ways to see where the error liesOne is to check the last error as shown in the GX Device menusAnd secondly you can look at the error code as is visible on (most but not all) PLCsSee the two sections below for details.
-| 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=UnavailableUnknown | +
-| 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 |+
  
 +=== 6.2 Looking up the last Modbus-TCP Error on the GX Device===
  
-==== Can I change configuration setting in a Multifor example the absorption voltage? ==== +To see why certain register is not availableuse the Settings -> Services -> Modbus-TCP menu. It shows the last error, and reason for that error.
-No not yet.+
  
-==== Can I request multiple registers at the same time? ====+{{ :ccgx:modbus-tcp-error.png?nolink |}} 
 + 
 +=== 6.3 Error codes === 
 + 
 +These error codes are returned by our software to the PLC; and most PLC software tools allow seeing them. 
 + 
 +^Code^Name^Description^ 
 +|0x01|IllegalFunction|The requested function is not supported.| 
 +|0x02|IllegalDataAddress|The requested Unit-ID is available, but one or more of the requested register(s) does not exist.| 
 +|0x03|IllegalDataValue|The requested quantity of registers is invalid. See the modbus specs, http://www.modbus.org/specs.php, for the limits per function code.| 
 +|0x0A|GatewayPathUnavailable|The requested Unit-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 GX device, switched on, and that its data is available on the GX device display.| 
 +|0x0B|GatewayTargetDeviceFailedToRespond|Requested Unit-ID not found in the mapping list. Double check the Unit-ID mapping list in the excel sheet.| 
 + 
 + 
 +==== 7. Support ==== 
 + 
 +The recommended method for support on Modbus-TCP questions is to use the [[https://community.victronenergy.com/spaces/31/index.html|Modifications section on Victron Community]]. Its frequently visited by many people using Modbus-TCP and other methods of integrating with Victron products. 
 + 
 +Direct company support is only offered on a limited basis. For such support, contact our Victron representative. 
 + 
 +==== 8. FAQ ==== 
 + 
 +=== Q1: Which products can be interfaced via Modbus-TCP? === 
 +All products that can be connected to the [[https://www.victronenergy.com/panel-systems-remote-monitoring/color-control|Color Control GX]]. 
 + 
 + 
 +=== Q2: Can I change a configuration setting in a Multi - for example: the absorption voltage? === 
 +No. 
 + 
 +=== Q3: 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. 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? ====+=== Q4: 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. 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? ===+=== Q5: 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? ==== +You cannot interface with them individually if they are configured for parallel-working; or as a three-phase system. Neither is it necessary to address units individually as Modbus-TCP provides system-totals as well as 'per phase' information.
-If you have, for example, two Multis in parallel, and also a separate Quattro, you have two VE.Bus systems: +
-  System 1: two Multis configured as a parallel system +
-  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.+=== Q6: Will unit-id's change after a reboot or loss of power? ===
  
-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: [[ve.can:changing_nmea2000_instances]]. +No.
-==== 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.+=== Q7: Advanced debugging ===
  
-Unit ids of products not connected via USB will not change. 
  
-==== After upgrading the CCGX to v1.16 or later, ModbusTCP no longer works? ==== +If all unit-id's and register-addresses have been checked and re-checked, and still the connection doesn't work, you could try looking at the Modbus-TCP log file on the [[venus-os:start|GX device]]
-After learning from our first ModbusTCP experiences with v1.14, we have changed a few things in v1.16: +
-  Instead of having to login to SSH to start/stop modbustcp, you can enable/disable it from the main menu +
-  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.+Follow these steps: 
 +  - [[ccgx:root_access|Obtain root access]] 
 +  - Login with SSH (use for example Putty in Windows - or simply type //ssh root@[ip address here]// on a Linux or Mac terminal console. 
 +  List the latest log file:<code> 
 +cat /var/log/dbus-modbustcp/current | tai64nlocal 
 +</code>
  
-There are two ways of enabling ModbusTCP: +In case of any errors, the output will look like this:
-  - use the menu and the buttons to find the services menu (last one in the list), and then enable ModbusTCP.  +
-  - 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+  2016-01-08 16:34:24.658248500  INFO 2016-01-08T16:34:24.657 [Server] New connecion:  "141.138.140.60:41792"  
 +  2016-01-08 16:34:24.695846500 ERROR 2016-01-08T16:34:24.689 "Error processing function code 3, unit id 247, start address 258, quantity 42 :" "Unit id is available, but start address does not exist"  
 +  2016-01-08 16:34:24.753921500  INFO 2016-01-08T16:34:24.753 [Server] Disconnected:  "141.138.140.60:41792"
  
-Our apologies for this change, we know how much hassle this can cause+In most cases the problem will be found in either the unit's id address; or the register addresses. Double check the numbers shown in the output with the numbers as used in your Modbus-TCP software or PLC.
  
-===Does Modbus TCP support Hub4? ===+=== Q8: Does Modbus-TCP support ESS? ===
-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 [[http://www.victronenergy.com/support-and-downloads/whitepapers|here]].+
  
-Notes: +Yes. See the [[https://www.victronenergy.com/live/ess:ess_mode_2_and_3|ESS mode 2 and 3 manual]] for more details.
-    * 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.1441375392.txt.gz · Last modified: 2015-09-04 16:03 by ictbeheer

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki