8 minute read

⚠ THIS IS DEPRICATED! ⚠

After connecting and configuring your slave devices it is time to configure and link the slaves to Motorcortex. Configuring EtherCAT slaves requires a number of steps:

Scan the EtherCAT bus and generate a topology file. the topology file is used by Motorcortex to create the correct format of EtherCAT messages, such that all slave devices and their data objects can be addressed.
Configure each input or output for each device and link it to the Motorcortex application.
Create special configurations for some more complex devices, such a servo-controllers or configurable i/o cards (This step is not always required).

Motorcortex and EtherCAT basics

Before linking and configuring the Ethercat slaves it is necessary to know some basics of how Ethercat works with motorcortex. In Motorcortex there are two files that have to be configured when adding new Ethercat devices:

topology.xml
master.xml

Creating the topology.xml

The topology.xml contains information about which devices are in a network and how they are connected. Each slave device will receive an ID that is determined by its place in the topology. With this ID the application can address the device and send information to an receive information from the device.

Connect all Ethercat devices that you want to link and configure.
Login to your controller using ssh (having trouble login in check out Remote access to the Motorcortex Computer).
```
 ssh admin@192.168.2.100
```

Note: the standard password on a motorcortex controller is vectioneer.

Go to the location of the topology.xml file
```
 cd /etc/motorcortex/config/io
```
Check if your Ethercat devices are connected using the following command.
```
 ethercat slaves
```

This command should output the connected EtherCAT slaves, for instance:

	0  0:0  OP     +  EK1914, 2 K. Safety Eingang/Ausgang 24V,  TwinSAFE
	1  0:1  OP     +  EL6910, TwinSAFE PLC
	2  0:2  PREOP  +  EK1110 EtherCAT-Verl�ngerung
	3  0:3  OP     +  EP2316-0003 8 K. Dig. Ein, 10�s, 8 K. Dig. Aus 24V, 0,5A, Diagn

Next the topology.xml has to be updated. but before doing this it is wise to create a backup topology file in case things go wrong. Run the following command to create a copy of the topology file with a different name.
```
 cp topology.xml topology_backup.xml
```
Now the topology.xml can be updated using the following command.

⚠ Careless changing of topology.xml can result that the whole application will not work anymore. Therefore always first make a backup before changes are made.

	sudo ethercat xml > topology.xml

The topology file is now updated to the new configuration of all connected Ethercat devices.

Creating the master.xml basics

The master.xml is used by Motorcortex to generate the EtherCAT folder in the Parameter Tree (more on the parameter tree will follow later in this chapter). Creating the master.xml is a complicated procedure which needs knowlegde about ethercat and rules creating this master.xml. Motorcoterx Link makes this procces a lot easyer and quicker linking and configuring your Ethercat devices. For this example Motorcoterx Link won’t be used. Therefore this chapter will provide the basic knowlege needed to create the master.xml file.

Motorcortex Parameter Tree

In the master.xml the user can define which parameter types are shown in the Parameter tree. The Parameter Tree contains a snapshot of all the inputs, outputs and internal data of the control objects at the current time.

Motorcortex has a tree structure in which the data objects are published. Each task or objects inside a task can create their own subtree (folder). Objects can be nested. In a general control application there are usually a “Logic”, “Control” and also “EtherCAT” folders that represent the data of different tasks. In the EtherCAT folder you will find the configured EtherCAT slave devices.

The names of the folders are configurable and the application developer can change these, but it is good practice to stick to some convention.

Inside the folders the data of the associated object is contained. Motorcortex currently supports the following datatypes: boolean, integer, double or binary (e.g. a c-struct). Also arrays of the same datatype are supported. Array elements start at index 0 (zero).

To view the tree structure of your Motorcortex application you can use Motorcoterx Desk.

Parameter Types in Motorcortex:

This subsection shortly describes how the different parameter types can be used in combination with EtherCAT.

The Motorcortex structure has the following parameter types:

Input: In this parameter type a value can be written. A typical use is an sensor. In the EtherCAT configuration file the sensor value will be linked to an input. However it is possible to also write this value an input into EtherCAT output. An input is typically linked to a PDO. In Motorcortex Desk an input is depicted as:

Output: this parameter type is read-only. A typical use is a set point value. The value is calculated within the Motorcortex and shall not be overwritten. Therefore this value can only be linked to an EtherCAT output, but never to an EtherCAT input. An output is typically linked to a PDO. In Motorcortex Desk an output is depicted as:

