Device configuration panel

Set up one EtherCAT device in the ECAT tool: its process data, SDOs, distributed clock, start-up commands and sync managers.

Click a device in the Domains list of the ECAT tool and its settings open in the middle of the screen, in the device configuration panel. Its tabs decide which data Motorcortex exchanges with the device, when, and where that data appears in the parameter tree. Deploy sends the configuration to the controller. Saved as a file, it is the master.xml in the io/ folder of a config package.

What each tab configures

Each tab sets up one way of talking to the device. The PDOsA PDO (process data object) is a block of values exchanged with the device every cycle. The rxPDO carries data to the device, such as a target position; the txPDO carries data from it, such as the actual position. carry the fast, cyclic data. The SDOsAn SDO (service data object) is a single value in the device’s object dictionary, read or written on request instead of every cycle. It suits settings and diagnostics. and the start-up commands travel through the device’s mailboxThe mailbox is a pair of sync managers on the device for request and reply messages, next to the ones for cyclic process data. , and the distributed clockThe distributed clock (DC) is a clock in every EtherCAT device, synchronised over the bus, so that all devices act at the same moment. times the device to the fieldbus cycle. Click a box to open its tab.

Most devices need little of this by hand. Load the device’s ESI fileAn ESI (EtherCAT Slave Information) file is an XML file from the device’s supplier. It describes the device: its identity, sync managers, PDOs and distributed clock modes. in the Settings tab and the tool fills in the PDOs, the sync managers and the distributed clock presets. You then name the entries you want in the parameter tree and link them to the application.

The tabs

The tabs are in the same order as in the tool. rxPDO and txPDO are two tabs in the tool that work the same way, and so are rxSDO and txSDO, so each pair shares one tab here.


Name and identity

The Settings tab says which device this is and what it is called in the parameter tree.

Settings tab of the ECAT tool, numbered: 1 Name, 2 Allow Overlapping PDOs switch, 3 Type, Product Code, Revision Number and Vendor ID, 4 Apply ESI from database and Upload ESI file buttons, 5 Add Link under Link Simulation
# Field What it does Default
1 Name The device’s folder in the parameter tree: root/Ethercat/<domain>/<Name>/…. The same field sits at the top of the panel. Give every device its own name: when two devices share one, the tool shows Device name is already taken and marks the device red in the Domains list. from the scan or the ESI file
2 Allow Overlapping PDOs Lets the rxPDOs and txPDOs share memory on the device. Switch it on only when the device’s documentation says it supports this; on other devices it can corrupt the data or break communication. off
3 Type, Product Code, Revision Number, Vendor ID The device’s identity, found by the bus scan or set by the ESI file. You cannot edit them here. from the scan

Load the ESI file

  1. Press Apply ESI from database to look the device up in the motorcortex.io ESI database by its vendor ID, product code and revision number. The search only runs while you are logged in. When nothing is found the tool says No descriptions found; then press Upload ESI file and choose the XML file from the device’s supplier.

A PDO that already has a name or group keeps them when you apply the ESI file again.

When the device’s domain can be simulated, give the device a simulation link. At start-up Motorcortex connects the domain’s simulation_enabled flag to the parameter you choose here, so that part of the application knows whether this device is simulated. For drives in the standard robot configuration this is root/DriveLogic/driveSimulation, one channel per drive. How the modes fit together is on Simulating devices.

  1. Press Add Link.

    Link dialog, numbered: 6 Path root/DriveLogic/driveSimulation with Channel 0, 7 the Simulation switch, 8 the Create parameter button. Gain 1, Divide 1 and Gain Offset 0 are left as they are.
  2. In Path, enter root/DriveLogic/driveSimulation. In Channel, enter the drive’s channel: 0 for the first drive, 1 for the second, and so on.

  3. The Simulation switch makes no difference for this link: it applies in every mode. The standard configuration has it on.

  4. Press Create parameter. The link appears under Link Simulation.

    Link Simulation with one link: root/DriveLogic/driveSimulation on channel 0

rxPDO and txPDO

The rxPDO tab holds the PDOs that Motorcortex sends to the device every cycle, such as Controlword and Target position. The txPDO tab holds the PDOs it reads back every cycle, such as Statusword and Position actual value. Both tabs work the same way.

