With this plugin, a controller can be used as an EtherCAT master for data exchange (PDO) and file handling (FoE)
Table of Contents
- Introduction
- Requirements and Limitations
- Plugin Installation
- Plugin Configuration
- Example: File Transfer via FoE
1. Introduction
The plugin itself is based on the IgH EtherCAT Master and implements the following functions:
- Exchange process data as PDOs
- File handling via FoE
2. Requirements and Limitations
The minimum system requirements for this plugin are:
- Q.station XB ETH
-
Controller firmware v2.14 B18
-
GI.monitor version 1.10.2.0 or later (https://dev.gantner-instruments.com/webfiles/public/Download/Q.Station/tools/GI.monitor.zip)
3. Plugin Installation
Download the correct plugin version that matches the controller firmware version from the Gantner public download area.
For installation instructions, please take a look at the page: installing a plugin.
4. Plugin Configuration
The configuration of a plugin is done through a plugin-specific configuration interface using GI.monitor.
- The EtherCAT master can read and write data to the controller's virtual variables. The controller virtual variables must be created first before configuring the plugin. The virtual variables should be configured as Setpoint and the Data direction should be Input for data from modules (read) or Input/Output for writing data to the modules.
- Start GI.monitor from the GI.bench menu in the system tray. To connect to the plugin, enter the Server Address (IP address of your controller), set the Server Port to 1200, and click Connect. If you do not know the IP address of your Q.series controller, use the Search button to find all controllers connected to your network.
- Next to the Route dropdown list click Reload and then select GInsEtherCATMaster.
The hardware has to be configured once to use the EtherCAT master. The steps needed are shown below.
Configure
The setup of data exchange can be simplified using the plugin configuration with Configure. This configuration is automatically loaded when the plugin is initialized and sets the exchange range. Using Configure combines the calls PDO_SetMemoryToRead and PDO_SetMemoryToWrite and the settings are stored permanently.
In the current state, a virtual variable limit constrains oversampling (each oversampling value needs its own variable). This can lead to a situation in which more data is available in the EtherCAT domain than can be displayed in GI.bench.
In this case, a circle buffer can be used to store more data. The configuration of the buffer is part of the plugin configuration and consists of BufferIndex, Name, and a UUID.
GetStates / GetStatesEtherCAT
Returns current information of the plugin itself and the EtherCAT system. This may be useful in error handling.
FoE_ActivateMode
FoE file exchange requires userland functions and therefore the real-time operation has to be stopped. After activation of this mode, FoE operations are possible. Do not forget to disable FoE mode afterward to restart real-time operation.
FoE_GetSlavesInBus
Returns more detailed information on EtherCAT slaves found.
FoE_Operation_Start / FoE_Operation_isFinished
This is the main function to handle file exchange via FoE for every given request. Multiple files can be set within FoE_Operation_Start, but file handling is done in sequence.
The current state of file exchange is returned in FoE_Operation_isFinished with more detailed information about each request.
PDO_GetEntries / PDO_ListVariableOffsets
PDO data exchange needs the information of data located in the GIns process image and the EtherCAT domain. This information can be gathered with PDO_GetEntries regarding the EtherCAT domain and PDO_ListVariableOffsets regarding the GIns process image.
In PDO_GetEntries all PDOs are shown for a specific slave.
In PDO_ListVariableOffsets all created variables on the Q.station are shown. A desired variable name can be set as optional, to get information about this variable only.
PDO_SetMemoryToRead / PDO_SetMemoryToWrite
With the given information of variable location, the data exchange is set using these functions depending on direction.
In the case of reading from EtherCAT, data from the domain is written to input parts in the GIns process image. Therefore, OffsetInputByte is needed. Mention an initial offset of 8 bytes storing the timestamp.
In the case of writing to EtherCAT, data from output parts of the GIns process image is written to the domain and the knowledge of OffsetOutputByte is needed.
Attention: The set memory is only temporary and will be removed at plugin restart. Use Configure for a permanent setting.
5. Guide: Setup Hardware once and Check System State
The configuration file of the used EtherCAT master has to be prepared with the MAC address and driver module. This file can be found on the station at /etc/ethercat.conf. Per default, the eth1 interface with r8169 is used with the function ConfigureHardware. This configuration has to be done only once and afterward the plugin has to be restarted with Start.
Only when the hardware configuration is set, the EtherCAT master can be used for data and file exchange. An exemplary call of ConfigureHardware is shown below with the default values.
If only one interface is listed, set an example static IP address for the second interface. This should turn on the second interface.
The current plugin state can be found with GetStates. Usually InfoText should be SMState_ProcessData as shown in the response, otherwise, restart the plugin with Stop, and Start.
Additionally, the state of the EtherCAT system can be found with GetStatesEtherCAT.
6. Example: Exchange Data via PDO
In this example, EtherCAT data should be read from modules and written into the process image of the Q.station.
Used Hardware:
For this example the following hardware is used:
- Q.station XT ETH (Master)
- Q.bloxx XE BC (Slave 0)
- Q.bloxx XE A102 (Slave 1)
- Q.bloxx XE A102 (Slave 2)
Slave 1 is configured with an input Slave1_AI and an input/output variable Slave1_DO:
Slave 2 is configured with one input variable Slave2_AI with oversampling. Mention the right oversampling setting according to the Q.station CPU rate.
Create Variables in GI.bench:
A virtual input variable (type: setpoint) should be created to read measurements for each EtherCAT variable. An additional input/output variable is needed to write a value to the slaves.
In this case, the variables EC1_AI and EC1_DO_CurrentValue should store the measurements of slave 1, and EC2_AI_X store oversampling measurements of slave 2. In EC1_DO_DesiredValue the desired output value for the digital output on slave 1 is written.
Get needed Variable Information
For setting up the data exchange two pieces of information are needed: Where is the data in the process image? And where in the EtherCAT domain? For this purpose, PDO_GetEntries and PDO_ListVariableOffsets can be used.
With PDO_GetEntries the information of location in the EtherCAT domain can be found for a specific slave. For example, the first variable of slave 1 can be seen below. The most interesting information is OffsetInDomain and SizeByte for each entry. With this knowledge, the data location in the EtherCAT domain is fixed.
The information of location in the GIns process image can be found with PDO_ListVariableOffsets, where desired variable information can be found using the name. The needed information for each variable is listed in OffsetInputByte (for EtherCAT inputs) and OffsetOutputByte (for EtherCAT outputs) of the response.
In this example, the EtherCAT domain and GIns process image are built up as shown below:
| Byte Start | EC Domain | GIns Input | GIns Output |
| 0 | Slave1_AI | Timestamp | EC1DODesiredValue |
| 4 | Slave1_DO (in) | Timestamp | - |
| 8 | Slave2AI0 | EC1_AI | - |
| 12 | Slave2AI1 | EC1DOCurrentValue | - |
| 16 | Slave2AI2 | EC2AI1 | - |
| 20 | Slave2AI3 | EC2AI2 | - |
| 24 | Slave2AI4 | EC2AI3 | - |
| 28 | Slave1_DO (out) | EC2AI4 | - |
| 32 | - | EC2AI5 | - |
| 34 | - | EC1DODesiredValue | - |
Set Data Exchange
The actual data exchange can be set using PDO_SetMemoryToRead and PDO_SetMemoryToWrite.
For simplicity the whole input range of the EtherCAT domain is copied and therefore following PDO_SetMemoryToRead command is done with Offset_EC_Domain = 0, Offset_GIns_InputByte = 8, and Size = 32. Mention the needed input offset of 8 Bytes resulting from the timestamp.
In the same way, the output range is set with PDO_SetMemoryToWrite with the parameter Offset_EC_Domain = 28, Offset_GIns_OutputByte = 0, and Size = 4. With this command, the output part of EC1_DO_DesiredValue is mapped with the output part of Slave1_DO.
Now the data should be exchanged and can be seen for example in GI.bench.
Troubleshooting:
- Don't forget to set hardware configuration once with ConfigureHardware.
- Check the data range of exchange (offset and size) and matching data types.
- Try to decrease EtherCAT bus frequency to 2 kHz if data is not exchanged completely.
7. Example: File Transfer via FoE
This example shows how to perform a file transfer via FoE in the same hardware setup as in the example before.
Enable FoE Mode
The first step of file transfer via FoE is enabling the FoE mode with FoE_ActivateMode. In this mode, the continuous data exchange is interrupted and the device is prepared for file exchange.
Start FoE Read-Operation:
To use FoE three pieces of information are needed: desired slave (SlavePos), the file on the master (filePathOnMaster), and the file on the slave (filePathOnSlave). Using this information the read operation is started with FoE_Operation_Start.
In this case, three files should be read from the slaves and stored on the master.
Check the current State of File Transfer:
The current state of the file transfer is returned in FoE_Operation_isFinished. The transfer is done file by file and therefore some time is needed especially with bigger files. The state of the whole transfer (AllRequestsFinished) and of each request can be seen in the response.
To check if the FoE operation is finished, the function FoE_Operation_isFinished is called. In this case, the operation is done (AllRequestFinished) with a successful reading from both slaves. The operation on bus position 0 failed because the desired file is not available on the device.
Disable FoE Mode:
Don't forget to disable the FoE mode afterward.
Finally, normal data exchange is resumed by deactivating the FoE mode.
Attention: The plugin configuration is set again (see Configure) and information from previous PDO_SetMemoryToRead and PDO_SetMemoryToWrite is lost.