Configure EtherCAT Main Device Node Model

Step 5 of 5 in Modeling EtherCAT Networks

Before configuring the model, complete the procedure in Configure EtherCAT Network by Using TwinCAT 3.

To configure model slrt_ex_ethercat_beckhoff_aio for execution by using the target computer as main device node, complete the procedure in Configure EtherCAT Init Block.

Configure EtherCAT Init Block

Before you use the EtherCAT Init block, configure the EtherCAT^® network with TwinCAT^® 3.

Before you start this procedure, familiarize yourself with TwinCAT 3 and its documentation.

As part of the configuration process, create and save an EtherCAT Network Information (ENI) file. See Configure EtherCAT Network by Using TwinCAT 3.

To include EtherCAT distributed clocks when PTP is enabled for the model, use EtherCAT bus shift mode.

To configure the EtherCAT Init block of model slrt_ex_ethercat_beckhoff_aio:

1. Open example SlrtEtherCATCommBeckhoffAIOSubordinateDevicesExample and example model slrt_ex_ethercat_beckhoff_aio. In the MATLAB Command Window, type:

   openExample('slrealtime/SlrtEtherCATCommBeckhoffAIOSubordinateDevicesExample');
   openExample('slrealtime/SlrtEtherCATCommBeckhoffAIOSubordinateDevicesExample', ...
       'supportingFile','slrt_ex_ethercat_beckhoff_aio.slx');

2. Double-click the EtherCAT Init block.

3. In the Config file (ENI) text box, browse to the EtherCAT Network Information (ENI) file that you created when you configured the network (here, 'BeckhoffAIOconfig.xml'). You can enter the file name with or without single quotes.

4. Use the default value 0 for parameter Network Device index.

   If the model includes more than one EtherCAT network, enter a unique Network Device Index for each network. Enter the same value for all blocks in each network.

5. Enter the Ethernet Port Number for the EtherCAT port that you are connecting to your EtherCAT network. See Install EtherCAT Network for Execution.

6. Take the default value Large model for parameter DC Tuning.

   

7. To update the data in the EtherCAT Init block and propagate it to the other EtherCAT blocks, click Refresh Data.

8. Click OK.

Configure EtherCAT PDO Receive Blocks

Before beginning this procedure, you must have selected a valid ENI file in the EtherCAT Init block.

Before you start this procedure, familiarize yourself with TwinCAT 3 and its documentation.

To configure the EtherCAT PDO Receive blocks of model slrt_ex_ethercat_beckhoff_aio:

1. Double-click the EtherCAT PDO Receive block labeled EtherCAT PDO Receive.

2. Set parameter Network Device Index to the value set in the EtherCAT Init block.

3. From the Signal Name list, select the variable, here Term 2 (EL3062).AI Standard Channel 1.Value.

4. Observe the value in seconds of parameter Sample Time.

   

5. Click OK.

Execute steps 1–5 for the EtherCAT PDO Receive block labeled EtherCAT PDO Receive 1.

Configure EtherCAT PDO Transmit Blocks

Before beginning this procedure, you must have selected a valid ENI file in the EtherCAT Init block.

Before you start this procedure, familiarize yourself with TwinCAT 3 and its documentation.

To configure the EtherCAT PDO Transmit blocks of model slrt_ex_ethercat_beckhoff_aio:

1. Open model slrt_ex_ethercat_beckhoff_aio.

2. Double-click the EtherCAT PDO Transmit block labeled EtherCAT PDO Transmit.

3. Set parameter Network Device Index to the value set in the EtherCAT Init block.

4. Select a Signal Name variable, here Term 3 (EL4002).AO Outputs Channel 1.Analog output.

5. Observe the value in seconds of parameter Sample Time.

   

6. Click OK.

Execute steps 2–6 for the EtherCAT PDO Transmit block labeled EtherCAT PDO Transmit 1.

Update Async SDO Block Variables by Using Complete Access Mode

The EtherCAT Async SDO Upload block and EtherCAT Async SDO Download block have a parameter that selects between single register access and complete access. This complete access mode provides a convenient method to apply the information that you get from the ESI file, using the information to programmatically populate the number of bytes in the data to read. This example shows approaches to get that information by inspecting the ESI file.

• The EtherCAT Async SDO Upload (read) block outputs a vector of byte data to be parsed with an unpack block.

• The EtherCAT Async SDO Download (write) block receives a vector of byte data produced by a pack block.

This example uses the Beckhoff EL3102 AI (Analog Input) device and shows how to obtain the information from the ESI file to produce the correct configuration for the unpack and pack blocks that are needed. The example uses index 0x8000, which has a set of different variables with varying sizes. This one describes configuration options for an AI channel on the board.

This device has a set of subindexed variables on index 0x8000 (channel 1) and 0x8010 (channel 2) where each of these has subindex values up to 0x18 (24 decimal) for AI configuration settings. Not all subindex values in the range [0,0x18] are available. This information is available in the Beckhoff documentation on their website. The documentation describes what each parameter does on the device, but the documentation does not have exact bit location information. Views from the Beckhoff web site for the EL3102 shows the information.

There are 17 subindexes in the range. When counting the number of bytes, a BOOLEAN is 1 bit and BIT3 is 3 bits with 16 and 32 bit ints as the usual sizes. This listing on the Beckhoff web site does not give the exact bit layout. Bit packing into bytes is not always obvious. In this example, there are 11 bits mentioned, one 3 bit plus 8 boolean, which requires 2 bytes. The information on this data sheet does not specify which bits are in each of the 2 bytes or specify the bit offsets.

Using either TwinCAT or ECEngineer to look at the CoE dictionary does not provide the exact bit layout.