A PDO is a numbered list of entries. Each entry points at one object on the device, by its index and subindex, and has a data type and a bit length. The device must support the mapping you configure, so start from the device’s ESI file (Settings tab) and only add PDOs by hand when the device’s documentation describes them.

Where the entries appear

Every entry with a Name becomes a parameter at:

root/Ethercat/<domain>/<device>/<PDO Group>/<entry Group>/<entry Name>

For example, in the standard robot configuration the rxPDO of Axis-01 in domain Axes has the group Inputs, so its Controlword entry is root/Ethercat/Axes/Axis-01/Inputs/Controlword. An empty group adds no folder, and a group can hold a slash to nest folders. In production mode an rxPDO entry is an input parameter, which you set or link, and a txPDO entry is an output, which you read. In simulation mode both are ordinary parameters that you can write.

You leave or set What happens
No Name The entry is still exchanged with the device, but gets no parameter.
Show in data tree off The same: exchanged, but no parameter, and its links are not made.
Include in Ethercat message off The entry, or the whole PDO, is left out of the mapping written to the device.

The PDO row

A new, empty PDO row, numbered: 1 Add PDO button, 2 index 0000, 3 Group, 4 Name, 5 Syncmanager 0, 6 include checkbox, 7 show in data tree, 8 More Actions, 9 Add Entry
# Field What it does Default for a new PDO
1 Add PDO Adds an empty PDO at the end of the list.
2 index The PDO’s object index in hex, for example 1600 for the first rxPDO or 1A00 for the first txPDO of a CiA402 drive. 0000
3 Group The folder for all entries of this PDO. empty
4 Name Makes the whole PDO one extra parameter with all of its data, next to its entries. The standard configuration uses .data to pass a safety device’s data on unchanged. Leave it empty if you only need the entries. empty
5 Syncmanager The sync manager that carries this PDO, from the Process data tab. Pick the one for process data in this direction; in the standard drive configuration that is 2 for rxPDOs and 3 for txPDOs. 0
6 Include in Ethercat message Off leaves the PDO out of the configuration. When the ESI file lists alternative PDOs, this is managed with PDO assignment in the Process data tab instead. on
7 Show in data tree Off: the PDO and its entries get no parameters. on
8 More Actions Add Link (links the PDO’s own parameter, see Name), Add Entry, Add PDO after and Delete.
9 Add Entry Adds an empty entry at the end of the PDO.

The entry row

A new, empty entry row, numbered: 10 index and subindex 0000:00, 11 Group, 12 Name, 13 data type Not set with a warning sign and bit length 0, 14 include checkbox, 15 show in data tree, 16 More Actions
# Field What it does Default for a new entry
10 index : subindex The object on the device, in hex, for example 6040:00 for the CiA402 control word. 0000:00
11 Group A folder inside the PDO’s group, for this entry only. empty
12 Name The parameter name, for example Controlword. empty
13 data type and bit length Bit, Bool, Int, UInt, Float, Double or String. Int and UInt take 8 to 64 bits in steps of 8; Bool is 1 bit, Float 32 and Double 64. Not set shows a warning sign. Not set, 0
14 Include in Ethercat Message Off leaves the entry out of the PDO mapping. on
15 Show in data tree Off: no parameter for this entry. on
16 More Actions Add Entry (after this one), Add Link, Add Mapping and Delete.

For example, the control word of a CiA402 drive is entry 6040:00, UInt, 16 bits, and its status word in the txPDO is 6041:00, UInt, 16 bits.

Link an entry to the application

A link connects an entry to a Motorcortex parameter, so the application does not have to use the entry’s own path. On an rxPDO entry the value flows from the linked parameter into the entry; on a txPDO entry it flows from the entry to the linked parameter. Press and Add Link, pick the parameter or enter its path, and press Create parameter.

Field What it does Default
Path The Motorcortex parameter, for example root/DriveLogic/driveControlWord. required
Channel The element of an array parameter: 0 for the first. 0
Simulation On: the link only applies while the device is simulated, and the value flows the other way: from an rxPDO entry to the linked parameter, and from the linked parameter into a txPDO entry. That is how the simulator is connected. Off: the link always applies. off
Gain, Divide, Gain Offset Scale the value by Gain ÷ Divide and shift it by Gain Offset. 1, 1, 0
invert Flips a true/false value. off

