From 04:00 PM CDT – 08:00 PM CDT (09:00 PM UTC – 01:00 AM UTC) Tuesday, April 16, ni.com will undergo system upgrades that may result in temporary service interruption.
We appreciate your patience as we improve our online experience.
NI VeriStand Add-Ons Documents
NI VeriStand Add-on: Modbus Custom Device
Overview
The Modbus Custom Device add-on allows users to add Modbus protocol communication to NI-VeriStand setup. TCP and Serial communication type are supported. For each, either Master or Slave personality can be used. Configuration of the Custom Device is defined via an XML file. This file describes general settings and also Modbus items you want to read/write. Cf. XML file paragraph and/or XML files examples for reference. Two instances of the Custom Device can be used on the same execution target.
Instructions for Use
To use the Modbus Custom Device, instance it in System-Explorer. The capture, below, is a capture of the Custom Device Main page. Browse and select the XML file you wand to use THEN click "Load/Refresh" button. If not error is detected in XML file, the NI-VeriStand channels matching your XML file are created. For details about XML file content definition, Cf. XML file paragraph.
NOTES:
- When a new XML file is loaded, all Modbus channels created previously are deleted.
- If user has already loaded a configuration file and user clicks again on "Load/Refresh" button, then MD5 of previous configuration and new configuration are compared. If MD5 remained the same, then nothing is done. If MD5 is different, then user gets a dialog-box to confirm that all existing channels will be deleted and replaced with channels from new selected XML file.
Installing the Modbus Custom Device
To use the Modbus Custom Device add-on, unzip the add-on files and place "Modbus" folder in Custom Devices folder of your NI-VeriStand installation folder: "<Public Documents>\National Instruments\<VeriStand>\Custom Devices\" directory
- Example destination path on Windows Vista/7: “C:\Users\Public\Documents\National Instruments\NI VeriStand <year>\Custom Devices”
- Example destination path on Windows XP: “C:\Documents and Settings\All Users\Documents\National Instruments\NI VeriStand <year>\Custom Devices”
XML File
4 examples of XML file (for TCP and Serial communications) are available on this page: two for Master, the two other for Slave Modbus type.
The table, below, summarizes the different XML tags which can be used in the XML configuration file.
| Element | Required? | Element Type | Min/Max Occurr. | Description |
|---|---|---|---|---|
| <General_Settings> | YES | complex | 1/1 | Opening tag for General Settings of the Modbus instance. |
| <Type> | YES | xs:string | 1/1 | Specifies the type of Modbus instance. Values supported:
|
| <Communication_Type> | YES | xs:string | 1/1 | Specifies the communication type of Modbus instance. Values supported:
|
| <Read_Write_Loop_Period> | YES | xs:long | 1/1 | Specifies the execution period (ms) of the Read/Write Operations. For the Master use-case, it’s the rate at which we wish to send requests to Slave. For the Slave use-case, it’s the rate at which we want to interact with registers of the simulated Slave device. |
| <TCP_Settings_Port> | NO | xs: unsignedShort | 0/1 | For TCP, specifies the TCP Port used (typically 502). |
| <TCP_Settings_IP_Slave_Address> | NO | xs:string | 0/1 | For TCP Master only, specifies the IP Address (format WWW.XXX.YYY.ZZZ). |
| <TCP_Settings_IP_Timeout> | NO | xs:unsignedInt | 0/1 | For TCP Master only, specifies the connection timeout in ms. |
| <Serial_Settings_Resource_Name> | NO | xs: string | 0/1 | For Serial, specifies the VISA resource name used. |
| <Serial_Settings_Unit_ID> | NO | xs:byte | 0/1 | For Serial only, specifies the device Unit ID. If omitted in XML file, default value used is 0 which can create a 538177 error. |
| <Serial_Settings_Serial_Type> | NO | xs:string | 0/1 | For Serial only, specifies the type. Values supported:
|
| <Serial_Settings_Baud_Rate> | NO | xs:unsignedInt | 0/1 | For Serial only, specifies the baud-rate used. |
| <Serial_Settings_Parity> | NO | xs:string | 0/1 | For Serial only, specifies the parity used. Values supported:
|
| <Serial_Settings_Flow_Control> | NO | xs:string | 0/1 | For Serial only, specifies the flow-control. Values supported:
|
| <Modbus_Items> | YES | complex | 1/1 | Opening tag for list of Modbus Items to Read/Write. |
| <Read_Coils> | NO | complex | 0/Unb. | Opening tag for a Read Coils operation(public function code of 1 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Read_Discrete_Inputs> | NO | complex | 0/Unb. | Opening tag for a Read Discrete Inputs operation(public function code of 2 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Read_Holding_Registers> | NO | complex | 0/Unb. | Opening tag for a Read Holding Registers operation(public function code of 3 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Read_Input_Registers> | NO | complex | 0/Unb. | Opening tag for a Read Input Registers operation(public function code of 4 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Write_Single_Coil> | NO | complex | 0/Unb. | Opening tag for a Write Single Coil operation(public function code of 5 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Address> | YES | xs: unsignedShort | 1/1 | Defines the Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Write_Single_Holding_Register> | NO | complex | 0/Unb. | Opening tag for a Write Single Register operation(public function code of 6 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Address> | YES | xs: unsignedShort | 1/1 | Defines the Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Write_Multiple_Coils> | NO | complex | 0/Unb. | Opening tag for a Write Multiple Coils operation(public function code of 15 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Write_Multiple_Holding_Registers> | NO | complex | 0/Unb. | Opening tag for a Write Multiple Registers operation(public function code of 16 in the MODBUS protocol). |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Write_Multiple_Discrete_Inputs> | NO | complex | 0/Unb. | Opening tag for a Write Multiple Discrete Inputs operation. This function is usable by the Modbus slave only. |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
| <Write_Multiple_Input_Registers> | NO | complex | 0/Unb. | Opening tag for a Write Multiple Input Registers operation. This function is usable by the Modbus slave only. |
| <Base_Name> | YES | xs:string | 1/1 | Defines the name prefix for all Modbus channels in that group. Actual name is made of the prefix concatened with Channel Index (MyPrefix_xxx). This Base_Name value must be unique among all groups of channels. |
| <Starting_Address> | YES | xs: unsignedShort | 1/1 | Defines the starting Address in device Address space of the device. The Modbus specification defines this address as being 1-indexed. This library implementation uses 0-indexed addresses. |
| <Quantity> | YES | xs: unsignedShort | 1/1 | Specifies the number of items in that group of channels. Minimum value is 1. |
NOTES:
- In table above, “Unb” stands for Unbounded.
- In Modbus_Items, for Read_CoilsMultiple_Coils, Write_Multiple_Holding_Registers, Write_Multiple_Registers and Write_Multiple_Discrete_Inputs, the elements: Base_Name, Starting_Adress and Quantity are used to create the NI-VeriStand Channel name.
- In Modbus_Items, for Write_Single_Coil and Write_Single_Register, the elements: Base_Name is used to create the NI-VeriStand Channel name.
Add-on Requirements to Run the Modbus Custom Device
All attempts have been made to provide an add-on comptible with the NI VeriStand shipping examples. The nature of some add-ons requires additional software or hardware to function.
Software
This device was created for use with NI VeriStand 2013 SP1 or NI VeriStand 2014. To use this custom device you must have the following software installed:
- NI-VeriStand 2013 SP1
or
- NI-VeriStand 2014
Hardware
This add-on requires one of the following hardware.
- Real-Time target running PharLap and NI-VeriStand engine
- Windows machine running NI-VeriStand engine
Known Issues
- About Source code, all the Modbus VIs have been put in a LabVIEW Packed Library in order to deploy Custom-Device successfully.
- When RT-Driver is launched, for Serial instances, there is a warning message displayed on the Web-console. Code keeps on executing.
- When code is imported on a new machine, .NET assembly used to deserialize XML configuration file may not load correctly BUT Main page of Custom-Device is not broken in LV environment. So, it may appear later in System-Explorer, once CD code is compiled, Main page of CD will not load correctly and error message saying VI is broken will be returned. To ensure .NET Assembly is loaded correctly, in the LabVIEW project, in XML_Deserializer.lvlib, in Test virtual folder, set correct paths for XML and XSD files and execute the VI. If it executes correctly, then assembly is loaded correctly. If not, go back in file explorer and ensure that access to Assembly is not blocked by OS security. To Unblock Assembly, go into its properties, Security page and there is an option to Unblock the Assembly. Close LabVIEW. Reopen Project and Test VI, a message should notify you that Assembly has been loaded from that location.
- The operation "Read/Write Multiple registers" (code 23) is not supported.
Version History
1.0.0 Beta 1 (August 2014)
- First public version. This version support NI-VeriStand 2013 only.
- NOTES:
- Serial communication has been only tested with 2 "Serial" files joined here using a RS-232 link between 2 distinct machines.
- NOTES:
2014.0.1 (November 2014)
- This version adds support for 2014 version of NI-VeriStand.
2014.1.0 (January 2015)
- This version fixes a bug: "Write Single Holding Register" support was not implemented in RT-Driver part.
https://github.com/NIVeriStandAdd-Ons/Modbus-Custom-Device
2014.1.1 (February 2015)
- This version fixes some Debug messages (typo mistakes)
- This version fixes a warning message when using Serial instances. Warning is displayed but doesn't prevent from executing RT-Driver.
- The source-code is available here, one github:
https://github.com/NIVeriStandAdd-Ons/Modbus-Custom-Device
- The built version is available, here, as attachment.
2014.1.2 (October 2015)
- This version fixes -2206 error at Undeploy.
- This version adds support for "Write Multiple Holding Registers" support for Master.
- The source-code is available here, one github:
https://github.com/NIVeriStandAdd-Ons/Modbus-Custom-Device
- No built version is provided here.
Add-on Requirements to Modify the Modbus Custom Device
- LabVIEW 2014
- LabVIEW Real-Time 2014
The source code is joined in the archive called "Source code_2014_1.0.zip". The project, inside, calls functions from the a XML Deserializer, joined in the second archive called "XML Deserializer.zip". The XML Deserializer is a .NET assembly used to read and parse XML Configuration file and validates XML file agains XSD schema. Source code of XML Deserializer is included in the archive.
Below is the procedure to migrate from one version to later verion:
- Go into "ModbusPharLap LabVIEW Packed Library" folder.
- Open LabVIEW Project called "ModbusPharLap.lvproj".
- Save Project.
- Execute Build Specification "ModbusPharLap" under target "RT PXI Target".
- Copy the .lvlibp file "ModbusPharLap.lvlibp" produced at location "...\builds\ModbusPharLap\ModbusPharLap\c" to root folder of the Source code (replacing past version).
- Close Project "ModbusPharLap.lvproj".
- Open Project "Modbus Custom Device Project.lvproj".
- Under "My Computer", right-click on file called "Custom Device Modbus.xml" and select Explorer. In File Explorer, right-click and select Edit. Adapt version information to target version. close file.
- Under "My Computer", in "Modbus System Explorer.lvlib", open following System Explorer VIs: Modbus Initialization VI.vi, Modbus Main Page.vi, Status Section Page.vi and Status.vi. Ensure that these VIs are not broken and simply save them.
- Save Project.
- Under "My Computer", under Build Specifications, select and execute (Build) "Configuration Release" build specification.
- Under "Pharlap 2" target, in "Modbus Engine.lvlib" file, open the file "Modbus RT Driver VI.vi". Save it.
- Under "Pharlap 2" target, under Build Specifications, select and execute (Build) "Engine Release" build specification.
- Close Project.
Support and Contact
This add-on is provided as open-source software. If it does not meet your exact specification, you are encouraged to modify the source code to meet your needs. It is not officially supported by National Instruments.
If you encounter a problem with this add-on, or if you have suggestions for a future revision, please post to the forum for this add-on https://decibel.ni.com/content/thread/24155. You must use this feedback forum for support. Do not call National Instruments for support for this add-on.
National Instruments does not support this code or guarantee its quality in any way. THIS EXAMPLE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND AND SUBJECT TO CERTAIN RESTRICTIONS AS MORE SPECIFICALLY SET FORTH IN NI.COM'S TERMS OF USE (http://ni.com/legal/termsofuse/unitedstates/us/).