Parameter: This is parameter type that is used to configure the system. Typical uses are motor parameters and system constants.Parameters are retrieved from the parameter list during start-up. If the user changes a value and wants to use in the future, he has to save the list before rebooting/switching off the controller. A parameter can be read and written. However due to its character, it will be used mostly in combination with SDOs. In Motorcortex Desk an parameter is depicted as:

Persistent: these are values that contain process data that is continuously updated and will be retained through application restarts. Typical applications are running ours or amount of produced products. In Motorcortex Desk an persistent is depicted as:

Creating the master.xml

The standard master.xml on a Generic control cabinet will look like this.

TBD

The master.xml has to start with

	<?xml version="1.0"?>
	<Master Type="EtherCAT" Device="0" Name="Ethercat">

and end with

	</Master>

In between these lines you will have to configure the folowing elements:

Domains
Devices
SDO/PDO/MAILBOX

EtherCAT Domains

It is possible to divide EtherCAT IOs in separate domains.

A Domain is an group of EtherCAT slaves (physical cluster of EtherCAT modules). An advantage different domains, is that every domain is separate and can (if configured properly) be disconnected and reconnected (hot-plug), while other devices in other domains that remain connected are still operational. Beside hot-plug capability domains also keep your structure more clear.

to open a domain start with:

	<Domain File="topology.xml" Name="Domain Name">

and end with:

    </Domain>

EtherCAT Devices

Devices can be added inside the domains

To add a device start with:

	<Device Id="#" Name="Device name" MapAll="0">

The Id="#" is the position of the ethercat device in the bus and can be found running the following command (The slave Id' number is in front of every device.).

	ethercat slaves

The Name="Device name" can be a custom name you give to the device.

The MapAll="0" is a function to automatically configure all mandatory SDO and PDO in the device. It can be turned on by setting the value to "1". It is not guaranteed that this function will provide a usable outcome in the Parameter Tree and is vendor dependant.

end a device with:

    </Device>

EtherCAT PDO/SDO/Mailbox

The information sent and received over the EtherCAT network consists of data packages of the following types: PDOs and SDOs.

PDO (Process Data Object).
This is cyclic data that is send or received during every EtherCAT broadcast. Examples are: status of switches and lights, actuator setpoints and actual values.

SDO (Service Data Object).
This is in data that is normally only send during start-up or during an event. Examples are: motor parameters, sensor configuration and (drive) error information.

Mailbox.
The configuration of the SDOs on an EtherCAT module can be send via a mailbox file. There are two file types: CANopen over EtherCAT (CoE) and Sercos over EtherCAT (SoE, sometimes also called Servo over EtherCAT). The structure of the file is very similar for both types. The EtherCAT module manufacturer decides which type is used.

Configurating SDO/PDO is dificult and vendor documentation in form of a object dictionary or esi.xml is needed to determine what name connects to what PDO/SDO. Some PDO/SDO are mandatory, these must be configured.

To open a pdo start with:

	<Pdo Index="####" Entry="####:##" Group="Group Name" Name="PDO Name" DataType="Datatype">

The Index+"####" of a PDO can be found in vendor documentation or esi.xml.

The Entry="####:##" of a PDO can be found in vendor documentation or esi.xml.

The Group="Group Name" makes it possible to create a group within the device with a custom name.

The Name="PDO Name" makes it possible to create a custom name for your PDO.

The DataType="Datatype"of a PDO can be found in vendor documentation or esi.xml.

end a pdo with:

     </Pdo>

To open a sdo start with:

	<Sdo Index="####" Entry="####:##" Group="Group Name" Name="SDO Name" DataType="Datatype">

The Index+"####" of a SDO can be found in vendor documentation or esi.xml.

The Entry="####:##" of a SDO can be found in vendor documentation or esi.xml.

The Group="Group Name" makes it possible to create a group within the device with a custom name.

The Name="SDO Name" makes it possible to create a custom name for your SDO.

The DataType="Datatype"of a SDO can be found in vendor documentation or esi.xml.

end a SDO with:

     </Sdo>

Master.xml file example

Below is a example of a master.xml file of the generic control cabinet.

Parameter Tree

to check the result:

Save the file

/etc/Motorcortex/config/io/master.xml,

restart Motorcortex

sudo/etc/init.d/Motorcortex restart