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 revision Previous revision
Next revision
Previous revision
ccgx:modbustcp_faq [2019-08-15 12:27]
guy_stewart replace venus-device with GX device
ccgx:modbustcp_faq [2020-02-06 21:16] (current)
mvader [6. Error codes and trouble shooting]
Line 1: Line 1:
-====== ModbusTCP ​FAQ ======+====== ​GX ModbusTCP ​Manual ​======
  
-==== Introduction ==== +==== 1. Introduction ==== 
-ModbusTCP is a feature on our [[venus-os:​start|GX devices]] eg [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​colorcontrol|Color Control GX]], and also the [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​venus-gx|Venus 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.+ModbusTCP is a feature on our [[venus-os:​start|GX devices]] eg [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​colorcontrol|Color Control GX]], and also the [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​venus-gx|Venus GX]].
  
-Through the ModbusTCP interface you can read and write date to the chargers, battery monitors, inverter/​chargers and other products connected to the GX device. The unit-id combined with the register address is used as a device-selector:​ selecting for example from which device you want to read its battery voltage measurement.+ModbusTCP is an industry standard protocol, that can be used to interface PLCs or other third party equipment with Victron products. ​Through the ModbusTCP interface you can read and write date to the chargers, battery monitors, inverter/​chargers and other products connected to the GX device.
  