The ESI file contains a full bit level description of 0x8000 and its subindexes, showing exactly where the single bit boolean variables are located in the data. The file also provides the full bit size of the set. The ESI files for devices that TwinCAT recognizes are kept in a directory in the TwinCAT install directory. With ECEngineer, the full set of ESI files it recognizes when shipped is not included, but is processed into the tool by an install process. Each device manufacturer is required to define ESI file content for their devices. If necessary, ESI files can be obtained directly from the device manufacturer.

The ESI file defines this as a data type, DT8000 for 0x8000 in the EL3102 device. The bit size is 160 bits, which is 20 bytes. This 20 byte value needs to be entered into either the EtherCAT Async SDO Upload block or EtherCAT Async SDO Download block as the array size.

While there is a place in TwinCAT to check a box that says to enable complete access, that appears to only be necessary for TwinCAT to use complete access. Using the Acontis code to get complete access works even if the checkbox is not selected in TwinCAT before exporting the ENI file. No special configuration is needed to use complete access CoE when generating an ENI file. This checkbox can be ignored when creating an ENI file for Simulink^® Real-Time™.

The next image is the EL31xx.xml ESI file. This one EtherCAT SubDevice Information file contains descriptions of over 100 different devices from Beckhoff in the EL31xx group of A/D converters. In a default install of TwinCAT 3.1, the file is found at C:\TwinCAT\3.1\Config\Io\EtherCAT\El31xx.xml.

If you use a tool such as XML Notepad, you can look through the ESI file with a tree view where you can open sections you’re interested in. Using XML Notepad, you find the devices that this ESI file refers to at EtherCATInfo + Descriptions + Devices. Next, you need to open the device nodes and look at the name in each. After finding the subordinate device with name EL3102, navigate to the Device > Profile > Dictionary > DataTypes entries where you find the types that are used with this device.

To find the datatype that describes the layout for the subindexes under 0x8000, you need to open the datatypes and look for DT8000 (DataType 8000). This datatype is a bit level description of all subindexes under 0x8000 as an example. The EL3102 has 39 different datatypes to search through. The non-structure like datatypes are given first and then the structure like datatypes are at the end numerically sorted by the number in DT<num>. For the EL3102, DT8000 is 6 before the end of the list. Not all manufacturers will name their data types the same way that Beckhoff does here for their devices.

The image shows that DT8000 has a bit size of 160 bits which is 160/8 = 20 bytes long. The subitems each describe one subindex bit length and starting bit. The one slight exception is that subindex 0 always contains the largest subindex that this item contains. If read as a single CoE read request, that value is read as a byte. If read as part of complete access, that first element is a uint8 followed by a padding byte that is zero, that’s the same as the first entry being a 16 bit integer.

When you read through the subitems for DT8000, you see that not all subindex numbers are used. When determining how to unpack the block of bytes that are returned with a complete access read, there may be unused bytes to force alignment of 16 bit integers to 16 bit boundaries. A 32 bit int appears to be able to be at any 16 bit boundary.

Data is packed using little endian byte ordering. The example above for the max subindex unpacks the second byte as the high order 8 bits of the 16 bit integer, with the first byte being the low order 8 bits.

When unpacking bits for Boolean and short fixed point bitfields, bit 0 of a byte is the low order bit. In the ESI file, the starting bit offset can be found by computing the remainder mod 8 of the bit offset.

The next image shows that subitem 21, Filter settings, has a data type of its own, DT0801EN16 which is defined as an enum in another datatype entry. Those values define the different filter bandwidths that the A/D can be set to use although the actual cutoff frequencies are given in the data sheet, not here in the ESI file. Those values are also listed in the Beckhoff man page for the EL3102.

Block parameters:

• Index — Edit box for main index, hex value as 0x8000, or converted to decimal as 32768.

• Access Mode — Complete Access

• Subindex — Edit box for first subindex to read or write. Only 0 or 1 are allowed for complete access. If 1 is chosen, then the value of index 0 is not returned.

• Data Type — uint8 or uint16

• Dimension — Edit box for the number of bytes to read or write. Get the bit size from the ESI file and divide by 8.

• Network Device Index — EtherCAT network ID

• Device Name — Pull down list of terminal device names

Most of the EtherCAT documentation shows indexes in hex. For this complete set for index 0x8000, the list of variable types in the pack or unpack block is:

{ ‘uint16’, ‘uint8’, ‘uint8’, ‘int16’, ‘int32’, ‘int16’, ‘int16’, ‘uint16’, ‘int16’, ‘int16’ }

To unpack the bits from both of the uint8 entries an additional bit unpack or bit pack block is needed for each one.

The unpack block also needs a cell array listing the vector dimension of each. In this case, this vector works:

{[1], [1], [1], [1], [1], [1], [1], [1], [1], [1]}

Configure EtherCAT Model Configuration Parameters

Before beginning this procedure, you must have selected a valid ENI file in the EtherCAT Init block. For more information, see Fixed-Step Size Derivation.

To configure the configuration parameters for model slrt_ex_ethercat_beckhoff_aio:

1. Open model slrt_ex_ethercat_beckhoff_aio.

2. Calculate the greatest common divisor (GCD) of the Sample Time values for the EtherCAT tasks and for all source blocks in the model. In this case, the GCD is 0.010.

3. In the Simulink Editor, on the Real-Time tab, from the Prepare section, click Hardware Settings. Select Configuration Parameters > Solver.

4. Set the Type parameter to Fixed-step and Fixed-step size (fundamental sample time) to one of the following:

   • An integral divisor of the GCD value, in seconds.

   • auto, if all other source blocks in the model have defined sample times.

   In this case, set the parameter to 0.010.

   

5. Click OK.

The next tasks are building, downloading, and executing the EtherCAT main device node model.

Modeling EtherCAT Networks