Which links a drive needs in each mode is on Simulating devices.

Split an entry into bits

Add Mapping divides one entry into smaller values, for example the 16 bits of a digital input word into 16 channels. Each map has an offset byte:bit inside the entry, a name, a group and a type. A new map is one Bit named channel 0, channel 1 and so on, at offset 00:00, 00:01, and so on. A map’s parameter sits next to its entry, in the entry’s group plus the map’s own group, and can have its own links.


rxSDO and txSDO

SDO entries are values in the device’s object dictionary that do not need to change every cycle: controller gains, limits, error codes. They travel through the mailbox, one request at a time, so they do not load the cyclic data.

  • An rxSDO entry is written to the device each time you change its parameter. The standard robot configuration uses them for the drive’s position and velocity loop gains.
  • A txSDO entry is read from the device when you ask for it: set root/Ethercat/read_sdos to read the txSDO entries of every domain, or root/Ethercat/<domain>/read_sdo for one domain. The standard configuration reads the drive’s Error Code this way.

The rxSDO and txSDO tabs work the same way. Every entry with a Name and a data type becomes a parameter at root/Ethercat/<domain>/<device>/<SDO Group>/<entry Group>/<entry Name>. For example, the standard Axis-01 has an rxSDO with group SDOs and an entry Position loop Kp in group Position Controller: root/Ethercat/Axes/Axis-01/SDOs/Position Controller/Position loop Kp.

Add an SDO

rxSDO tab with a new SDO, numbered: 1 Add SDO, 2 type COE, 3 index and subindex 0000:00, 4 Group, 5 Name, 6 data type Not set with bit length 0, 7 include checkbox, 8 More Actions, 9 Add Entry
# Field What it does Default
1 Add SDO Adds an SDO with one empty entry.
2 type The protocol for every SDO in this tab: COE (CoECANopen over EtherCAT: the device’s settings are objects with a 16-bit index and an 8-bit subindex, as in CANopen. ) or SOE (SoEServo drive profile over EtherCAT: the device’s settings are Sercos IDNs, such as S-0-0015. ). COE
3 index : subindex The entry’s object on the device, in hex, for example 2012:01. 0000:00
4 Group On the SDO row: the folder for all its entries. On an entry row: a folder for that entry. empty
5 Name On an entry row: the parameter name. On the SDO row it is a label only and adds no parameter. empty
6 data type and bit length As for PDO entries: Bit, Bool, Int, UInt, Float, Double or String. An entry left on Not set gets no parameter. Not set, 0
7 Include in Ethercat message Off leaves the SDO or the entry out. on
8 More Actions On the SDO row: Add SDO after, Add Entry, Delete. On an entry row: Add Entry, Add Link, Delete.
9 Add Entry Adds an empty entry to the SDO.

Entries from the standard drive configuration:

Tab Name Index:Sub Type Bits
rxSDO Position loop Kp 2012:01 Float 32
rxSDO .Save all parameters (hex: 0x65766173, dec: 1702257011) 1010:01 UInt 32
txSDO Error Code 603F:00 UInt 16
txSDO Error Report 203F:01 String 64

A link on an SDO entry works as on a PDO entry: on an rxSDO entry the linked parameter feeds the entry, on a txSDO entry the entry feeds the linked parameter.

Save and load the SDO list

Download saves the SDOs of the open tab as <device>-rx-sdos.xml or <device>-tx-sdos.xml. Upload loads such a file and replaces the SDOs of that tab. Use it to copy a set of SDOs to another device of the same type.

Example SDO file

The root element is EtherCATSdos, with RxSdo elements for the rxSDO tab or TxSdo elements for the txSDO tab. An upload to the rxSDO tab needs at least one RxSdo.

<EtherCATSdos>
  <RxSdo Group="SDOs">
    <Type>COE</Type>
    <Entry Name="Position loop Kp" Group="Position Controller">
      <Index>#x2012</Index>
      <SubIndex>1</SubIndex>
      <BitLen>32</BitLen>
      <DataType>FLOAT</DataType>
    </Entry>
  </RxSdo>
</EtherCATSdos>

What the distributed clock does

