20 minute read

EtherCAT slaves configuration

Introduction

MOTORCORTEX is a Hard-Realtime Control System with an integrated high-speed communication system. It is especially designed to allow easy and high-performance interaction with the control system from any client platform and with many supported programming languages.

This document will explain how to link EtherCAT slave devices to a MOTORCORTEX application.

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

MOTORCORTEX

In a MOTORCORTEX application all control objects are organized in a tree structure; 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 use the MOTORCORTEX-Desk tool.

EtherCAT Domains/Groups

It is possible to divide the EtherCAT IOs in separate domains.

A Domain is an group of EtherCAT slaves (physical cluster of EtherCAT modules). Each domain has a dedicated XML file. 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.

Per domain, groups (and subgroups) can be created. Typically each EtherCAT slave is assigned to a name and/or group. In that case the slave will appear in MOTORCORTEX-Desk as a dedicated folder.
Optionally it is possible to create subfolders for data objects (e.g. if the user prefers to separate inputs and outputs). This is all for a clear structure, functionally all data objects from one domain can also be dumped together.

Sending Information over EtherCAT

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

PDO stands for 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 stands for 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.

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.

There are also other types of information that can be send over EtherCAT (e.g. File over EtherCAT (FoE), EtherNet over EtherCAT (EoE)), but this is out of scope of this document that will only focus on adding EtherCAT slaves to the MOTORCORTEX software.

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:

Configuring EtherCAT Topology

Introduction

The EtherCAT Topology 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.

In an EtherCAT network a single message is sent that passes by all devices and is returned back to the Master. Each device takes its own information from this message and inserts data back into the message as it passes. The Master needs to know the topology before it can build the correct message, containing data for all the slaves.

