linuxcnc-ethercat

LinuxCNC Ethercat XML Configuration Reference

LinuxCNC-Ethercat needs an XML configuration file to tell it about the EtherCAT hardware in the system. This configuration file provides naming information and tells it how to map specific LinuxCNC pin names to specific hardware.

LinuxCNC-Ethercat provides a long list of drivers for specific hardware, and also provides a way to talk to generic EtherCAT hardware, with all of the configuration specified in the ethercat.xml configuration file.

In general, compiled-in drivers are easier to work with and can have extra error checking, but they’re harder to create in the first place. The generic driver maps specific LinuxCNC pins directly to EtherCAT PDOs, without needing any code. In many cases this is sufficient to get arbitrary hardware working.

The basic structure of ethercat.xml looks like this:

<masters>
  <master idx="0" appTimePeriod="2000000" refClockSyncCycles="1000">
    <slave .../>
	...
  </master>
</masters>

There is a <masters> tag at the top, which contains one or more <master> tags, each of which describe an EtherCAT bus. Each <master> then has one or more slaves, each of which may have some additional configuration provided.

LinuxCNC systems with multiple Ethernet interfaces may be configured with EtherCAT devices on multiple interfaces; in this case there will be multiple <master>s listed.

Master Configuration

The <master> tag has a few attributes, some of which are optional and some of which are required:

Generally, for “normal” systems, this will look like

  <master idx="0" appTimePeriod="1000000" refClockSyncCycles="1000">

Slave Configuration

The <slave> tag has a number of attributes, some of which are only usable with generic devices, and others which are usable with any device:

Non-generic devices cannot use the generic-only options, but they have an additional configuration mechanism available to them. You can add additional <modParam name="<name>" value="<value>"/> tags. The exact meaning of these is driver-defined.

It is possible to specify vid and pid for non-generic devices. This overrides the built-in VID and PID that each type provides; it’s really only useful with the basic-cia402 driver.

Generic devices generally have configPdos="true", and then define a set of <syncManager>, <pdo>, <pdoEntry>, and possibly <complexEntry> tags that describe the PDOs used on the device.

Here is a simple example, for a Beckhoff EL1008 digital input device. Note that there is a compiled driver for the EL1008, but it’s possible to use generic to talk to the hardware instead:

    <slave idx="2" type="generic" vid="00000002" pid="03fa3052" name="D2" configPdos="true">
      <syncManager idx="0" dir="in">
	<pdo idx="1a00">
	  <pdoEntry idx="6000" subIdx="01" bitLen="1" halPin="din-0" halType="bit"/>
	</pdo>
	<pdo idx="1a01">
	  <pdoEntry idx="6010" subIdx="01" bitLen="1" halPin="din-1" halType="bit"/>
	</pdo>
	<pdo idx="1a02">
	  <pdoEntry idx="6020" subIdx="01" bitLen="1" halPin="din-2" halType="bit"/>
	</pdo>
	<pdo idx="1a03">
	  <pdoEntry idx="6030" subIdx="01" bitLen="1" halPin="din-3" halType="bit"/>
	</pdo>
	<pdo idx="1a04">
	  <pdoEntry idx="6040" subIdx="01" bitLen="1" halPin="din-4" halType="bit"/>
	</pdo>
	<pdo idx="1a05">
	  <pdoEntry idx="6050" subIdx="01" bitLen="1" halPin="din-5" halType="bit"/>
	</pdo>
	<pdo idx="1a06">
	  <pdoEntry idx="6060" subIdx="01" bitLen="1" halPin="din-6" halType="bit"/>
	</pdo>
	<pdo idx="1a07">
	  <pdoEntry idx="6070" subIdx="01" bitLen="1" halPin="din-7" halType="bit"/>
	</pdo>
      </syncManager>
    </slave>

Compare with the PDOs listed in the LinuxCNC-Ethercat device PDO explorer, and you’ll see that there’s a nearly direct mapping from the PDO documentation to the XML file.

In order to get this correct for any given device, you’ll need to refer to the manufacturer’s documentation, and some trial and error may be required.

<syncManagers>

The <syncManager> tag sets up an EtherCAT sync manager. (link needed)

The following attributes are available:

<pdo>

The <pdo> tag has a single attribute:

<pdoEntry>

The <pdoEntry> tag sets up a specific PDO entry and maps it to a LinuxCNC pin.

Attributes:

<complexEntry>

In some cases, multiple logical values are packed into a single PDO. The <complexEntry> tag provides a way to extract these into individual pins.

Attributes:

Other tags, not yet documented.

In addition to the above tags, there are a handful of others available that will be useful in specific situations:

This site is open source. Improve this page.