With the distributed clock on, the device acts on a SYNC0 signal from its own clock instead of on the arrival of the frame. All devices on the bus then take their inputs and apply their outputs at the same moment, once per cycle. The device’s ESI file says which settings it supports.

Distributed Clock tab, numbered: 1 the On switch, 2 Select from preset, 3 Assign Activate #x300, 4 Mode Cycle for Cycle Time Sync 0 and Cycle Time Shift 0, 5 Factor 1 for Sync 0 and -2 for Shift 0
# Field What it does Default
1 On / Off switch Turns the distributed clock on for this device. Off: the device runs without it. off
2 Select from preset Only there when the ESI file lists distributed clock modes. Pick one under Preset and press Confirm: it replaces all settings below.
3 Assign Activate The value that switches on the device’s SYNC signals, from the ESI file (AssignActivate). Type it in hex, #x300, or in decimal, 768; the tool stores it as hex. 0 leaves the distributed clock off, even with the switch on. #x300
4 Mode Cycle: the time follows the fieldbus task cycle, times or divided by Factor. User Defined: you enter the time as Value in nanoseconds. Cycle
5 Factor A positive factor multiplies the fieldbus task cycle time, a negative one divides it. Sync 0: 1, Shift 0: -2

Cycle Time Sync 0 is the time between two SYNC0 pulses. Cycle Time Shift 0 is how long after the start of the cycle the pulse comes. The at the top right opens DC Settings; switch on Show Sync/Shift 1 to also set Cycle Time Sync 1 and Cycle Time Shift 1, for devices that need a second signal. They are hidden and 0 by default.

The default timing

With the defaults and a fieldbus task of 1 kHz, as in the standard robot configuration, SYNC0 fires every 1 ms, half a cycle after each cycle start:

Fieldbus task 1 kHz: 1 ms cycle cycle start 0 ms 1 ms 2 ms 3 ms SYNC0 on the device shift cycle Cycle Time Sync 0, Factor 1: 1 × 1 ms = 1 ms between SYNC0 pulses Cycle Time Shift 0, Factor −2: 1 ms ÷ 2 = 0.5 ms after the cycle start

The same timing in User Defined mode is Value 1000000 ns for Cycle Time Sync 0 and 500000 ns for Cycle Time Shift 0. Cycle mode keeps it right when you change the task’s cycle time: Dt of Fieldbus_task in config.json, in microseconds.

When the device does not accept the settings, it does not go to Operational and reports an AL status such as 0x0030 (invalid DC synch configuration): see Troubleshoot EtherCAT.


Start-up commands

The Startup tab holds init commands: values the master writes to the device through the mailbox while it brings the device up, before the device reaches Operational. Use them for settings that must be in place before the device runs, such as the module list of a modular device or the IP address of a device with an Ethernet port. Each command belongs to a state transitionAn EtherCAT device starts in Init and goes through Pre-Operational (PreOp) and Safe-Operational (SafeOp) to Operational. IP is the step from Init to PreOp, PS from PreOp to SafeOp and SO from SafeOp to Operational. , which says when the master sends it.

Empty Startup tab, numbered: 1 the CoE, SoE and EoE sub-tabs, 2 the Upload button, 3 Add Item under Startup List is empty
  1. Choose the kind of command with the CoE, SoE and EoE sub-tabs.
  2. Upload loads a start-up file and replaces all commands of the device, in all three sub-tabs. Once the list has commands, Download saves them as <device>-startup.xml.
  3. Add Item adds a command. In a filled list, add the next one with in the header or Add Item under .

Every command has a Comment for your own description, the include in Ethercat message checkbox to leave it out without deleting it, and Delete under .


CoE commands

A CoE command writes a value to one object of the device, by index and subindex. The master sends it on the PS transition, from Pre-Operational to Safe-Operational.

A new CoE command row, numbered: 1 Index 0000 and subindex 0, 2 Comment, 3 Data showing NA, 4 the Complete Access switch, 5 include checkbox and More Actions
# Field What it does Default
1 Index : Sub Index The object: the index in hex, for example F030, the subindex as a number. 0000:0
2 Comment Your description, for example Module Slots. empty
3 Data The value to write: see the Data field below. NA
4 Complete Access On: writes the whole object in one go, all its subindexes from 0; Sub Index is then not used. Use it when the device’s documentation asks for it. off
5 and Include the command, Add Item after it, Delete. on
Example CoE start-up file

