Installing Software Requirements
Before installing the cRIO ECAT module-specific packages, ensure your system has:
- LabVIEW 2018 or higher
- LabVIEW FPGA module 2018 or higher
- LabVIEW Real-Time module 2018 or higher
- NI CompactRIO 18.0 or higher
- NI Industrial Communications for EtherCAT 2018 or higher [required if using an NI EtherCAT Master]
After you have installed the base packages listed above, install the latest versions of the KUNBUS EtherCAT software from the JKI VI Package Manager (VIPM):
Figure 1. Search “KUNBUS” to quickly discover the cRIO ECAT S packages (highlighted)
Install both the “cRIO EtherCAT Slave” and “PDO Configurator” packages to your computer. The description of the packages in VI Package Manager will list LabVIEW and Operating System compatibility.
Configuring PDO Data
In EtherCAT, data is sent as Service Data Objects (SDOs) or Process Data Objects (PDOs). SDOs are used for non-cyclic communication, which is typically configuration. PDOs are used for cyclically transferred data, such as I/O samples. The cRIO ECAT S module can automatically receive some SDO data, which is handled by the module’s onboard logic and is not user-configurable. Primary communication between the module and the EtherCAT network takes place using PDOs.
The cRIO ECAT module provides 1024 Bytes for both Tx and Rx PDOs. The PDO-Configurator, a standalone utility, allows you to set the data type (Bool, Int, UInt or Array), name, and direction of each PDO.
The PDO-Configurator will output two necessary files: the ESI file and a PDO file. The ESI file (EtherCAT Slave Information) is a standard file that each EtherCAT slave provides to identify itself and its communication structure. This file is saved in XML format and is sometimes referred to as “the XML file”. The PDO file is a custom binary file that contains information that needs to be sent to the cRIO ECAT S module to configure it to your desired PDO configuration.
Launching the PDO-Configurator
The PDO-Configurator can be started using Start » Kunbus GmbH » cRIO ECAT Slave » Tools » PDO-Configurator, or LabVIEW » Tools » KUNBUS GmbH » PDO-Configurator.
Creating PDO(s)
The labels “RX” and “TX” represent Receive and Transmit and are from the perspective of the network. For example, a module TXPDO is a PDO that the cRIO ECAT module receives from the EtherCAT network. Determining if you need both RXPDOs and TXPDOs will require knowledge of your objectives for this EtherCAT device as a part of the larger network – what will the master send to it? What will it send to the master? These are core questions to determining the type and number of PDOs to create.
To create a PDO, go to PDOs » Add RxPDO or Add TxPDO based on which you would like to create.
Figure 2. Creating a TxPDO in the PDO-Configurator
Once you create a PDO file, you’ll need to populate it with variables. For an RXPDO, these need to match the data being sent to this EtherCAT device (both in index and datatype). You can add variables by going to Variables » Add Var. Then, set the Variable Name and Data Type. If you change Number of Elements to something else, then one the configurator will create an array datatype. The Index of each variable will be important later when you wish to access PDO data in your LabVIEW application.
Note: The NI EtherCAT Master software does not support array data types.
Figure 3. Setting the data type of a RxPDO variable in the PDO-Configurator
Exporting Data
After creating your desired PDOs and filling them with variables, it’s time to export this data. Go to File » Export ESI & PDO file as to save the ESI file and compile the PDO file that will be used to configure the C-Series EtherCAT Slave module. The PDO configurator tool will save both files in the same location you choose in the file dialog. The Tool will add an 8-digit number at the end of the file. This number differentiates multiple module configurations in case you are using more than one module or more than one configuration with the same module. The ID will be programmed as the modules product code by downloading your PDO configuration file.
Downloading to Module
To apply the PDO configuration file to the cRIO ECAT S, there is a download project. This download project can be found in LabVIEW » Tools » KUNBUS GmbH » PDO Configuration Download. This project contains an FPGA VI that will need to be compiled for a specific target before use. For more information on how to migrate this to your FPGA target, visit Moving Examples to a Different FPGA Target. Use the PDO-ConfigurationDownload(Host).vi to send the configuration file to the module. For more information on this process, see page 13 of the Getting Started PDF at LabVIEW » Help » KUNBUS GmbH » cRIO ECAT Slave.
Programming in LabVIEW
The module is accessed and programmed through property and method nodes in LabVIEW FPGA. There are three methods and three properties for the module and sync methods for data exchange. The module methods are Reset, Update and Write PDO file. Reset must be used if the module becomes corrupted and goes into exception state. The Update method gives you control to initiate the SPI transfer between FPGA and module memory. You can either update the Tx or Rx or both memories. Keep in mind that each transfer takes time and if you use both memories you should always update them at the same time. The Write PDO file method allows you to update the PDO configuration as mentioned in the Downloading to Module section. The module properties are vendor ID, module ID and serial number and are characterizing the module. You might want to read those properties ones, to identify your module. At last the data exchange methods give access to the PDO and Sync data.
To see these methods in action, you can open one of the examples. The Getting started example uses most of the programing elements and the Getting started DC example uses all of them. It adds time synchronization to the Ethercat network. These examples can be found in the Example Finder via LabVIEW » Help » Find Examples. Choose the directory Toolkits and Modules » Third-Party Add-Ons » KUNBUS GmbH » EtherCAT.
Configuring the EtherCAT master
As mentioned under Exporting Data the ESI XML file and the PDO configuration uses a unique 8-digit ID. The first 4 digits are representing the unique module ID and the last 4-digits are representing the checksum for your specific PDO configuration. That way the NI EtherCAT Master who uses SDO communication to read the modules product code can differentiate between multiple modules in your network and multiple configurations for the same module.
To use an NI device as a master, you’ll first need to install NI-Industrial Communications for EtherCAT to both the development PC and the Real-Time controller. After this, you can add the slave to a LabVIEW project as outlined in the article: Adding Third-Party EtherCAT Slaves in LabVIEW.
The Getting started example brings the ECAT_RT_NI-Master Example VI, that uses the programmatic way of querying the EtherCAT network compared to the static project-based method. To use the example, the ESI XML file needs to be imported to your RT target that holds the module.
In case you want to store, remove or rename ESI files manually, here are the paths to both locations:
- Windows OS HOST for static project based configuration: \\Program Files(x86)\National Instruments\Shared\IndComECAT\DD
- Linux RT Target for programmatic configuration: /files/var/local/natinst/IndComECAT/DD
Note: If you change anything manually you need to restart the target or Host LabVIEW for the XML changes to be recognized.
If working with a third party master, consult their documentation on how to add a slave to the network. Many master software programs require the ESI file for the slave, which you created in “Configuring PDO Data”.
Finding More Help
In addition to this tutorial, there are two documents that ship with the driver. The Module Specification and the Getting Started manual can be found in LabVIEW » Help » KUNBUS GmbH » cRIO ECAT Slave. For support, you can call NI Support or post a question on the Industrial Communications forum page.