How EtherCAT works in Motorcortex

How a device on the EtherCAT bus becomes parameters in the tree: from the ESI file and the bus scan, through master.xml, to the running bus and its error reporting.

  8 minute read  

Motorcortex talks to drives and I/O through an EtherCAT bus. This page explains what happens between a device on the bus and a parameter in your application, and how the bus reports errors. To add a device step by step, follow Add a device.

From device to parameter tree

The whole bus is described in one file, io/master.xml in the configuration package. The ECAT tool writes it; Motorcortex reads it when the application starts. Click a box to read more about that step.

Add the devices from a bus scan Bus scan Scan Bus in the ECAT tool Load the ESI file in the Settings tab of the device ESI file from the device vendor The ECAT tool ECAT tool devices, PDOs, links io/master.xml in the configuration package io/master.xml read at start-up When a slave does not reach OP EtherLab master brings slaves to OP The parameters the EtherCAT module adds Parameter tree root/Ethercat/… Link an entry to the application Application through the links
  1. Find the devices. Scan Bus in the ECAT tool reads which devices are on the bus, with their vendor ID, product code and revision number.
  2. Describe them. An ESI fileEtherCAT Slave Information: an XML file from the device vendor that describes the device, its sync managers, its PDOs and its distributed clock modes. fills in what the scan does not know. Apply ESI from database looks it up by vendor ID, product code and revision number; Upload ESI file loads one you have.
  3. Choose what to exchange. In the device configuration panel you name the entries you need and link them to the application. Deploy sends the result to the controller as master.xml.
  4. Start the application. It reads the file that config.json names under "Path": { "Fieldbus": "io/master.xml" }. It configures the EtherLab master, which brings every device to the OP state, and adds a parameter for every named entry under root/Ethercat. How the names in the file make each path is on io/master.xml.

When a device does not reach OP, the kernel log says why: see Troubleshoot EtherCAT.

What travels over the bus

A device exchanges four kinds of data with the controller. They differ in when they travel, and so in what they suit.

Kind When it travels Suits Set up in
PDOProcess data object: a block of values exchanged with the device every cycle. An RxPdo goes to the device, a TxPdo comes from it. entries Every cycle of the EtherCAT task Setpoints, actual values, digital I/O rxPDO and txPDO tabs
SDOService data object: a single value in the device’s object dictionary, read or written on request through the mailbox. entries An rxSDO when you change its parameter; a txSDO when you ask with read_sdo or read_sdos Gains, limits, error codes rxSDO and txSDO tabs
Startup commands Once, while the master configures the device Settings the device needs before it runs, such as its input range Startup tab
Distributed clock Set up once at start-up Devices that must act at the same moment every cycle Distributed Clock tab

The PDOs travel in the process data sync managersBuffers in the device, each for one direction of data: usually sync managers 0 and 1 for the mailbox, 2 for the outputs to the device and 3 for the inputs from it. , usually sync manager 2 to the device and 3 from it. SDOs and startup commands use the mailbox. The tabs are explained on the device configuration panel.

Startup commands are sent in the order of the list:

  • CoE commands are all sent while the device is in PREOP, before the master asks for SAFEOP.
  • SoE commands are sent at the transition you choose: IP (INIT to PREOP), PS (PREOP to SAFEOP) or SO (SAFEOP to OP). Without a transition, PS is used.

Domains

A domainA group of devices in master.xml that shares one block of process data, one working counter check and one Simulation switch. groups devices. Motorcortex checks the working counterA count in every EtherCAT frame of how many devices processed it. When it is lower than expected, at least one device did not answer. of each domain every cycle, so each domain reports its own errors. A domain can also run simulated while the others run on the real bus: see Simulating devices.

The standard robot configuration has two domains: GCC, with the devices EK1914-01 and EL6910-01, and Axes, with the drives Axis-01 to Axis-09.

How a domain reports an error

A short glitch should not stop the machine, so a domain only reports an error when the working counter stays incomplete for longer than error_delay_sec. It clears the error once the counter has been complete for no_error_delay_sec.

Every cycle Wait Report Application Working counter did every device in the domain answer? The delay parameters of a domain Delay error_delay_sec no_error_delay_sec The error and state parameters of a domain Domain error …/<domain>/error …/<domain>/state ES_Bus_Error ES_Bus_Error in the Robot App, via base.link.json The error clears again once the counter has been complete for no_error_delay_sec.

In the standard robot configuration, base.link.json links root/Ethercat/GCC/error and root/Ethercat/Axes/error to the Robot App, which then raises ES_Bus_Error.