Two commands for object F030 of a modular device, from one of the standard robot configurations: a uint 8 at subindex 0 and a uint 32 at subindex 1.

<?xml version="1.0"?>
<EtherCATMailbox>
  <CoE>
    <InitCmds>
      <InitCmd>
        <Transition>PS</Transition>
        <Comment>Module Slots</Comment>
        <Timeout>0</Timeout>
        <Data DataType="UINT8" BitLen="8">00</Data>
        <Ccs>0</Ccs>
        <Index>#xF030</Index>
        <SubIndex>0</SubIndex>
      </InitCmd>
      <InitCmd>
        <Transition>PS</Transition>
        <Comment>Module Slots</Comment>
        <Timeout>0</Timeout>
        <Data DataType="UINT32" BitLen="32">01000204</Data>
        <Ccs>0</Ccs>
        <Index>#xF030</Index>
        <SubIndex>1</SubIndex>
      </InitCmd>
    </InitCmds>
  </CoE>
</EtherCATMailbox>

Data holds the bytes in the order they are sent, least significant first. Add CompleteAccess="true" to an InitCmd to write the whole object.


SoE commands

An SoE command writes a value to one IDN of a drive that uses the SoE profile. You choose the transition on which the master sends it.

A new SoE command row, numbered: 1 Drive No. 0, 2 Transition PS, 3 Comment, 4 Data showing NA, 5 IDN S, 0, 0000, 6 include checkbox and More Actions
# Field What it does Default
1 Drive No. The axis inside the device: 0 for a single-axis drive, 0, 1 and so on for a multi-axis drive. 0
2 Transition PS (Pre-Operational to Safe-Operational) or SO (Safe-Operational to Operational). PS
3 Comment Your description, for example the name of the IDN. empty
4 Data The value to write: see the Data field below. NA
5 IDN Three parts: S for a standard IDN or P for a product-specific one, the parameter set from 0 to 7, and the data block number from 0000 to 4095. S 0 0015 is S-0-0015. S 0 0000
6 and Include the command, Add Item after it, Delete. on

A start-up file can also hold OpCode, Elements and Attribute for each command. The tool keeps them, but you cannot edit them here and the EtherCAT master does not use them.

Example SoE start-up file

One command that sets IDN S-0-0015, the telegram type, on the PS transition.

<?xml version="1.0" encoding="utf-8"?>
<EtherCATMailbox>
  <SoE>
    <InitCmds>
      <InitCmd>
        <Transition>PS</Transition>
        <Comment>Telegram type</Comment>
        <Timeout>0</Timeout>
        <OpCode>3</OpCode>
        <DriveNo>0</DriveNo>
        <IDN>15</IDN>
        <Elements>64</Elements>
        <Attribute>0</Attribute>
        <Data>0700</Data>
      </InitCmd>
    </InitCmds>
  </SoE>
</EtherCATMailbox>

IDN is the number the three parts make: bit 15 is set for P, bits 12 to 14 hold the parameter set, and the lowest 12 bits the data block number. 15 is S-0-0015.


EoE command

An EoEEthernet over EtherCAT: Ethernet frames tunnelled through the EtherCAT mailbox, so that a device with an Ethernet port or a web interface can be reached over the bus. command gives the device its network settings. A device has at most one, so the list has no Add Item once it holds a command.

An EoE command row, numbered: 1 Comment eoe init, 2 Data 02000..., 3 the Edit Settings gear, include checkbox and More Actions
  1. Comment: eoe init for a new command.
  2. Data: the settings as 62 bytes of hex. Edit them with the gear instead of by hand.
  3. Edit Settings opens EoE Settings.
EoE Settings dialog, numbered: 4 Mac Address, 5 DHCP switch, 6 Include timestamps switch, 7 IP Address, 8 Subnet Mask, 9 Gateway, 10 DNS Server, 11 DNS Name, 12 Save
# Field What it does Default
4 Mac Address The device’s MAC address, as 02:01:05:10:03:e9. a random, locally administered address
5 DHCP On: the device gets its address from a DHCP server, and the address fields below are hidden. on while all addresses are 0.0.0.0
6 Include timestamps Sets the time stamp flag in the settings. off
7 IP Address The device’s IP address. 0.0.0.0
8 Subnet Mask For example 255.255.255.0. 0.0.0.0
9 Gateway The gateway address. 0.0.0.0
10 DNS Server The DNS server address. 0.0.0.0
11 DNS Name The device’s host name, at most 31 characters. empty
12 Save Writes the settings into Data.

