Getting Started

Prerequisites

Linux, macOS, or Windows. Linux with a PREEMPT_RT kernel is recommended for production; the library performs its own OS and system-level optimizations for real-time performance.
At least one Ethernet port dedicated to EtherCAT (not shared with your LAN).
A C toolchain — gcc on Linux and macOS, or an x64 Native Tools Command Prompt for VS 2022 or later on Windows.
Root / sudo access on Unix systems, required for direct access to the Ethernet adapter.

Slave requirements

Every slave on the network must:

Be an EtherCAT slave using the CiA 402 motion profile.
Expose at least Status Word: 0x6041 and Position actual value: 0x6064 in its Tx (slave → master) map.
Expose at least Control Word: 0x6040 and Target position: 0x607A in its Rx (master → slave) map.

Installation

The EtherCAT Master ships as an archive from the downloads page — there is no package repository to add. Download the build for your platform and extract it. The archive contains:

Item	Purpose
`libethercat.a`	The EtherCAT master static library.
`ethercat.h`	The public C API header.
`main.c`	Example application demonstrating the API.
`app_config.yml`	Example configuration file.
`ESI/`	Folder for your slave ESI (EtherCAT Slave Information) files.
`rebuild_and_rerun_app.sh` / `.bat`	Build-and-run helper scripts.

Configure

Before running the library:

Set interface_name in the ethernet section of app_config.yml to the Ethernet adapter used for EtherCAT. If you do not know the interface name, run the library anyway — it prints the list of valid interface names. You can also list adapters with ifconfig.
Set your desired EtherCAT cycle_time.
Copy your slave ESI files into the ESI/ folder.

# app_config.yml
ethernet:
  interface_name: enp86s0
  prioritize_usr_space_eth_drv: true

ethercat:
  esi_file_path: ESI/
  prioritize_esi_config: true
  cycle_time: 4000        # [us], only multiples of 250 us supported
  shift_time: 30          # [% of cycle time], DC master frame send to sync0 offset
  rx_frame_timeout: 12000 # [us], Unix only, between 1/4 and 3 times cycle_time

Build and run the example

Linux and macOS

To rebuild and rerun the example application:

./rebuild_and_rerun_app.sh

To run the already-built example against a config file:

sudo ./ethercat_master_example <path_to_config_file>

Sudo is required because the library performs OS optimizations and needs direct access to the Ethernet adapter. Run sudo -s first if you would rather keep privileges for the whole shell session.

Windows

To rebuild and rerun, from an x64 Native Tools Command Prompt for VS 2022 or later:

rebuild_and_rerun_app.bat

To only run the example, from a command prompt:

ethercat_master_example <path_to_config_file>

The config file path defaults to app_config.yml if you omit it.

Caution: the example application servos on the first motor and moves it slowly. Make sure the axis is clear before you run it.

main.c servos on and moves a single-axis servo drive slave at constant speed, and doubles as a worked reference for the library API. Slave indexes are slave positions within the network, indexed from zero.