Getting Started with the Adeeb EtherCAT Master on Linux

This is the first video in the Adeeb Robotics training series. It walks through using the Adeeb EtherCAT Master to command an EtherCAT servo drive — an EtherCAT slave — on Linux: the download, the configuration files, the example application, a live network scan, and pushing cycle time down to 250 µs to spin a real Yaskawa servo.

Hardware setup

The demo uses a minimal single-axis bench:

• An Intel NUC mini PC acting as the EtherCAT master.
• A Yaskawa EtherCAT servo drive connected to the NUC over a single Ethernet cable, plugged into the physical LAN port on the back of the NUC.
• A Yaskawa servo motor wired to the drive via encoder and motor power cables.

The Adeeb EtherCAT Master includes an optimized real-time Ethernet driver tuned for NUC mini PCs that use the Intel IGC driver. On NUC hardware this user-space driver delivers the deterministic timing required to reach the lowest supported cycle times; it is not used on any other platform.

Downloading the release

The trial libraries are published on the Adeeb Robotics downloads page.

1. Open the downloads page and locate the EtherCAT Master package. Releases ship for Linux, Windows, and macOS, each bundled with example code.
2. Download the Linux library and unzip it.
3. Open the extracted folder in your editor (the demo uses Visual Studio).

The 2-hour trial runs for two hours per session and must be restarted afterward. The licensed version has no time limit.

What’s in the package

Item	Purpose
ESI files	Slave description files supplied by the device vendor. The demo uses the ESI for the Yaskawa Sigma-7 EtherCAT servo slaves.
Real-time Linux Ethernet driver	The optimized user-space driver for NUC mini PCs running the Intel IGC driver. It is not used on other PCs.
Config file	Holds the EtherCAT timing parameters and, where applicable, the network interface name.
Example application	A cross-platform C program demonstrating the master API. It builds and runs on Linux, macOS, and Windows.
Library binary + header	The compiled master library plus a header exposing every supported API and constant.

Configuration

Selecting the network interface

The config file contains the network interface name. On Linux you can retrieve it with ifconfig (on Windows the equivalent is ipconfig). When the optimized user-space driver is active — the case on a NUC running Linux — the interface name is not needed, because the driver binds directly.

If you disable the optimized driver, or run on Windows, macOS, or Linux on non-NUC hardware, you must set the interface name correctly. If it points at a value that does not exist on the machine, the master will not start and the terminal prompts you to pick from the available interfaces — the rebuild-and-run script lists the detected interfaces so you can select the one wired to the slave.

Timing parameters

The EtherCAT configuration is where you tune determinism and throughput. The key parameters:

• Cycle time — in microseconds. The minimum supported is 250 µs, which only works reliably on NUC mini PCs running Linux with the prioritized user-space Ethernet driver enabled. Cycle time must be a multiple of 250 µs; any other value is rejected and the master snaps to the nearest valid value. Yaskawa EtherCAT servo slaves do not support a cycle time larger than 4,000 µs.
• Prioritize user-space Ethernet driver — keep this set to true. It ensures the deterministic driver is always prioritized.
• Shift time — governs when the frame is sent relative to the slave’s SYNC0 event. The diagram in the package shows the SYNC0 event, the frame cycle, and the delay between SYNC0 and the frame becoming active. It is expressed as a percentage of the cycle time. You rarely need to change it; 30% is a good default.
• Receive frame timeout — the point at which the master declares slave throughput bad and reports the frame as dropped (not received). For a low-throughput slave, raise this to the maximum allowed. The supported range is one quarter to three times the cycle time.

How the example application works

The example is a single C program that natively supports Linux, macOS, and Windows. Its core is a cyclic thread — an infinite loop that runs the EtherCAT cycles synchronously.

Each cycle proceeds in this order:

1. The library sleeps the required interval until it is time for the next cycle.
2. It transmits the EtherCAT frame.
3. It reads the cyclic feedback data from the returned frame.
4. At the end of the loop it writes the cyclic command data.
5. It processes asynchronous commands.
6. It performs DC sync synchronization.
7. It receives the EtherCAT frame back — every cycle sends a frame and then receives it.

Asynchronous commands cover servo-on and servo-off, plus reading and writing COE objects. COE (CAN over EtherCAT) objects are parameters on the slave. Servo-on places the drive in a mode that accepts position commands and motion; servo-off takes it out of that mode.

DC sync refers to distributed clock synchronization. Every device runs an internal clock at a slightly different rate, so the clocks must be continuously synchronized — by adjusting either the master clock or the slave clock, called master shift or slave shift mode respectively. The Adeeb EtherCAT Master currently supports master shift mode only; slave shift mode is not yet supported.

The main function

The main function follows this sequence:

1. Query the version of the EtherCAT master library.
2. Initialize the EtherCAT master library.
3. Apply system real-time pre-optimizations for throughput.
4. Launch the cyclic thread — the program contains separate launch paths for Unix and Windows systems.
5. Initialize the network: scan for slaves and place them all in pre-operational mode.
6. Request operational mode for all slaves. Once in operational mode, distributed clock synchronization is running and commands are read from and written to the slaves.

The library exposes an API that returns the number of detected slaves. To run in position mode, set the CiA 402 op mode on the slave to Cyclic Synchronous Position (CSP). The example then reads and writes a few COE objects: each access takes a slave index (zero-based, so 0, 1, 2, 3 …), an object index, a subindex, and the value. The bench has a single slave, so the slave index is 0.

Running a network scan

The package includes a convenience script that rebuilds the example code and runs it in one step. On launch it brings up the real-time Ethernet Linux driver, and the servo audibly hums once it servos on — the motor turns slowly at the default cycle time because the update rate is low.

On exit the run reports what it found and how it performed:

• One slave found on the network, with its sync manager information initialized from the ESI file.
• The slave’s vendor ID and product code.
• The state transitions: init, then pre-op, then op.
• The values read from the COE objects.
• Timing statistics — current, average, minimum, maximum, and standard deviation for both latency and DC clock drift (between master and slave), plus the count of latency cycles and runtime cycles.

Pushing cycle time to 250 µs

The default config runs at 4,000 µs. Because this is a NUC mini PC, you can lower the cycle time all the way to 250 µs. Set the receive frame timeout to one third of the cycle time — roughly 83 µs — staying within the allowed one-quarter-to-three-times range.

On the next run the motor spins faster because the example adds 10 encoder ticks per cycle, and cycles now occur 4,000 times per second: a 250 µs cycle time is 4,000 Hz, an extremely fast rate for an EtherCAT system, achievable only because of the optimized real-time driver.

Watching for latency warnings

Whenever a cycle incurs slightly longer latency, the master prints a warning. If you run computationally heavy work — or drag the editor window around too aggressively — the warnings get worse and you can exceed the maximum runtime of 250 µs. Leave the machine alone and the run stays clean for long stretches; Adeeb has run continuous stress tests for two weeks with no issues.

To reduce CPU and memory load, close the editor and run directly from the terminal. After stopping with Ctrl+C, the demo reported a maximum runtime of 335 µs — startup occasionally produces a few long cycles, which is not a concern as long as the standard deviation stays very small — while maximum latency was only 5 µs, with clock drift reported alongside.

The library API

The library file itself is a binary; the accompanying header declares every supported API and the library constants, grouped by function:

• COE object reads and writes.
• EtherCAT state control — moving slaves between pre-op and op.
• Additional master control and status APIs.

Next steps

• Grab the trial libraries and ESI files from the downloads page and run the example against your own slave.
• Review the full feature set on the Adeeb EtherCAT Master product page.
• Continue the series with Getting Started with the Adeeb Robot Controller on Linux, which builds on this stack with the arc Python module:

from arc import *

• Request a demo to see the master driving a multi-axis system at 250 µs cycle time.