The flags in Data tell the device which fields to use; see the byte layout below. The tool puts the command on the PS transition. If the controller’s EtherCAT driver has no EoE support, the master logs a warning and starts without it.

What the 62 bytes of Data hold
Bytes Field Notes
0 to 3 Header Always 02 00 00 00.
4 to 7 Flags Byte 4: bit 0 MAC address, bit 1 IP address, bit 2 subnet mask, bit 3 gateway, bit 4 DNS server, bit 5 DNS name included. Byte 5: bit 0 time stamps.
8 to 13 MAC address In the order you write it.
14 to 17 IP address Last number first: 10.0.2.123 is 7b 02 00 0a.
18 to 21 Subnet mask Last number first.
22 to 25 Gateway Last number first.
26 to 29 DNS server Last number first.
30 to 61 DNS name The characters, padded with zeros.

An example start-up file with MAC address 02:01:05:10:03:e9, IP address 10.0.2.123, subnet mask 255.255.255.0 and gateway 10.0.2.1:

<?xml version="1.0" encoding="ISO-8859-1"?>
<EtherCATMailbox>
  <EoE>
    <InitCmds>
      <InitCmd>
        <Transition>PS</Transition>
        <Comment>eoe init</Comment>
        <Timeout>0</Timeout>
        <Data>020000000f0000000201051003e97b02000a00ffffff0102000a000000000000000000000000000000000000000000000000000000000000000000000000</Data>
      </InitCmd>
    </InitCmds>
  </EoE>
</EtherCATMailbox>

The Data field

Click next to the value in the Data column to edit it.

Field What it does Default
type int, uint, float or octet array. octet array
bits int and uint: 8, 16, 32 or 64. float: 32. octet array: any multiple of 8. from the value
value A number for int, uint and float, checked against the type’s range. For octet array a hex editor. empty, shown as NA

Numbers are stored least significant byte first, the order in which EtherCAT sends them: uint 32 with value 1 becomes 01000000.


Sync managers

A sync managerA sync manager is a block of memory on the device that the master and the device share, each with a start address, a size and a direction. Some carry the mailbox, the others the cyclic process data. is the memory on the device through which data passes. The Process data tab lists the device’s sync managers; each PDO names the one that carries it. The ESI file fills in this list, so you rarely change it. Compare it with the ESI file when the device rejects its sync manager configuration.

Process data tab with the Syncmanagers table: columns Enable, Index, Name, Start Address, Control Byte and Default Size, the plus button to add one, and a new row with Enable off and Default Size 0
Field What it does Default for a new row
Drag the row to change the order.
Enable Whether the sync manager is enabled, as the ESI file gives it. off
Index The number a PDO’s Syncmanager refers to. one higher than the highest
Name For example MBoxOut, MBoxIn, Outputs, Inputs. empty
Start Address Where it starts in the device’s memory, in hex, for example #x1800. empty
Control Byte Its settings byte, in hex, from the ESI file. When bit #x40 is set, the master turns on the sync manager’s watchdog. empty
Default Size Its size in bytes. 0
/ Add Syncmanager, Delete Syncmanager. Deleting one that PDOs still use asks you to move those PDOs to another sync manager first.

The four sync managers of each drive in the standard robot configuration:

Name Start Address Control Byte Default Size Carries
MBoxOut #x1000 #x26 1024 mailbox to the device
MBoxIn #x1400 #x22 1024 mailbox from the device
Outputs #x1800 #x64 35 rxPDOs
Inputs #x1C00 #x20 47 txPDOs

PDO assignment

Some devices offer alternative PDOs for the same data, of which only one may be used at a time. When the ESI file says so, the tab shows a PDO assignment table below the sync managers. Tick Included for the PDO you want: the PDOs it excludes are switched off, and Info says which PDO excluded them. Such PDOs start switched off, and their include checkbox in the PDOs tab is managed from here.