-Besides reading this FAQ, make sure to also read the ModbusTCP section in our  [[https://​www.victronenergy.com/​upload/​documents/​Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication whitepaper]].+Besides reading this GX ModbusTCP Manual, make sure to also read the ModbusTCP section in our  [[https://​www.victronenergy.com/​upload/​documents/​Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf|Data communication whitepaper]].
  
-==== Supported ​ModbusTCP ​function codes ====+By default, ​ModbusTCP ​is disabled. To enable it, go into the settings menu, scroll down to '​Services',​ and then enable the ModbusTCP service.
  
-The supported function codes are: +==== 2. Addressing, Unit-ID and Registers ====
-  * ReadHoldingRegisters ​+
-  * ReadInputRegisters ​+
-  * WriteSingleRegister ​+
-  * WriteMultipleRegisters ​16+
  
-Note that there is no difference between function code 3 and 4.+=== 2.1 Definitions === 
 +The ModbusTCP 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.
  
-==== Product categories ​and registers ====+  * 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 ModbusTCP gateway. 
 +  * The **Register Address** then determines the parameter to read or write: ie. voltage, or current, ​and so forth.
  
-In the ModbusTCP Registerlist xlsx file, there is a column called 'dbus-service-name'​. And it must be consulted to find out which set of registers are available for a product.+=== 2.2 Unit-IDs ===
  
-Note that besides device-specific ​registers, 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.+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 ModbusTCP 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 ​   ^ ^ Device class                   ^ Product types                                              ^ Registers ​   ^
Line 34: Line 50:
 | com.victronenergy.grid | Energy meters configured to measure the grid | 2600 to 2609 | | com.victronenergy.grid | Energy meters configured to measure the grid | 2600 to 2609 |
 | com.victronenergy.gps | GPS | 2800 to 2807 | | com.victronenergy.gps | GPS | 2800 to 2807 |
 +| com.victronenergy.tank | Tank sensors | 3000 to 3007 |
 | com.victronenergy.genset | Generators ​ | 3200 to 3223 | | com.victronenergy.genset | Generators ​ | 3200 to 3223 |
 | com.victronenergy.temperature | Temperature sensors <​sup>​(1)</​sup>​ | 3300 to 3305 | | com.victronenergy.temperature | Temperature sensors <​sup>​(1)</​sup>​ | 3300 to 3305 |
 +| com.victronenery.meteo | IMT solar irradiation sensors | 3600 to 3603 |
  
-(1): Check for compatible ​[[venus-os:​start|GX devices]] ​(eg Venus GX) that provide temperature sensor inputsThe battery temperature ​as measured by a sensor connected to a VE.Bus ​device ​is not available. And the battery temperature as measured by a sensor connected to a BMV battery monitor is available ​under the com.victronenergy.battery register set.+(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.
  
-General note: 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 those parameters available. +==== 3. Supported ModbusTCP function ​codes ====
-==== Error codes ==== +
-^Code^Name^Description^ +
-|0x01|IllegalFunction|The requested function is not supported.| +
-|0x02|IllegalDataAddress|The 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|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 supported function codes are: 
 +  * ReadHoldingRegisters ​
 +  * ReadInputRegisters ​
 +  * WriteSingleRegister ​
 +  * WriteMultipleRegisters ​16 
 + 
 +Note that there is no difference between function code 3 and 4. 
 + 
 +==== 5. 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 [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​color-control#​whitepapers|Color Control page]]. excel sheet containing the modbustcp 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 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. 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 ==== +==== 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.+
  
-==== What is a unit-id and what do I need to set it to? ===+=== 6.1 The common cause: Unit-ID / Register combination ​===
-The unit-id, sometimes called ‘slave address’, specifies how a product connected to the CCGX needs to be addressed. See the tab ‘Unit ID mapping’ tab in the Modbus-TCP excel sheet.+
  
-For the overal system datalook for com.victronenergy.system ​in the excelsheet, and use unit-id 100.+In case a certain read or write is not successfulmost likely there is an issue in the unitid/​registerid combination.
  
-Note that both unit-id 0 and unit-id 100 map to the same internal addressWe recommend ​to use id 100, since many ModbusTCP clients and PLCs do not work with id 0.+Besides double checking the mapping, there are two ways to see where the error liesOne is to check the last error as shown in the GX Device menus. And secondly you can look at the error code as is visible on (most but not all) PLCs. See the two sections below for details.
  
-==== Which products can be interfaced via Modbus TCP? ====+=== 6.2 Looking up the last ModbusTCP Error on the GX Device=== 
 + 
 +To see why a certain register is not available, use the Settings -> Services -> ModbusTCP menu. It shows the last error, and reason for that error. 
 + 
 +{{ :​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 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.| 
 + 
 + 
 +==== 7. Support ==== 
 + 
 +The recommended method for report on ModbusTCP 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 ModbusTCP 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]]. All products that can be connected to the [[https://​www.victronenergy.com/​panel-systems-remote-monitoring/​color-control|Color Control GX]].
  
  
-===Can I change a configuration setting in a Multi - for example: the absorption voltage? ​====+=== Q2: Can I change a configuration setting in a Multi - for example: the absorption voltage? ===
 No. No.
  
-===Can I request multiple registers at the same time? ====+=== 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 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 ModbusTCP provides system-totals as well as 'per phase' information. 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 ModbusTCP provides system-totals as well as 'per phase' information.
  
 +=== Q6: Will unit-id'​s change after a reboot or loss of power? ===
  
-==== Will unit-id'​s change after a reboot or loss of power? ====+No.
  
-It may change in the case of VEdirect Devices connected via USB - but even then our experience is that it will only change in the first reboot.+=== Q7: Advanced debugging ===
  
-Unit-id'​s for products //not// connected via USB will not change. 
-==== Advanced debugging ==== 
  
 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 modbustcp log file on the [[venus-os:​start|GX device]]. ​ 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 modbustcp log file on the [[venus-os:​start|GX device]]. ​
Line 108: Line 150:
 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 modbustcp software or PLC. 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 modbustcp software or PLC.
  
-===Does Modbus TCP support ​Hub-4? ==== +=== Q8: Does Modbus TCP support ​ESS? === 
-Yes. See the [[https://​www.victronenergy.com/​live/​system_integration:hub4_grid_parallel_external_control_loop|Hub-4 advanced control ​manual]] for more details.+ 
 +Yes. See the [[https://​www.victronenergy.com/​live/​ess:ess_mode_2_and_3|ESS mode 2 and 3 manual]] for more details.
  
  
-===== DISQUS ===== 
-~~DISQUS~~ 
ccgx/modbustcp_faq.1565864825.txt.gz · Last modified: 2019-08-15 12:27 by guy_stewart