Parameters in the tree

Next to the device parameters, the EtherCAT module adds these parameters under root/Ethercat, and under root/Ethercat/<domain> for each domain. Ethercat is the Name of the fieldbus in master.xml.

Parameter Type What it does Default
read_sdos input Set it to read the SDO entries of every domain from the devices once. It resets itself. false
read_regs input The same for register entries. false
error output true while any domain has an error.
counter output Counts the cycles of the EtherCAT task.
master_id output The number of the EtherCAT master, from Device in master.xml.
cpu_affinity parameter The CPU the master’s thread runs on.
<domain>/state output 0 off, 1 running, 2 error.
<domain>/error output true while the domain has an error. Only a domain with a Name has it.
<domain>/simulation_enabled output true when the domain runs simulated.
<domain>/read_sdo input Reads the SDO entries of this domain once. Only there when the domain has SDO entries. false
<domain>/error_delay_sec parameter How long, in seconds, the working counter must be incomplete before error is set. 0
<domain>/no_error_delay_sec parameter How long, in seconds, it must be complete again before error clears. 0

A device entry is an input parameter when it goes to the device (rxPDO) and an output when it comes from it (txPDO). In simulation mode both are ordinary parameters that you can write.

A link can convert between the raw number of a device and a value in a unit, such as volts. It computes:

destination = source × Gain / Divide + GainOffset

The source is the entry for a txPDO and the application parameter for an rxPDO. As an example, take an analog card that reads -10 V to +10 V as a 16-bit signed value, so 3276.8 counts per volt:

  • An input: a link with Divide="3276.8" on the entry gives the application the voltage.
  • An output: a link with Gain="3276.8" turns a voltage from the application into counts. GainOffset="3276.8" would add 3276.8 counts, so 1 V, after the gain.
<Entry Name="Voltage">
  <Link Index="0" Simulation="false" Divide="3276.8">root/MyApp/inputVoltage</Link>
  <Index>#x6000</Index>
  <SubIndex>17</SubIndex>
  <BitLen>16</BitLen>
  <DataType>INT16</DataType>
</Entry>

root/MyApp/inputVoltage stands for a parameter of your application. By default the result is clamped to the range of the destination’s data type. All link attributes are listed on io/master.xml.

Slave states

Every device, a slave in EtherCAT terms, goes through the states INIT, PREOP, SAFEOP and OP when the master configures it. When the application starts, the master takes every device to OP. ethercat slaves on the controller shows the state of each device:

1  5555:0  PREOP  +  EL3162 2C. Ana. Input 0-10V

The columns are the position on the bus, the alias and the position relative to it, the state, the error flag (+ for none, E when the scan or configuration failed) and the name. Where each state can go wrong is on Troubleshoot EtherCAT.

Configurations from before the ECAT tool

The older topology.xml and pdo.xml format

Configurations written by hand, before the ECAT tool, use an older format that Motorcortex still reads. Its root element is <Master> instead of <Motorcortex>. A master.xml that starts with <Motorcortex Version="2.0"> uses the current format; other files use the older one. The application log says which, with Using EtherCAT XML Parser 2.0 or Using EtherCAT XML Parser 1.0.

In the older format the device descriptions come from a topology file, the output of ethercat xml on the controller with every device connected. A domain points at it with File, and its devices only list what differs from it:

<Domain Name="IO" File="topology.xml" ErrorDelaySec="0.1" NoErrorDelaySec="1">
  <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
      <Link>root/Control/dummyBool</Link>
    </Pdo>
  </Device>
  <Device Id="5" Name="05-EL3174-01">
    <Mailbox File="05-EL3174-01_startup.xml"/>
    <Sdo Entry="800d:11" Group="SDOs" Name="Input Type channel 1" DataType="INT16"/>
  </Device>
</Domain>
Element or attribute What it does
Domain File The topology file with the device descriptions.
MapAll On a domain or a device: puts every PDO entry of the topology file in the parameter tree.
ErrorDelaySec, NoErrorDelaySec Start values of error_delay_sec and no_error_delay_sec.
Device Id The position of the device on the bus, counted from 0.
Pdo Entry Index and subindex of the entry, in hex, for example 6000:01.
Mailbox File A file with startup commands, with root element EtherCATMailbox.
Sdo Entry An SDO in the parameter tree. Set its type with the DataType attribute: the DataType element and the Size attribute are no longer used.

Links take the same attributes as in the current format. To move such a configuration to the ECAT tool, add the devices again from a bus scan and set up their links there.