MOTORCORTEX is capable of using different EtherCAT Master stacks. By default the EtherLab (https://etherlab.org/) Master is used. The tools to scan the EtherCAT topology are provided as part of the EtherLab driver. MOTORCORTEX is compatible with the topology files generated by the EtherLab tools.

Scanning available slaves

Connect all slaves to the EtherCAT Network. Also the slaves that you want to hot-plug later.

Log in to the controller (via SSH) and type the following (on some systems it may be required to use sudo to execute the command with root privileges):

ethercat slaves

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

0 0:0 PREOP + EK1100 EtherCAT Coupler (2A E-Bus)
1 0:1 PREOP + EL1018 8K. Dig. Eingang 24V, 10�s
2 0:2 PREOP + EL2008 8K. Dig. Ausgang 24V, 0.5A
3 0:3 PREOP + EL3104 4K. Ana. Eingang +/-10V Diff.
4 0:4 PREOP + EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5 0:5 PREOP + EL3174 4K. Ana. Eingang +/-10V Diff., +/-20mA SingleEnded, 16bit

Above you see 6 slaves with ID’s 0 through 5 being detected. EtherCAT starts numbering of slaves at 0.

Check if all slaves are present. If slaves are missing, check the EtherCAT connection and if the slave is powered.

Create/update EtherCAT Topology

First make a copy of the current topology (via filezilla or via the terminal, see below)

cd /etc/motorcortex/config/io
cp topology.xml topology_backup_YYYY_MM_DD.xml

To write the new topology type the following in the terminal.

sudo ethercat xml > topology.xml

The exact content of the `topology.xml` file will not be discussed in this document, since it is complex and not needed for this document. If the user is curious, he is encouraged to open the file in a text editor and view the content. The file should not be modified by hand.

⚠ 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.

Linking EtherCAT Slaves to MOTORCORTEX signals

In this chapter the inputs and outputs of the EtherCAT devices will be linked to MOTORCORTEX parameters. These links are located in a PDO file (or more PDO files in case of multiple domains).

Creating slave configurations and linking signals to MOTORCORTEX (pdo.xml)

With the Slaves connected and the topology.xml file generated and installed, follow the following procedure to create a slave configuration:

Create a file called /etc/motorcortex/config/io/pdo.xml and copy the text below into it. The filename is determined in the MOTORCORTEX Application and depends on the programmer’s choice. This is the most basic version of a slave configuration file, where all inputs and outputs from all (most) slaves are mapped to the MOTORCORTEX application. The file first defines a Domain and links a topology file to this domain. topology.xml is the file generated in Scanning available slaves. The option MapAll=1 maps all the inputs and outputs of slave devices and generates default names. Devices that do not have simple inputs or outputs may not be mapped with MapAll.

<?xml version="1.0"?>
<Domain File="topology.xml" MapAll="1"></Domain>

Restart the MOTORCORTEX server application (sudo may require the user’s password)

sudo /etc/init.d/motorcortex restart

Go to MOTORCORTEX-Desk via your browser and log in:

http://192.168.2.100:8000
Server address: 192.168.2.100
Username: admin
Password: vectioneer

Go to the folder root/EtherCAT, here you will find subfolders of the EtherCAT devices.
The order of the devices is alphabetical.
The slave ID is the last part of the device name.

Adding information to slaves

As a reminder of which slaves are present it is handy to copy the slave list that was shown as part of the procedure in Scanning available slaves in your pdo.xml file. This way you can quickly look up which devices are present and what their ID is.

<!--
0 0:0 PREOP + EK1100 EtherCAT Coupler (2A E-Bus)
1 0:1 PREOP + EL1018 8K. Dig. Eingang 24V, 10�s
2 0:2 PREOP + EL2008 8K. Dig. Ausgang 24V, 0.5A
3 0:3 PREOP + EL3104 4K. Ana. Eingang +/-10V Diff.
4 0:4 PREOP + EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5 0:5 PREOP + EL3174 4K. Ana. Eingang +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

In the pdo.xml file, all devices can have their own section with configuration parameters. The devices are identified with a <Device Id="X"> tag, where the Id is the EtherCAT ID that refers to the device. Each device can be given a Group and a Name property. The Group specifies a subfolder when the device is created in MOTORCORTEX, and is optional. If the Group is omitted, the device will be created in the current Domain.

<?xml version="1.0"?>
<!--
0  0:0  PREOP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  PREOP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  PREOP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  PREOP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

<Domain File="topology.xml">
	<!--device 0, EK1100-->
	<Device Id="1" Group="Group1" Name="01-EL1018-01" MapAll="1">
	</Device>
	<Device Id="2" Group="Group1" Name="02-EL2008-01" MapAll="1">
	</Device>
	<Device Id="3" Group="Group2" Name="03-EL3104-01" MapAll="1">
	</Device>
	<Device Id="4" Group="Group2" Name="04-EL4134-01" MapAll="1">
	</Device>
	<Device Id="5" Group="Group2" Name="05-EL3174-01" MapAll="1">
	</Device>
</Domain>

to check the result:

Save the file

/etc/MOTORCORTEX/config/io/pdo.xml,

restart MOTORCORTEX

sudo/etc/init.d/motorcortex restart

See if you can already see the individual inputs and outputs.

Linking a digital input to a MOTORCORTEX parameter

Normally each Slave device has a number of Inputs or Outputs. These signals can be linked to a signal in the MOTORCORTEX Parameter Tree. EtherCAT inputs write data to the Parameter Tree and can only be linked to parameters that allow write access (Inputs and Parameters); it is not possible to link an EtherCAT input to an Output signal. Check the MOTORCORTEX-Desk to see what the type of the parameter is you would like to link to.

Consider the example pdo.xml below.

<!--
<?xml version="1.0"?>
<!--
0  0:0  PREOP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  PREOP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  PREOP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  PREOP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
	<Pdo Entry="6000:01" Name="input_01">
	   <Link>root/Control/dummyBool</Link>
	</Pdo>
    </Device>

    <Device Id="2" Name="02-EL2008-01">
    </Device>

    <Device Id="3" Name="03-EL3104-01">
    </Device>

    <Device Id="4" Name="04-EL4134-01">
    </Device>

    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

In this example, the EtherCAT Slave with ID 1 is a digital input module EL1018, that has 8 digital inputs. The input is a Process Data Object (PDO) and can be configured with the <Pdo> tag. The Entry property specifies where the PDO can be found on the device. The Entry consist of the index (hex) and subindex (two digits, leading zeros). The indices and sub-indices of the signals can be found in the documentation of the device provided by the manufacturer or can be derived from the contents of the topology.xml file.

In the topology.xml file the index and subindex for this particular type of device can be found in the <Entry> section of the device.

...
   	<Device>
		<Type ProductCode="#x03fa3052" RevisionNo="#x00120000">EL1018</Type>
		<Name><![CDATA[EL1018 8K. Dig. Eingang 24V, 10�s]]></Name>
		<Sm Enable="1" StartAddress="#x1000" ControlByte="#x0" DefaultSize="1" />
		<TxPdo Sm="0" Fixed="1" Mandatory="1">
			<Index>#x1a00</Index>
			<Name>Channel 1</Name>
			<Entry>
				<Index>#x6000</Index>
				<SubIndex>1</SubIndex>
				<BitLen>1</BitLen>
				<Name>Input</Name>
				<DataType>BOOL</DataType>
			</Entry>
		</TxPdo>
		<TxPdo Sm="0" Fixed="1" Mandatory="1">
			<Index>#x1a01</Index>
			<Name>Channel 2</Name>
...

In this case, the first input of this device is located at index 6000 and subindex 1. To set the index and subindex of the input we use the Entry property:

<Pdo Entry="6000:01" Name="input_01">

Using the name property, the input is named “input_01”. This name will be used when the device is added to the MOTORCORTEX Parameter Tree. In this case the input can be found in the tree: /root/EtherCAT/00-EL1018-01/input_01

To link a value to the MOTORCORTEX application use the <Link> tag. The path to link to can be found by opening the MOTORCORTEX-Desk and browsing to the appropriate value in the tree. How to create a MOTORCORTEX application see

!!TBD!! G0110-0200-01-MAN-[Developing Motorcortex Applications in C++ (Server)](#Developing Motorcortex Applications in C++ (Server)).

...
	<Device Id="1" Name="00-EL1018-01">
		<Pdo Entry="6000:01" Name="input_01">
			<Link>root/Control/dummyBool</Link>
		</Pdo>
	</Device>
...

to check the result:

Save the file

/etc/MOTORCORTEX/config/io/pdo.xml,

restart MOTORCORTEX

sudo/etc/init.d/motorcortex restart

If now the input is made high, the value the input is linked to (in this case root/Control/dummyBool) will go to 1.

Linking a digital output

It is also possible to place a boolean value in an output. EtherCAT outputs can be linked to MOTORCORTEX Inputs, Outputs and Parameters.

<?xml version="1.0"?>
<!--
...
-->
<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
	<Pdo Entry="6000:11" Name="input_01">
	   <Link>root/Control/dummyBool</Link>
	</Pdo>
    </Device>

    <Device Id="2" Name="02-EL2008-01">

	<Pdo Entry="7000:01" Name="output_01">
	   <Link Invert="1">root/Control/dummyBool</Link>
	</Pdo>

	<Pdo Entry="7010:01" Name="output_02">
	   <Link>root/Control/module_state</Link>
	</Pdo>

    </Device>

    <Device Id="3" Name="03-EL3104-01">
    </Device>

    <Device Id="4" Name="04-EL4134-01">
    </Device>

    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

Besides adding the dummyBool to the output, we also added Invert="1". This means when digital input 1 is 1/true, output 2 will be 0/false (and vice versa). Output 2 is selected by Entry="7010:01". This value already showed up when we used MapAll="1". For the correct entry, look in to the documentation of the EtherCAT slave, typically under the subheading input data or output data. Last to demonstrate that it is also possible to write an integer to a digital output, the state of the MOTORCORTEX Logic is written to output 3.

Analog inputs

Each analog device has it’s own measuring range and unit. This means that every device has its own conversion. Where for a PT100-temperature module as the EL3201, the temperature is passed through as a value x10 (thus 31.4°C is transmitted as 314), for many others it is a value of 2^x for the full range. The EL3104 for instance has a full range of -10..10V with 16 bits resolution. The EL3104 uses an UINT16 (unsigned integer) value to represent -10..10V, this means that 0 = -10V and 65536 = +10V. In the configuration file however we can map the UINT16 value to an INT16 value, which is signed. This means that now 0V = 0, 10V = 2¹⁵-1 (since we start at 0) and -10V is -2¹⁵.

<?xml version="1.0"?>
<!--
...
-->
<Domain File="topology.xml">
    <!--device 0, EK1100-->
    <Device Id="1" Name="01-EL1018-01">
	<Pdo Entry="6000:01" Name="input_01">
	   <DataType>INT16</DataType>
	   <Link>root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
	<Pdo Entry="7010:01" Name="input_02">
	   <DataType>INT16</DataType>
	   <Link Invert="1">root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
	<Pdo Entry="6020:11" Group="Analog Inputs" Name="analog_input_03">
	   <DataType>INT16</DataType>
	   <Link Divide="3276.8">root/Control/dummyDouble</Link>
	</Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
    </Device>
    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

The slave uses some datatype that is also specified in the topology.xml file. Using the <DataType> tag the datatype can be changed to a more convenient format. In general it is used to convert from unsigned integer values to signed integers. So the slave for instance uses UINT16 as a type, with values in the range 0..65536, using <DataType>INT16</DataType>, it can be converted to a INT16 with a range of -32768..32767. So the value of 0 corresponds to 0.00V for instance in a -10V..10V input card.

Above a -10…10V value will be read-in on slave 4 (id=3), input 4. Note the Divide="3276.8". This scales the ‑2¹⁵…2¹⁵-1 back to -10…10V. This is done to easy cross-check the incoming voltage in case of troubleshooting. Another item introduced over here is Group="Analog Inputs". Since this module has only analog inputs, the subgroup that is now created is rather useless, but in EtherCAT module that have multiple types of inputs and or outputs (like drives), it results in a organized structure that allows quicker navigation.

Note: it is good practice to first link the analog input of the sensor to an input double that has the measuring unit (in this case Volt).

Analog outputs

<?xml version="1.0"?>
<!--
...
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
	<Pdo Entry="6000:11" Name="input_01">
	   <DataType>INT16</DataType>
	   <Link>root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
	<Pdo Entry="7010:01" Name="input_02">
	   <DataType>INT16</DataType>
	   <Link Invert="1">root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
	<Pdo Entry="6020:11" Name="analog input 03">
	   <DataType>INT16</DataType>
	   <Link Divide="3276.8">root/Control/dummyDouble</Link>
	</Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
	<Pdo Entry="7030:01" Name="analog output 04">
	   <DataType>INT16</DataType>
	   <Link Gain="3276.8" GainOffset="3276.8">root/Control/dummyDouble</Link>
	</Pdo>
    </Device>
    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

Above the value of root/Control/dummyDouble is used to write to an analog output. The value of ‑10…10V is scaled back to the appropriate INT16 value by using Gain="3276.8", but on top of that the voltage is increased with 1V by using GainOffset="3276.8".

Start-up files and SDOs

Some EtherCAT devices are configurable through Service Data Objects (SDO’s); depending on how they are configured, they have different behavior. For instance the Beckhoff EL3174 Analog input module can be configured for different input types, e.g. current or voltage.

These devices can be configured by adding a <MailBox> tag, that points to a startup file that contains the desired configuration of the device. These setting are applied when the device is started.

The format of the startup files is determined by the type of slave device. Some devices use CAN over EtherCAT (CoE) for configuration, others use SERCOS over EtherCAT (SoE).

<?xml version="1.0"?>
<!--
...
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
	<Pdo Entry="6000:01" Name="input_01">
	   <DataType>INT16</DataType>
	   <Link>root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
	<Pdo Entry="7010:01" Name="input_02">
	   <DataType>INT16</DataType>
	   <Link Invert="1">root/Control/dummyBool</Link>
	</Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
	<Pdo Entry="6020:11" Name="analog input 03">
	   <DataType>INT16</DataType>
	   <Link Divide="3276.7">root/Control/dummyDouble</Link>
	</Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
	<Pdo Entry="7030:01" Name="analog output 04">
	   <DataType>INT16</DataType>
	   <Link Gain="3276.7" Gainoffset="1">root/Control/dummyDouble</Link>
	</Pdo>
    </Device>
    <Device Id="5" Name="05-EL3174-01">
	<Mailbox File="05-EL3174-01_startup.xml"/>
	<Pdo Entry="6000:11" Name="analog input 01">
	   <DataType>INT16</DataType>
	   <Link Divide="3051.8" Index="0">root/Control/dummyDoubleArray</Link>
	</Pdo>
    </Device>
</Domain>

Above you can see that Divide="3051.8" is smaller, due to the larger measuring range of the EL3174. Also is the value placed into the first index (Index="0") of the array dummyDoubleArray.

To create the startup file, create a file in /etc/MOTORCORTEX/config/io called 05-EL3174-01_startup.xml.

<?xml version="1.0" encoding="ISO-8859-1"?>
<EtherCATMailbox>
    <CoE>
	<InitCmds>

	    <InitCmd>
	        <Transition>PS</Transition>
	        <Comment><![CDATA[Input Type]]></Comment>
	        <Timeout>0</Timeout>
	        <Ccs>1</Ccs>
	        <Index>32781</Index>
	        <SubIndex>17</SubIndex>
	        <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
	    </InitCmd>

	    <InitCmd>
	        <Transition>PS</Transition>
	        <Comment><![CDATA[Input Type]]></Comment>
	        <Timeout>0</Timeout>
	        <Ccs>1</Ccs>
	        <Index>32797</Index>
	        <SubIndex>17</SubIndex>
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->

	        <Data>1300</Data> <!--   4..+20mA -->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
	    </InitCmd>

	    <InitCmd>
	        <Transition>PS</Transition>
	        <Comment><![CDATA[Input Type]]></Comment>
	        <Timeout>0</Timeout>
	        <Ccs>1</Ccs>
	        <Index>32813</Index>
	        <SubIndex>17</SubIndex>
	        <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
	    </InitCmd>

	    <InitCmd>
	        <Transition>PS</Transition>
	        <Comment><![CDATA[Input Type]]></Comment>
	        <Timeout>0</Timeout>
	        <Ccs>1</Ccs>
	        <Index>32829</Index>
	        <SubIndex>17</SubIndex>
	        <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->

	    </InitCmd>

	</InitCmds>
    </CoE>
</EtherCATMailbox>

Mapping an SDO to the MOTORCORTEX Tree

It is also possible to map SDO’s to the MOTORCORTEX Parameter Tree, so they can be updated at runtime. For this to work, the SDO’s have to be configured using the <sdo> tag, so they are included in the EtherCAT communication. This is done by adding them to the device configuration in the pdo.xml.

<?xml version="1.0"?>
<!--\\
...
-->
<!--
<Domain File="topology.xml">
	<!--device 0, EK1100-->
<Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
       <DataType>INT16</DataType>
       <Link>root/Control/dummyBool</Link>
    </Pdo>
</Device>
<Device Id="2" Name="02-EL2008-01">
    <Pdo Entry="7010:01" Name="output_02">
       <DataType>INT16</DataType>
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>
</Device>
<Device Id="3" Name="03-EL3104-01">
    <Pdo Entry="6020:11" Name="analog input 03">
       <DataType>INT16</DataType>
       <Link Divide="3276.7">root/Control/dummyDouble</Link>
    </Pdo>
</Device>
<Device Id="4" Name="04-EL4134-01">
    <Pdo Entry="7030:01" Name="analog output 04">
       <DataType>INT16</DataType>
       <Link Gain="3276.7" Gainoffset="1">root/Control/dummyDouble</Link>
    </Pdo>
</Device>
<Device Id="5" Name="05-EL3174-01">
    <Mailbox File="05-EL3174-01_startup"/>
    <Pdo Entry="6000:11" Name="analog input 01">
       <DataType>INT16</DataType>
       <Link Divide="3051.8" Index="0">root/Control/dummyDoubleArray</Link>
    </Pdo>
    <Pdo Entry="6000:7" Name="Fault channel 1">
    </Pdo>
    <Pdo Entry="6010:7" Name="Fault channel 2">
    </Pdo>
    <Pdo Entry="6020:7" Name="Fault channel 3">
    </Pdo>
    <Pdo Entry="6030:7" Name="Fault channel 4">
    </Pdo>
    <Sdo Entry="800d:11" Size="2" Group="SDOs" Name="Input Type channel 1">          
       <DataType>INT16</DataType>
    </Sdo>
    <Sdo Entry="801d:11" Size="2" Group="SDOs" Name="Input Type channel 2"> 
       <DataType>INT16</DataType>
    </Sdo>

Now that the SDO is mapped it can be changed by using for instance the MOTORCOREX-Desk. IN case of the EL3174 analog input card, entering a value of 20 (decimal, it corresponds to hex 14), the module will use the 4…20mA input range. Changing the value to 2 (which is also hex 2), will change the input back to -10…10V. The values correspond to the content of the mailbox file. In the example configuration above the EL3174’s fault signals (PDO’s) are also mapped to MOTORCORTEX. When the channel is now configured for 4..20mA and no cable is connected to the input the “Fault channel 1” signal will become high (because when no cable is connected the input signal will be out of the sensor range). Also a red led will turn on the input module, indicating the fault.

Note that SDOs are still not updated cyclically. They only are updated via a mailbox command. MOTORCORTEX sends a mailbox update request package automatically when a SDO value is changed through the Parameter Tree. A read action of all SDOs can also be triggered by triggering the read_sdos input of the Domain in the Parameter Tree (setting it to a value of “1”). If this is done through the MOTORCORTEX-Desk, setting the read_sdos to 1 will not be visible; the server application immediately resets it back to “0” when the request is received.

If the recover_sdo parameter is set to 1, an SDO read request is automatically sent during startup and recovery of a lost connection.

Advanced EtherCAT configuration

EtherCAT Domain Errors

The MOTORCORTEX Parameter Tree also shows if a Domain has an error. The error output becomes true if there is an error. And error can be cause by a domain being disconnected or a problem with a slave in this domain.

There are two parameters that can be configured to change the behavior of the error output:

error_delay_sec; time is seconds before the error output becomes true (1) after an error is detected
no_error_delay_sec; time in seconds the error output becomes false (0) after the error is resolved.

EtherCAT slave Status

An EtherCAT slave module has different states. Every state allows different functions to be accessible or executable. The EtherCAT master can switch the slaves to different states.

The following EtherCAT Slave States are defined:

Init (INIT)
Pre-Operational (PREOP)
Safe-Operational (SAFEOP)
Operational (OP)
Bootstrap (BOOT)

For information on the meaning of the states see “EtherCAT and EtherCAT-P Slave Implementation Guide”.

The slaves current state can be checked by issueing the following command on the controller:

ethercat slaves

The response of this command should be similar to:

0  0:0  OP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  OP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  OP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  OP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  OP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  OP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit

where the third column shows the EtherCAT slave state.

When a MOTORCORTEX control application starts it will put all the slaves into Operational state.

EtherCAT slaves configuration

Introduction

MOTORCORTEX and EtherCAT basics

MOTORCORTEX

EtherCAT Domains/Groups

Sending Information over EtherCAT

Parameter Types in MOTORCORTEX:

Configuring EtherCAT Topology

Introduction

Scanning available slaves

Create/update EtherCAT Topology

The exact content of the `topology.xml` file will not be discussed in this document, since it is complex and not needed for this document. If the user is curious, he is encouraged to open the file in a text editor and view the content. The file should not be modified by hand.

⚠ 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.

Linking EtherCAT Slaves to MOTORCORTEX signals

Creating slave configurations and linking signals to MOTORCORTEX (pdo.xml)

Adding information to slaves

Linking a digital input to a MOTORCORTEX parameter

!!TBD!! G0110-0200-01-MAN-[Developing Motorcortex Applications in C++ (Server)](#Developing Motorcortex Applications in C++ (Server)).

Linking a digital output

Analog inputs

Analog outputs

Start-up files and SDOs

Mapping an SDO to the MOTORCORTEX Tree

Advanced EtherCAT configuration

EtherCAT Domain Errors

EtherCAT slave Status

!! TBD Distributed Clocks !!

!! TBD FsoE slaves !!

EtherCAT slaves configuration

Introduction

MOTORCORTEX and EtherCAT basics

MOTORCORTEX

EtherCAT Domains/Groups

Sending Information over EtherCAT

Parameter Types in MOTORCORTEX:

Configuring EtherCAT Topology

Introduction

Scanning available slaves

Create/update EtherCAT Topology

The exact content of the topology.xml file will not be discussed in this document, since it is complex and not needed for this document. If the user is curious, he is encouraged to open the file in a text editor and view the content. The file should not be modified by hand.

⚠ 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.

Linking EtherCAT Slaves to MOTORCORTEX signals

Creating slave configurations and linking signals to MOTORCORTEX (pdo.xml)

Adding information to slaves

Linking a digital input to a MOTORCORTEX parameter

!!TBD!! G0110-0200-01-MAN-[Developing Motorcortex Applications in C++ (Server)](#Developing Motorcortex Applications in C++ (Server)).

Linking a digital output

Analog inputs

Analog outputs

Start-up files and SDOs

Mapping an SDO to the MOTORCORTEX Tree

Advanced EtherCAT configuration

EtherCAT Domain Errors

EtherCAT slave Status

!! TBD Distributed Clocks !!

!! TBD FsoE slaves !!

The exact content of the `topology.xml` file will not be discussed in this document, since it is complex and not needed for this document. If the user is curious, he is encouraged to open the file in a text editor and view the content. The file should not be modified by hand.