io/master.xml

The EtherCAT bus configuration: the devices on the bus, how their process data appears in the parameter tree, and what it is linked to.

  5 minute read  

The io folder holds the EtherCAT bus configuration. master.xml lists the devices on the bus, the process data each one exchanges, and the application parameters that data is linked to. You create and edit it with Motorcortex-ECAT, not by hand.

└── io
    ├── master.xml
    └── firmware
        └── ec_{VendorID}_{ProductCode}_{RevisionNumber}.bin

The application reads the file named in config.json:

"Path": {
  "Fieldbus": "io/master.xml"
}

From master.xml to the parameter tree

At start-up the application creates a parameter for every named PDOA PDO (process data object) is a block of values a device exchanges with the controller every cycle. An RxPdo goes to the device, for example a target position; a TxPdo comes from the device, for example the actual position. entry in the file. The names in the file make its path, and the <Link> elements inside an entry connect it to the application. This is how it works for the target and actual position of the first axis in the standard robot configuration:

The names in master.xml make the path of each entry root / Go to Domains configuration panel Ethercat / Go to Domains configuration panel Axes / Go to Device configuration panel Axis-01 / Go to Device configuration panel Inputs / Go to Device configuration panel Target position FieldBus Name Domain Name Device Name PDO Group Entry Name A Link inside each entry connects it to the application Application parameter Entry under root/Ethercat/Axes/Axis-01 Drive on the bus RxPdo: to the drive …/motorPositionTarget Link Go to Device configuration panel Inputs/Target position sent every cycle TxPdo: from the drive …/motorPositionActual Link Go to Device configuration panel Outputs/Position actual value read every cycle Go to Simulating devices When the domain runs simulated, a Link with Simulation="true" also connects the entry to root/Simulator ›

The same two entries in master.xml:

<Motorcortex Version="2.0">
  <FieldBusList>
    <FieldBus Type="EtherCAT" Device="0" Name="Ethercat">
      <Domain Group="" Name="Axes" Simulation="true">
        <Device Alias="3" Name="Axis-01" AllowOverlappingPdos="false">
          <RxPdo Sm="2" Fixed="false" Mandatory="false" Group="Inputs">
            <Index>#x1600</Index>
            <Entry Name="Target position">
              <Link Index="0" Simulation="false">root/AxesControl/actuatorControlLoops/actuatorControlLoop01/motorPositionTarget</Link>
              <Link Index="0" Simulation="true">root/Simulator/targetPosition</Link>
              <Index>#x607A</Index>
              <SubIndex>0</SubIndex>
              <BitLen>32</BitLen>
              <DataType>INT32</DataType>
            </Entry>
          </RxPdo>
          <TxPdo Sm="3" Fixed="false" Mandatory="false" Group="Outputs">
            <Index>#x1A00</Index>
            <Entry Name="Position actual value">
              <Link Index="0" Simulation="false">root/AxesControl/actuatorControlLoops/actuatorControlLoop01/motorPositionActual</Link>
              <Link Index="0" Simulation="true">root/Simulator/positionValue</Link>
              <Index>#x6064</Index>
              <SubIndex>0</SubIndex>
              <BitLen>32</BitLen>
              <DataType>INT32</DataType>
            </Entry>
          </TxPdo>
        </Device>
      </Domain>
    </FieldBus>
  </FieldBusList>
</Motorcortex>

The group names are seen from the drive: its Inputs are what the controller sends, its Outputs what it sends back.

All elements at a glance

Element What it sets
<FieldBus> Type="EtherCAT", Device: the number of the EtherCAT master, 0 for the first. Name is the first level of every path under root. Only the first <FieldBus> in the list is used
<Domain> A group of devices. Name is the next level of the path. With Simulation="true" the domain runs simulated, also in production mode; in simulation mode every domain does. See Simulating devices
<Device> One device on the bus. Name is the next level of the path; an optional Group adds a level before it
<RxPdo>, <TxPdo> The process data to and from the device. Group adds one or more levels to the path, for example FSoEData/FromSafetyPLC. With a Name, the whole PDO also becomes one parameter
<Entry> One value in the PDO. With a Name it becomes a parameter; entries without one, such as padding bits, do not
<Link> Connects the entry to the application parameter whose path is its text. See the attributes below

Two attributes work on most elements:

  • Included="false" leaves the element out, as if it were not in the file. It works on the fieldbus, a domain, a PDO, an entry and a link.
  • Visible="false" on a PDO or an entry keeps it on the bus but leaves it out of the parameter tree.

A link on an RxPdo entry copies the application parameter into the entry, a link on a TxPdo entry copies the entry into the application parameter. Both happen every cycle.

Attribute What it does Default
Index The element of the linked parameter, for an array 0
Simulation true makes this the simulation link: it is only made when the domain runs simulated, and then connects the entry to the simulator false
Gain Multiplies the value 1.0
Divide Divides the gain, for a gain that is easier to write as a fraction none
GainOffset Added after the gain 0.0
Invert Inverts a true/false value false
Clamp When the value goes into a smaller data type, limits it to that type’s range instead of letting it wrap around true

A normal link (Simulation="false") is made in every mode. In simulation, the simulator writes the actual values into the TxPdo entries, and the normal links pass them on to the application as they would from a real drive.

Firmware files

The firmware folder is only needed for a device whose own memory is too small for its SIIThe SII (Slave Information Interface) is a small memory in every EtherCAT device. It holds the device’s identity and a description of its process data. data. Each file is named after the <Type> of its device in master.xml, as eight hexadecimal digits each for the vendor ID, the product code and the revision number. For a device with

<Type VendorId="#x00000002" ProductCode="#x077a2c52" RevisionNo="#x00120000">EK1914</Type>

the file is io/firmware/ec_00000002_077a2c52_00120000.bin. How to make one is in Custom SII firmware.