Getting Started
The Adeeb Robotics EtherCAT Master library provides support for PDO and SDO EtherCAT communication via easy-to-use C APIs. The library also supports DC (Distributed Clocks) sync, EtherCAT state transitions, and CoE object reads and writes.
Software Release Version: 0.0.6
Requirements
Before using this library, ensure the following:
- All connected slaves are EtherCAT devices implementing the CiA 402 motion control profile.
- The TxPDO (slave-to-master) mapping includes at minimum:
- Status Word:
0x6041 - Position Actual Value:
0x6064
- Status Word:
- The RxPDO (master-to-slave) mapping includes at minimum:
- Control Word:
0x6040 - Target Position:
0x607A
- Control Word:
Initial Setup
Ethernet Interface Configuration
Update the interface_name field in the ethernet section of the app_config.yml file to match the Ethernet adapter used for EtherCAT communication.
If you’re unsure of the interface name, simply run the library and it will display a list of available network interfaces.
Cycle Time Configuration
Set your desired EtherCAT cycle time in the app_config.yml file.
ESI Files
Add the EtherCAT Slave Information (ESI) files for your devices to the ESI/ directory.
Building & Running
Linux / macOS
To rebuild and run the example application:
./rebuild_and_rerun_app.shTo run the example application only:
sudo ./ethercat_master_example <path_to_config_file>Windows
To rebuild and run the example application (use the x64 Native Tools Command Prompt for Visual Studio 2022 or later):
rebuild_and_rerun_app.batTo run the example code only:
ethercat_master_example <path_to_config_file>The default configuration file is app_config.yml. To list available network interfaces, run ifconfig.
Required Privileges
On Unix-based systems, root privileges (sudo) are required as the library performs real-time optimizations and direct access to the network interface. You can persist sudo privileges by running:
sudo -sSample Application
The main.c file contains a basic application that powers on a servo motor and jogs it at a slow constant speed. It serves as a reference for using the EtherCAT API.
Caution: The sample application will immediately power on the first motor and move it slowly. Ensure your hardware is safe and ready before running.
This library includes several OS- and system-level optimizations to help achieve high-performance real-time control.
Configuration File
Ethernet
| Field | Type | Description |
|---|---|---|
interface_name | String | Ethernet interface name |
prioritize_usr_space_eth_drv | Boolean | If true, use ethernet driver optimization if possible. Only supported on select hardware running Linux. See Appendix B. |
EtherCAT
| Field | Type | Description | Unit |
|---|---|---|---|
esi_file_path | String | ESI file path | N/A |
prioritize_esi_config | Boolean | If true, prioritize obtaining slave configuration from ESI file; otherwise use slave EEPROM SSI data | N/A |
cycle_time | u32 | EtherCAT cycle time, only multiples of 250μs supported | μs |
shift_time | u32 | DC master frame send to sync0 offset | % of cycle_time |
rx_frame_timeout | u32 | Receive frame timeout, only supported on Linux and macOS | μs |
Real-Time Cyclic Thread APIs
All APIs below are non-blocking except for thrd_rt_pre_opt_c(), sleep_tx_frm_rd_cyc_fbk(), and wr_cyc_cmd_prc_async_dc_sync_rx_frm().
| API | Description | Parameters | Returns |
|---|---|---|---|
thrd_rt_pre_opt_c() | Thread real-time optimization. Call once before the start of the real-time thread. | N/A | N/A |
sleep_tx_frm_rd_cyc_fbk() | Sleep the required amount of time and transmit EtherCAT frame. | N/A | Boolean |
wr_cyc_cmd_prc_async_dc_sync_rx_frm() | Process asynchronous EtherCAT commands, perform DC sync, and receive EtherCAT frame. | N/A | N/A |
rd_slv_pos_act() | Read slave actual position. | slv_idx (uint) | i32 |
wr_slv_trg_pos() | Write slave target position. | slv_idx (uint), pos (i32) | N/A |
rd_slv_sta_wrd() | Read slave status word for warning and alarm monitoring. | slv_idx (uint) | u16 |
rd_slv_cnt_wrd() | Read slave control word. | slv_idx (uint) | u16 |
wr_slv_cnt_wrd() | Write slave control word (e.g., for clearing faults and alarms). | slv_idx (uint), cnt_wrd (i16) | N/A |
rd_slv_servo_on_current() | Read current slave servo status (ON or OFF). | slv_idx (uint) | Boolean |
wr_slv_servo_on_desired() | Write desired slave servo status. Causes changes to the control word. | slv_idx (uint), servo_on_desired (Boolean) | N/A |
Main Thread APIs
All APIs below are blocking except for get_number_of_slaves().
| API | Description | Parameters | Returns |
|---|---|---|---|
get_ecat_master_ver() | Get EtherCAT master library version. | ver (u8 pointer), ver_len (uint) | rslt (u16) |
sys_rt_pre_opt_c() | System real-time optimization. Call once at the beginning of main thread. | N/A | N/A |
init_network() | Scan the network for slaves and place them in pre-op EtherCAT state. | N/A | u16 |
get_number_of_slaves() | Get number of slaves. Must be called after init_network. | N/A | u16 |
req_preop() | Place all slaves in pre-operational EtherCAT state. | N/A | u16 |
req_op() | Place all slaves in operational EtherCAT state. | N/A | u16 |
CoE Operations
| API | Description | Parameters | Returns |
|---|---|---|---|
coe_rd_u8() | CoE u8 read operation. | slv_idx, index (u16), sub_index (u8), data (u8 pointer) | rslt (u16) |
coe_wr_u8() | CoE u8 write operation. | slv_idx, index (u16), sub_index (u8), data (u8) | rslt (u16) |
coe_rd_u16() | CoE u16 read operation. | slv_idx, index (u16), sub_index (u8), data (u16 pointer) | rslt (u16) |
coe_wr_u16() | CoE u16 write operation. | slv_idx, index (u16), sub_index (u8), data (u16) | rslt (u16) |
coe_rd_u32() | CoE u32 read operation. | slv_idx, index (u16), sub_index (u8), data (u32 pointer) | rslt (u16) |
coe_wr_u32() | CoE u32 write operation. | slv_idx, index (u16), sub_index (u8), data (u32) | rslt (u16) |
CiA 402 Operations
| API | Description | Parameters | Returns |
|---|---|---|---|
set_cia402_op_mode() | Set slave to cyclic position mode. | slv_idx (uint), op_mode (u8) | rslt (u16) |
Appendix A: ECAT Result Error Codes
| Value | Description |
|---|---|
0x0000 | Success |
0x0001 | Version string length insufficient |
0x0002 | Invalid slave index |
0x0003 | Uninitialized slave index |
0x0004 | Uninitialized station address |
0x0005 | Working counter not incremented |
0x0006 | Frame receive timeout |
0x0007 | Frame command mismatch |
0x0008 | ESI file not found |
0x0009 | SM data cat section not found in SSI |
0x000A | Register response mismatch |
0x000B | SSI maximum byte length reached |
0x000C | Max retries reached while polling CoE SM1 response mbox ready status |
0x000D | CoE mbox emergency |
0x000E | CoE mbox abort code |
0x000F | CiA operational mode maximum retries reached |
0x0010 | EtherCAT command mismatch |
0x0FFF | Unspecified EtherCAT error |
Appendix B: Ethernet Driver Optimization
Maximum possible update rate of 4000 Hz (250 μs cycle time) is only supported on PCs with real-time Ethernet driver support. Specifically, this requires a PC with Linux OS and an Intel Ethernet LAN adapter using the igc Intel driver.
Supported Intel Ethernet PCIe cards:
I225-LM, I225-V, I225-I, I220-V, I225-K, I225-K2, I226-K, I225-LMVP, I226-LMVP, I225-IT, I226-LM, I226-V, I226-IT, I221-V