EtherCAT Master

This document describes the procedure of working with EtherCAT Master in RT-LAB versions 10.7 (starting from 10.7.2) and 11.1.1 or later (2019+). The present EtherCAT driver is based on the SOEM library (Simple Open EtherCAT Master).
This driver requires two working Ethernet ports on the simulator on which it will be run. One port is needed for the communication with the host (the Windows PC where RT-LAB is running) while the other port is needed to connect to the network of EtherCAT slaves.

Supported Features

Files Needed by the Driver

There are two configuration files needed by the driver. One is meant to configure the driver itself and its method of functioning and the other is meant to configure how the data will be exchanged between it and the Simulink model. These two files must be transferred to the simulator when the Simulink model is loading. In order to achieve that, the files need to be added in the model's "Files" list in RT-LAB as shown below:

These two files are described in more detail in the two following sections.

Configuring the Driver

The configuration of the driver along with any extra information about some of the slaves in the network is presented in the "*_cfg.opal" file (seen as "ethercat_master_cfg.opal" file in the image above). We recommend using the configuration from the example models as a working basis.

An example of the file used for configuration when an Elmo drive is present is given below:

OPAL-1.0 Object
EtherCAT::Master::Configuration {
   waitSlavesOP = 1
   launchWatchdog = 0
   networkInterface = eth1
   customInitialization {
      item {
         key = 1
         value {
            forceGenericDriver=0
            options {
               Profile:Multimode
               InterpolationTime:10
               ResetCounter:1  
            }
         }
      }
   }
}

Here is an example of the configuration when Beckhoff's FC1100 card is present in the slaves chain:

OPAL-1.0 Object
EtherCAT::Master::Configuration {
   waitSlavesOP = 1
   launchWatchdog = 1
   networkInterface = eth1
   customInitialization {
      item {
         key = 1
         value {
            pdoSetup {
               item {
                  name=BIT_in
                  type=BIT
                  direction=SLAVE_TO_MASTER
                  byteOffset=0
                  bitOffset=2
               }
               item {
                  name=BYTE_out
                  type=BYTE
                  direction=MASTER_TO_SLAVE
                  byteOffset=1
               }
            }
         }
      }
   }
}

The description of each of the options is as follows:

Each item in the customInitialization list is the configuration of the EtherCAT slave found at the address denoted by the item's key.

The description of each of its fields is as follows:

customInitialization {
   item {
      key = 1
      value {
         forceGenericDriver=0
         options {
            Profile:Multimode
            InitialValue:0
            InterpolationTime:10
            ResetCounter:1 
         }
      }
   }
}

Formatting the commands to be sent when transitioning between states:

• write unsigned integer:
  write('X', 'Y', U'Z', 'T'), where 'X' represents the index, 'Y' represents the subindex, 'Z' represents the size in bits (value must be divisible by 8 to be byte-aligned) and 'T' represents the value to write. 'X', 'Y' must be hexadecimal values while 'Z' has to be a valid unsigned integer representable on 16 bits; 'T' must be a valid unsigned integer representable on 64 bits.
  Example: write(A, 0, U16, 16)
  
  
• write signed integer:
  write('X', 'Y', I'Z', 'T'), where 'X' represents the index, 'Y' represents the subindex, 'Z' represents the size in bits (value must be divisible by 8 to be byte-aligned) and 'T' represents the value to write. 'X', 'Y' must be hexadecimal values while 'Z' has to be a valid unsigned integer representable on 16 bits; 'T' must be a valid signed integer representable on 64 bits.
  Example: write(1, B, I8, -10)
  
  

• read values:
  read('X', 'Y', 'Z', 'T'), where 'X' represents the index, 'Y' represents the subindex, 'Z' represents the type and 'T' represents the name that will be given to the value read. 'X', 'Y' must be hexadecimal values. 'Z' has to be a string representing a data type. 'T' is a string that will be used to create a connection point with the Simulink model. More on connections in the next section.
  Choices for the type:

  String	Description
  "U8"	unsigned integer on 8 bits
  "I8"	signed integer on 8 bits
  "U16"	unsigned integer on 16 bits
  "I16"	signed integer on 16 bits
  "U32"	unsigned integer on 32 bits
  "I32"	signed integer on 32 bits
  "U64"	unsigned integer on 64 bits
  "S64"	signed integer on 64 bits

  
  Example: read(2, 1, I8, myValue)

Making Connections Between the Model and the Driver

The driver can be seen as a middle-man between the signals in the Simulink model and the EtherCAT slaves connected to the simulator. In the model, the data that the user wishes to send to the EtherCAT slaves is connected to blocks called OpOutput. Similarly, the data received from the slaves is connected to blocks named OpInput. The driver will take the data from the OpOutput blocks and send it to the slaves; it will also convey data received from the slaves back to the model through the OpInput blocks. In order to be able to do that, the user needs to bind the Simulink signals (represented as OpInput and OpOutput blocks) to the driver signals. This is done by using a text file named connections.opal which needs to be transferred to the simulator at the same time as the configuration file (as seen in the image above).

Below is an example of a connections.opal file:

OPAL-1.0 Object
List {
  item {
    configFile=ethercat_master_cfg.opal
    id {
      EtherCATMaster
    }
    inputs {
      item {
        dataInExchanger=1/analogIn0
        dataInProcess=OpInput:AnalogIn0
      }
    }
    outputs {
      item {
        dataInExchanger=2/analogOut0
        dataInProcess=OpOutput:AnalogOut0
      }
    }
  }
}

In more detail, "dataInExchanger" represents the signals of the driver, whereas "dataInProcess" represents the signals in the Simulink model.

The number just after "dataInExchanger=" represents the position of slave in the EtherCAT chain topology. The value 0 is reserved for the EtherCAT master, therefore it is never used. Numbering starts at 1, for the first slave connected to the simulator and it increments for each slave connected in the network (following a daisy chain topology). If ever in doubt, the user can activate the verbose mode of the driver, re-load the simulation at which point the entire slave network topology will be outputted in RT-LAB's display. Each slave's information will be displayed, along with its index (address) within the EtherCAT network. This is the index that needs to be used in the connections.opal file.
The name that follows the index in the "dataInExchanger" item is characteristic to the type of the module at that position in the network. For a full description of what names are possible, please consult the table in the following section.
For the "dataInProcess" item, the names that come after "OpInput:" and "OpOutput:" refer to the names of OpInput and OpOutput Simulink blocks. Therefore, it is important to make sure that those names are unique in the model.

List of Supported Modules and How to Connect to Them

The modules listed in the table below have been tested and proved to be compatible with the present EtherCAT master driver. Support of more modules is possible. Please contact Opal-RT Technologies for more information.
The description of supported EtherCAT slave modules and their possible connection points is as follows:

As mentioned in the configuration file section, the read command that the user can send between slave states also creates a connection point between the model and the driver.
The name of this connection point is the name given in the command. Giving again the example above, the command read(2, 1, I8, myValue), the name of the connection point will be "myValue". Therefore, an example of the "dataInExchanger" is the following: "dataInExchanger=3/myValue".

Limitations

The current version of the EtherCAT master driver has the following limitations:

• On 64bit platforms, enabling the XHP mode is not possible; if the driver is part of a model that requires XHP enabled, it is advised to group the OpInputs/OpOutputs used by EtherCAT master in a separate subsystem that will operate with XHP = off
• The network interface chosen for the EtherCAT communication must be 100Mb/s