yarp-device-ethercat-CiA402 🚀

Overview 🌟

This repository provides a YARP device plugin for EtherCAT CiA402 drives.

Compilation 🛠️

Prerequisites 📋

Ensure the following dependencies are installed:

• CMake (version 3.8 or higher)
• YARP
• SOEM
• toml++ (TOML parser for C++)

Note: This device has been tested only on Linux systems.

Build Steps 🧩

1. Clone the repository:

   git clone https://github.com/ami-iit/yarp-device-ethercat-cia402.git
   cd yarp-device-ethercat-cia402

2. Create a build directory and navigate into it:

   mkdir build && cd build

3. Configure the project with CMake:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/install

4. Build the project:

   make

5. Install the plugin:

   make install

Usage 🚀

Running the Plugin 🏃‍♂️

After building the project, the plugin can be loaded into a YARP-based application. Make sure the YARP_DATA_DIRS environment variable includes the path to the plugin's configuration files:

export YARP_DATA_DIRS=/path/to/install/share/yarp:$YARP_DATA_DIRS

Configuration ⚙️

The plugin requires a configuration file defining the EtherCAT network and device parameters. An example can be found at: config/robot/template_1_motor/config.xml

To select the drive internal position controller structure, configure:

• use_simple_pid_mode — boolean. When true the driver sets 0x2002:00 = 1 (Simple PID); when false it sets 0x2002:00 = 2 (Cascaded PID).

To program simple PID gains (only meaningful when use_simple_pid_mode=true), provide:

• simple_pid_kp_nm_per_deg — list of joint-side Kp values in Nm/deg
• simple_pid_kd_nm_s_per_deg — list of joint-side Kd values in Nm*s/deg

The two gain keys are optional as a pair: if exactly one of them is provided the driver errors out.

When both are present (and use_simple_pid_mode=true) the device converts them to the drive units (mNm/inc and mNm*s/inc), and writes 0x2012:01..03 with Ki clamped to zero. If use_simple_pid_mode=false, any simple_pid_* keys are ignored (with a warning) to avoid programming/printing 0x2012 with the wrong unit interpretation.

See doc/protocol_map.md for the conversion details.

Setting Up yarprobotinterface 🛠️

To ensure that the yarprobotinterface binary has the correct permissions and can locate its dependencies, execute:

patchelf --add-rpath $(dirname $(dirname $(which yarprobotinterface)))/lib $(which yarprobotinterface)
sudo setcap cap_net_raw,cap_net_admin+ep $(which yarprobotinterface)

Example 💡

To run the plugin with a specific configuration:

yarprobotinterface --config config/robot/template_1_motor/config.xml

Supported Drives 🛠️

This plugin has been primarily tested with Synapticon drives. While it may be compatible with other EtherCAT drive models or manufacturers, some modifications might be necessary to ensure proper functionality. This is due to the plugin’s use of a custom Process Data Object (PDO) mapping, which extends beyond the standard CiA402 specification.

If you're looking to adapt the plugin for different hardware, we encourage you to open an issue or contribute improvements.

Additional notes 📝

For more details, see:

• Protocol map — PDOs, SDOs, and conversion formulas: doc/protocol_map.md
• Modes and setpoints — available control modes and targets: doc/modes_and_setpoints.md
• Dual encoder handling — mounts, sources, and transformations: doc/dual_encoder_handling.md

License 📜

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.