NI VeriStand Add-on: Scan Engine and EtherCAT custom device
NOTE: This page has been archived, and builds and support are no longer available here. For builds and support, please see the GitHub page for this Custom Device:
Scan Engine/EtherCat Custom Device
Overview
The Scan Engine and EtherCAT custom device allows users to easily read scanned I/O from C series modules located in a CompactRIO, NI 9144 or NI 9145 EtherCAT chassis. The add-on also supports custom FPGA personalities to be used with a 9144 or 9145 chassis.
See the following links for more information:
Introduction to EtherCAT
The RIO Scan Interface Under the Hood
Instructions for Use
After installing the Scan Engine and EtherCAT custom device, it can be added to the system configuration as a custom device. A local chassis can be added if running NI VeriStand on a CompactRIO controller, and any number of EtherCAT Masters and NI 914x slaves can be added. The corresponding slots can be configured for a large number of C series modules. Also, the NI 914x and/or local chassis can be configured to run a custom LabVIEW FPGA personality which communicates with User-Defined Variables.
Installing the Scan Engine and EtherCAT custom device
To use the Scan Engine and EtherCAT custom device, unzip the attached .zip file and follow the instructions in the included "readme.txt"
Add-on Requirements to Run the Scan Engine and EtherCAT custom device
The nature of some add-ons requires additional software or hardware to function.
Software
The most recent version of this add-on was created for use with NI VeriStand 2016 or later. To use the most recent version custom device you must have the following software installed:
- VeriStand 2017 or later
- NI-RIO 17 or later
- NI-Industrial Communications for EtherCAT 17.0 or later (required if using EtherCAT chassis)
- <Optional> LabVIEW 2017 or later with RT and FPGA modules (required for creating custom bitfiles)
Source code of the addon based on LV 2016 is available here: Scan-Engine-Custom-Device Scan-Engine-Custom-Device-Classes, Scan-Engine-Custom-Device-FXP-LLB
To use older versions of the custom device, consult the readme contained inside those downloads.
Older version of the source code based on LV 2011 SP1 can be found in branch. However there is not active development of this legacy branch.
Scan-Engine-Custom-Device/tree/Legacy_up_to_2014, Scan-Engine-Custom-Device-Classes/tree/Legacy_up_to_2014, Scan-Engine-Custom-Device-FXP-LLB/tree/Legacy_up_to_2014
Hardware
This add-on requires the following hardware.
- For Scan Engine: CompactRIO controller/chassis with C-Series modules
- For EtherCAT: RT controller (PXI, PXIe, or cRIO) with NI 914x EtherCAT chassis and C-Series modules
Add-on Requirements to Modify the Scan Engine and EtherCAT custom device
The most recent version of this add-on was created for use with NI VeriStand 2016. To use the most recent version custom device you must have the following software installed:
- LabVIEW 2016 or later
- LabVIEW RT 2016 or later
- NI-RIO 16 or later
- NI-Industrial Communications for EtherCAT 16.1 or later
To modify older versions of the custom device, consult the readme contained inside those downloads.
Troubleshooting
If you experience problems, make sure all of the required software is installed on the host and target machines. Follow all instructions on this page and in the readme to ensure things are set up correctly, and check the Known Issues list.
If problems persist, FTP into your controller, delete the c:\ni-rt\config folder, then reboot the target. (always make a backup copy first before deleting).
For further support, see the "Support and Contact" section at the bottom of this page.
Using the Scan Engine and EtherCAT custom device with NI 986x XNET modules
NI 986x XNET modules require a custom FPGA bitfile be compiled. You can still use NI 986x XNET modules with the scan engine and EtherCAT custom device by taking advantage of "hybrid mode". In hybrid mode, an FPGA bitfile is compiled with IO modules located under the cRIO chassis in the LabVIEW project.
Follow this procedure to create your hybrid mode bitfile for NI VeriStand:
- Create a LabVIEW project
- Add a cRIO target
- Add a chassis under the target
- Add NI 986x XNET modules under the chassis
- Fill in the remaining slots of the chassis with NI 9201 modules. The module type does not really matter, it simply enables the slot for scan engine use.
- Add an FPGA target under the chassis
- Add a blank VI under the FPGA target
- Compile the blank VI
In NI VeriStand:
- Create your system definition file
- Select the controller and select the "FPGA / Scan interface mode" drop down to "FPGA mode"
- Add the scan engine and EtherCAT custom device and add the local chassis and the IO modules you desire
- Add the XNET port desired and on the port settings page, select "986x settings". Select the bitfile you just compiled
Release notes for the Scan Engine and EtherCAT custom device
<4.3.1>
- Source code upgraded to LabVIEW 2016 version
- Support for NI 9145 EtherCAT chassis
- Support for NI Remote I/O controller and modules
<4.3>
- Support for NI-VeriStand 2016
- Support for 3rd Party EtherCAT Slaves added.
<4.2>
- Added support for: NI-9212, NI-9242, NI-9244, NI-9220, NI-9222, NI-9223.
- Special digital personality support added for NI-9437.
- Open-Thermocouple Detection (OTD) property support added for NI-9212 and NI-9213.
<4.1.11>
- Source code upgraded to LabVIEW 2015 version
- Added support for Linux_x64 and Linux_32_ARM targets
- Added wait around detection procedure to allow proper module detection on Linux targets
- 2015 version uses WebDAV for file upload. On VxWorks target must be set password for WebDAV access
<4.1.10>
- Fixed an issue introduced in RIO 13.0 where module detection could sometimes fail yielding error 537707. The previous fix in version 4.1.7 for this issue only considered UDVs, this change now considers module detection as well.
<4.1.9>
- Actually fix run-time module reconfiguration of the 9235, 9236, and 9237 to work. The fix in 4.1.8 did not work.
<4.1.8>
- Fixed an issue introduced in 4.1.1 that run-time (also called dynamic) module reconfiguration for the 9235, 9236, and 9237 no longer worked
<4.1.7>
- Added a new control on the main page of the custom device to work around an NI-RIO issue. In RIO 13.0 through 14.1 (fixed in 15.0 when it releases), user defined variables do not appear immediately after loading a bitfile to a local chassis. The delay varies depending on the CPU power of the target system. If the scan engine devices proceeds as normal after loading the bitfile, error 537707 can occur indicating missing UDVs. Therefore, this new control allows a user to specify a delay to insert after loading all local chassis' bitfiles. It has no effect if no local chassis bitfiles were loaded.
<4.1.6>
- Added file import and export buttons for OTD compensation values on the 9214 page
<4.1.5>
- Fixed a problem that the 9214 module would throw error -65582 and shut down the system if open thermocouple detection was enabled
<4.1.4 Date 9/15/2014>
- Fixed a problem with the 2013 download that would cause error 1124 when using FXP UDVs. This was because the zip file accidentally contained files for another version of NI VeriStand. Since there are no changes to actual custom device, keeping the version at 4.1.4.
<4.1.4>
- Fixed an issue where the system would sometimes go down with error -1950678941 if it experienced a late iteration (late count) and was using a custom FPGA bitfile containing fixed-point user defined variables (UDVs)
<4.1.3>
- Fixed a critical issue introduced in 4.1.1 that causes the custom device to throw error -307970 when using user defined variables in certain configurations
- Improved performance of user defined variables
<4.1.2>
- Fix a ~10 microsecond jitter issue seen when using the 9213
<4.1.1>
- Large real-time performance increase by fixing and working around several performance related bugs. For even more performance, install the latest RIO patch, RIO 13.0.1.
<4.1.0>
- Mutation required for users of NI 9214 modules. Open system explorer, save, close.
- Added support for the NI 9214 module's ability to disable or enable its open thermocouple detection (OTD) and to provide OTD compensation values. OTD is default off
<4.0.5>
- Real time engine performance improvements
- Reduced the file size of the custom device built distribution
- Readme no longer contains duplicate information as this web page. It links to this web page instead.
- Updated built in help page to state default cyclic data bandwidth is 40 (not 20)
<4.0.4>
- Fixed a bug where fixed-point UDVs on a VxWorks target would throw an error
- Reading from a 9213 module no longer throws an error if there are open thermocouple channels with NI-RIO 13.0
<4.0.3>
- Fixed a bug where module references were opened after starting the async loop, causing the refs used by the async loop to be invalid
- fixed some bugs with the renaming of EtherCAT slaves
<4.0.1>
- Some performance improvements made to reading/writing modules
- A new "Prepend slave position to name" option was added to the EtherCAT slave page. This allows you to disable to default behavior of incluidng the position in the name of the slave (ex. "Slave" instead of "0: Slave"). This option will be checked by default.
- The currently installed version of the custom device is now displayed on the main page.
<4.0>
- Mutation is required for this release. After installation you must open system definitions containing this custom device with the system explorer, save, and close.
- Added support to configure the 9478 module properties
- Added support to set the shunt calibration (both at configuration and run time) for the 9235 and 9236
- Added support for ADC sampling rate property on the 9229, 9233, 9234, 9235, 9236, 9237, and 9239
- Added support for 9482
- If there is an existing local chassis with the default name and "add local chassis" is selected, the existing chassis will no longer be overwritten
<3.9>
- Fixed an issue where error 65723 would be seen at deployment in certain system configurations
<3.8>
- Fixed an issue where 9081 and 9082 controllers would have deploy failures due to error -65512. This was done by working around NI-RIO CAR 399571
<3.7>
- Fixed an issue where speciality digital channels would be deleted and recreated every time a specialty digital module was selected. This caused links (mappings, calculated channels, etc) to speciality digital channels to constantly break.
<3.6>
- The custom device will now clear any scan engine timing faults while it is initializing.
<3.5 Date 4/1/2013>
- No changes to the custom device functional at all. The source was simply reorganized some for easier use and rebuilt and smaller distribution. Since there are no changes to functionality keeping the version at 3.5.
<3.5>
- Custom bitfiles can now be used with the local chassis (ie. CompactRIO). You can select a bitfile on the "User Variables" section. Any User-Defined Variables in the bitfile will show up in the custom device.
- The shutdown code of the custom device has been improved. The Scan Engine will be set back into Configuration mode during shutdown (setting all EtherCAT outputs back to their hardware defaults), and unused references are properly cleaned up.
- Usability: The PCL timing source will be set back to "Automatic" if the custom device is deleted
- Usability: "FPGA/Scan interface mode" will be automatically set if using a local chassis
- Upgraded dependencies to be RIO 12.1 and EtherCAT 2.5. These versions are required for use
<3.4>
- New upgrade notes at the top of the readme should be consulted
- If you are upgrading to this version of the custom device from a previous version, you MUST delete the "nemstr.dll", "neviapi.dll", "niecatsv.dll", "nNIBlueBus_nCrioFixed.dll" and "nNIBlueBus_nCrioFixed_nRefnum.dll" files from your <Program Files>\National Instruments\VeriStand 2011 directory. They are no longer required.
- The default EtherCAT bandwidth has been increased from 20% to 40%. Previous versions of the EtherCAT driver were not enforcing this setting and to get the same performance as before, we chose to increase the default bandwidth. If you have set your bandwidth to something other than the default, consider increasing it higher to achieve better performance.
- New add-on status channels display the late counts of this Add-on (if it is failing timing) and the loop duration if this add-on is running in "unsynchronized to NI VeriStand loop" mode.
- Auto detection of local chassis now works (in addition to EtherCAT chassis), however the # of slots available cannot be detected so it is set to 8. Having extra unused slots is fine and doesn't affect behavior
- Fixed an issue that caused system explorer to hang if auto detect failed
- Upgraded dependencies to be RIO 4.1 and EtherCAT 2.3. These versions are required for use.
- Known issue resolved: "error -805 occurs if you run the device synchronized to VeriStand, then unsynchronized. Reboot controller to fix the error"
- Source: removed passwords from the auto-detection VIs
<3.3>
- Added Specialty Digital support for CompactRIO (allso digital modules with 8 channels or less)
- Reduced size of distribution
<3.2.1>
- Resolved an issue introduced in 3.2 that would cause deployment to be unreliable.
- Error codes are now correctly reported instead of listed as "unknown error" if the additional install steps are followed.
<3.2>
- A small change was made to enbable this add-on to work with XNET 986x modules. The user must compile the bitfile they wish to use (containing scan modules under chassis as well as 986x modules) and specify that bitfile on the NI-XNET port page, then they can use those scan modules from the scan module add-on. Details on the change: scan engine rate is now set remotely with an action VI on download so that the scan rate can be changed before XNET starts.
- NI VeriStand should no longer throw a timeout error when deploying to low power cRIO targets and "Synchronize NI VeriStand to Scan Engine" is checked
<3.1>
- Added workaround for RIO driver bug which sometimes caused 9219 module configuration to fail.
- Improved recovery from scan engine faults
<3.0>
- Upgraded custom device for NI VeriStand 2011
<2.3>
- Can now be used on an RT target without the EtherCAT driver installed if only local scan modules are being used. This makes it possible to use the custom device with single-Ethernet port VxWorks targets (such as the cRIO-9014 and the sbRIO-96x2 boards) which cannot install the EtherCAT driver.
<2.2>
- Bug fix: modules with both input and output channels (9401, 9402, 9403) now work correctly
<2.1>
- updated module support: all modules now supported
<2.0>
- first public release
- Not all C series modules and functionality are currently supported. Additional module support will be coming soon!
Custom error codes for the Scan Engine and EtherCAT custom device
537700: There was a mismatch between the EtherCAT Masters configured in the system definition and what was detected on the target system.
537701: There was a mismatch between the EtherCAT Slaves configured in the system definition and what was detected on the target system.
537702: There was a mismatch between the modules configured in the system definition and what was detected on the target system.
537704: Timeout waiting for the asynchronous loop. The asynchronous loop is not running or responding.
537705: A User-Defined Variable (UDV) configured in the system definition was not found on the target.
537706: The FPGA configuration deployed to an EtherCAT Slave does not match what was configured in the system definition. Ensure that the correct FPGA bitfile has been deployed to the target.
537707: A User-Defined Variable (UDV) container was not found.
537710: Unsupported file type. Please select a valid .lvbitx file.
Known Issues (current version)
- Due to NI-Industrial Communications for EtherCAT CAR 643532, the EtherCAT driver will return incorrect I/O references when there are more than 145 I/O Variables on third party EtherCAT targets. This will cause problems for the Custom Device when slaves with more than 145 I/O Variables are used.
- Auto-detection of EtherCAT will not find unconnected EtherCAT masters or empty 9144 slaves
- Automatic discovery does not populate module settings or detect if a custom bitfile is currently deployed (may cause modules in some slots to not be discovered)
- Local chassis can not be automatically detected if the target is in FPGA mode with a pure FPGA bitfile (not "hybrid") bitfile currently running. A possible work around involves deploying the system definition with the controller page setting to "scan mode" and then future detection will work. This isn't a work around if you needed to be in FPGA mode.
- Fixed Point (FXP) User Defined Variables coming from an FPGA on either local or 9144 chassis with a data type larger than 32 bits will cause the custom device to throw error 7 upon deploy. Workaround: Use FXP UDV sizes 32 bits or less
- Using RIO 12.0 with this add-on causes errors when attempting to auto detect or download bitfiles to 9144 slaves. Workaround: Use RIO 4.1 or RIO 12.1 or greater
- Errors 5377xx can sometimes be seen when deploying. See the troubleshooting section of this document.
- Due to NI-RIO CAR 423339 introduced in RIO 12.1, scan performance of the local chassis on 9081 and 9082 controllers is poor. Solved with RIO 13.0.1 patch.
- Due to NI-Industrial Communications for EtherCAT CAR 441474, installing the EtherCAT driver on a computer with only NI VeriStand (and without LabVIEW) doesn't install all needed components to install EtherCAT to a Real-Time target through MAX. Workaround: Download and install the NI-488.2 driver and explicitly select "NI-488.2 3.1.2 for LabVIEW Real-Time" in the install options. Fixed in EtherCAT 2.7
- The auto detect modules button does not work and throws error 1003 if you do not have the NI-Industrial Communications for EtherCAT driver installed.
- The custom device requires NI Industrial Communications for EtherCAT be installed on the host PC even if you're not using EtherCAT.
- Using an XNET module along with a specialty digital module in a cRIO chassis may result in an error upon deployment (CAR 524753) with the message "NI-XNET: (Hex 0xBFF63009) The board's firmware did not answer a command". This error does not occur with 9401 or 9402 modules when specialty digital is configured to none. Workaround: Program the specialty digital module through LabVIEW FPGA and communicate via UDVs.
- Some C Series modules may take several seconds to be discovered by the scan engine, resulting in error 537702 during deployment. Workaround: Set the "Delay after FPGA load (s)" on the main custom device page to a large wait (start with 30 seconds and decrease if deployment is successful).
- After a new installation or an update of the Custom-Device, Help may not be displayed for different pages in System Explorer. Workaround: right-click on the file "Scan Engine.chm" at location "C:Users\Public\Documents\National Instruments\NI VeriStand 2016\Custom Devices\Scan\Engine\", select "Allow".
Support and Contact
Support for this Custom Device now happens through the GitHub page for this Custom Device. For questions, support, or feature requests create an Issue here:
Download This Add-On
NI VeriStand 2017 with NI-RIO 17.0+ and EtherCAT 17.0+:
Scan Engine and EtherCAT 2017 v4.4.1
NI VeriStand 2016 with NI-RIO 16.0+ and EtherCAT 16.1+:
Scan Engine and EtherCAT 2016 v4.4.1
NI VeriStand 2015 SP1 with NI-RIO 15.0+ and EtherCAT 15.0+:
Scan Engine and EtherCAT 2015 SP1 v4.3.1
NI VeriStand 2015 with NI-RIO 15.0+ and EtherCAT 15.0+:
Scan Engine and EtherCAT custom device - 2015 - v4.1.11
Legacy:
NI VeriStand 2014 with NI-RIO 14.0+ and EtherCAT 14.0+:
Scan Engine and EtherCAT custom device - 2014 - v4.1.10
NI VeriStand 2013 with NI-RIO 13.0+ and EtherCAT 2.6+:
Scan Engine and EtherCAT custom device - 2013 - v4.1.10
NI VeriStand 2012 with NI-RIO 12.1+ and EtherCAT 2.5+:
Scan Engine and EtherCAT custom device - 2012 - v4.1.10
NI VeriStand 2011 with NI-RIO 4.1+ and EtherCAT 2.3+:
Scan Engine and EtherCAT custom device - 2011 - v4.1.10
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 Scan Engine & EtherCAT Custom Device Feedback.
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/).