search

ethz-msrl / ethercat_ros_configurator

EtherCAT ROS Configurator
BSD 3-Clause "New" or "Revised" License
1 stars 0 forks source link

readme

EtherCAT ROS Configurator

This package acts as a configurator for EtherCAT device SDKs built on top of the ethercat_sdk_master package. This package provides a seamless software architecture to add new ethercat slave device classes and configure them with a ROS backend for easy integration and multhreading for asynchronous update of the command and feedback data through ROS messages. Furthermore, this package provides a simple way to configure an EtherCAT network with multiple slave devices through a single yaml configuration file.

Table of Contents

Installation

This package is supposed to be used as a ROS package for a catkin work space. Therefore, knowledge of the catkin build system and workspaces is assumed for the rest of the sections. If you are not familiar with catkin, please refer to the ROS wiki and Catkin Tutorials for more information. Note that the package is tested under the following conditions:

Step 1: Installing Dependencies

The following packages are required to be installed in your system in order to use this package:

ROS Noetic

For installing ROS Noetic in Ubuntu 20.04 LTS, please refer to the ROS Noetic Installation Guide. The packages have not been tested for ROS installations in other environments like WSL, Raspberry Pi, etc, therefore, user discretion is advised. Feel free to open an issue if you encounter any problems with other distributions, but receiving support for other distributions is not guaranteed.

Catkin Tools

To use the catkin build command, you need to install the catkin_tools package. You can install it by running the following command:

sudo pip3 install -U catkin_tools

For more information and alternative installation methods, please refer to the catkin_tools Installation Guide.

Message Logger

The message logger package provides a simple way to log messages to the console and to a file. Add the package to your workspace by running the following commands:

cd /path/to/your/catkin/workspace/src
git clone https://github.com/leggedrobotics/message_logger.git
cd message_logger
git checkout bdb867e

For the specific version of the package used while testing alongwith the installation instructions, goto message_logger.

SOEM Interface

The SOEM Interface package provides a ROS wrapper for the SOEM Library. Add the package to your workspace by running the following commands:

cd /path/to/your/catkin/workspace/src
git clone https://github.com/leggedrobotics/soem_interface.git
cd soem_interface
git checkout 7b7bed2

The specific version of the package used while testing can be found at soem_interface. At the time of writing this readme, the latest version of the package should work, if it fails, checkout the specific commit hash in the link after cloning the repository.

EtherCAT SDK Master

This package presents a nice base class for implementation of EtherCAT slave devices by providing high level EtherCAT functionalities over the SOEM Library. Add the package to your workspace by running the following commands:

cd /path/to/your/catkin/workspace/src
git clone https://github.com/leggedrobotics/ethercat_sdk_master.git
cd ethercat_sdk_master
git checkout 6b420bc

The specific version of the package used while testing can be found at ethercat_sdk_master.

EtherCAT Motor Messages

The EtherCAT Motor Messages package provides a set of ROS messages for EtherCAT motor controllers. Add the package to your workspace by running the following commands:

cd /path/to/your/catkin/workspace/src
git clone https://github.com/ethz-msrl/ethercat_motor_msgs

Yaml-CPP

The package uses the yaml-cpp library for parsing the YAML configuration files. Version 0.6 of the library is installed by default in Ubuntu 20.04 LTS. However, you should be able to install it by running the following command:

sudo apt-get install libyaml-cpp0.6

Step 2: Install Device SDKs

Several supported device SDKs are available for use with this package. The device SDKs are built on top of the ethercat_sdk_master package. The device SDKs are available as separate packages and can be installed by following the instructions in the respective package's readme. Installing them usually just boils down to cloning the respective device SDK's repository and installing any dependencies mentioned in their installation instructions.

N.B.: some dependencies mentionned are already installed in Step 1, in which case ignore the instruction to clone these in the SDK repo.

Make sure that the device SDKs can be found by the cmake find_package() command in CMakeLists.txt.

Supported Device SDKs

The following device SDKs are supported:

SDK Name URL Type Description License Registration Name
Nanotec EtherCAT SDK https://github.com/ethz-msrl/nanotec_ethercat_sdk Motor Controller Designed for Nanotec C5E-1-21 motor controller BSD-3-Clause Nanotec
Maxon EPOS EtherCAT SDK https://github.com/ethz-msrl/maxon_epos_ethercat_sdk Motor Controller Designed for Maxon EPOS4 motor controller BSD-3-Clause Maxon

This list will be updated as more device SDKs are added to the package. Follow the installation instructions in the respective device SDK's readme to add it to your catkin workspace.

Step 3: Install EtherCAT ROS Configurator

Finally, clone this repository into your catkin workspace and build the workspace. You can do this by running the following commands:

cd /path/to/your/catkin/workspace/src
git clone git@github.com:ethz-msrl/ethercat_ros_configurator.git
cd ..
catkin build ethercat_ros_configurator
source devel/setup.bash

Note that the device SDK packages only compiles the class object for a device if its SDK is found by cmake. Check out the warning messages in the build log to see which SDKs were found by cmake. For example: if the Nanotec and the Maxon SDKs are found, the following is the output of the build log:

Starting  >>> ethercat_ros_configurator                                                                                                                                        
_______________________________________________________________________________________________________________________________________________________________________________
Warnings   << ethercat_ros_configurator:cmake /home/neelaksh/ethercat_ws/logs/ethercat_ros_configurator/build.cmake.000.log                                                    
Found EtherCAT device sdk: maxon_epos_ethercat_sdk
Found EtherCAT device sdk: nanotec_ethercat_sdk
cd /home/neelaksh/ethercat_ws/build/ethercat_ros_configurator; catkin build --get-env ethercat_ros_configurator | catkin env -si  /usr/bin/cmake /home/neelaksh/ethercat_ws/src/ethercat_ros_configurator --no-warn-unused-cli -DCATKIN_DEVEL_PREFIX=/home/neelaksh/ethercat_ws/devel/.private/ethercat_ros_configurator -DCMAKE_INSTALL_PREFIX=/home/neelaksh/ethercat_ws/install; cd -

...............................................................................................................................................................................
_______________________________________________________________________________________________________________________________________________________________________________

Usage Instructions

Before following the instructions below, make sure you have built your catkin workspace alongwith the SDKs of all the EtherCAT devices you intend to use. The following steps will guide you through the process of using the package to configure your EtherCAT network. The EtherCAT ros configurator prepares a network of devices through the config/setup.yaml file. An example of the setup file for an EtherCAT bus with 2 Nanotec C5E-1-21 motor drivers followed by a Maxon EPOS4 driver is given below:

ethercat_master:
  time_step:                          0.002 # in seconds
  update_rate_too_low_warn_threshold: 50 # in Hz
  ros_namespace:                      ethercat_master

ethercat_devices:
  - type:               Nanotec # Registration Name of the device SDK
    name:               Nanotec_Motor_1 # Name of the device, should be unique for each device. Used for ROS topics.
    configuration_file: device_configurations/nanotec_1.yaml # Path to the configuration file for the device
    ethercat_bus:       eth0 # eth0 usually
    ethercat_address:   1 # Address of the device on the bus, should be unique for each device
    thread_frequency:   100 # in Hz
    initial_mode_of_operation: 8 # Check mode maps in the SDK docs or device .cpp file

  - type:               Nanotec
    name:               Nanotec_Motor_2
    configuration_file: device_configurations/nanotec_2.yaml
    ethercat_bus:       eth0
    ethercat_address:   2
    thread_frequency:   100
    initial_mode_of_operation: 8

  - type:               Maxon
    name:               Maxon_Motor_1
    configuration_file: device_configurations/maxon_1.yaml
    ethercat_bus:       eth0
    ethercat_address:   3
    thread_frequency:   100
    initial_mode_of_operation: 8

ethercat_master Section

The ethercat_master section contains the configuration for the EtherCAT master. The time_step parameter is the time step for the EtherCAT master in seconds. In the example YAML the master is configured to run at 500 Hz, the package has been tested at 1000 Hz (time step of 0.001 secs) too. The update_rate_too_low_warn_threshold parameter is the threshold time for the warning message when the update rate of the EtherCAT master is too low. The ros_namespace parameter is the namespace for the EtherCAT master. All the device topics will be published or subscribed to under this namespace.

ethercat_devices Section

This section lists the devices connected to the EtherCAT network. Each device is represented as a dictionary with the following keys:

Important Note On EtherCAT Address

The address 0 is reserved for the EtherCAT master. The EtherCAT address value for all slaves is supposed to be in the range of 1 to 65535 (16 bits). Therefore, one master can support upto 65535 devices. Note that, addresses define which parameters get associated with which device. Addresses are always assigned in a way that the device closest to the master gets the smallest address, the next device gets the smallest address after that and so on. This means, that in the list of device dictionaries in the ethercat_devices section, the address value order of the devices should follow the physical wiring order (topological position) of the devices on the bus. Otherwise, you may end up assigning the wrong device class, and the wrong settings to the wrong device which may lead to failure or unexpected behavior. For example, if the address of the Maxon motor is changed to 2 while that of the 2nd Nanotec motor is changed to 3, then the master node will try to create a slave of type Maxon at address 2 for the 2nd Nanotec motor, which will lead to failure. Therefore, it is important to ensure that the address values are assigned according to the correct topological order.

Command and Feedback Data

At the time of writing, the package is only configured for motor controllers. The package provides a simple way of updating the command and receiving the feedback data through ROS messages. The command and feedback data is updated asynchronously through the worker threads of the device classes. For each device, 2 ROS topics are created:

Wiring The EtherCAT Network

Check the EtherCAT installation guide for more details on setting up the physical connections between the devices and a ROS enabled PC.Please note a Ethernet port should be available on the ROS machine. A basic linear bus connection topoloy is achieved as follows: One ethernet wire is connected from the ROS machine's Ethernet port to the "input" EtherCAT port of the first device. Then the "output" EtherCAT port of the first device is connected to the "input" EtherCAT port of the second device and so on. This is continued until the last device is reached whose "output" port is left unconnected. The dangling "output" port is handled internally by the EtherCAT communication protocol. A sample diagram of such a connection topology is given below:

Image Source: Acontis Technologies. The reader is encouraged to refer to this link for gaining a better understanding of the EtherCAT communication protocol.

Note that the network might benefit from circular connection topologies because of one layer of redundancy against phyical connection faults. However, this would require two ports in the ROS machine to serve as a part of the same EtherCAT bus; however, this is not supported by the package at the time of writing.

Usage

Root Access Requirement

Please note that running the EtherCAT master node requires root privilages because of the low level access to the Ethernet port. One way to achieve this is to launch the node while logged in as root in the terminal. This will require sourcing the ROS environment variables in the root shell. Sourcing the ROS environment in root shell is not recommended. A better way to achieve this will be through implementing a ethercat_grant like functionality in the package. This is not a feature of the package as of this release.

TODO: implement ethercat_grant.

Running the ROS node

After setting up the config/setup.yaml file, you can run the ROS node as follows (assumes a ROS master is already running):

(TO TEST)

sudo -i
cd <your_catkin_workspace>
source /opt/ros/noetic/setup.bash
source devel/setup.bash
rosrun ethercat_ros_configurator ethercat_ros_node <path_to_config_file>

Replace <path_to_config_file> with the path to the config/setup.yaml file. The path can either be absolute, or can be relative to the current bash working directory when launching the rosnode.

To run the example script, use: 

roslaunch ethercat_ros_configurator test_reference.launch

API Documentation & Contributing To The Project

Refer to the following url for detailed information on how to integrate a new device SDK with the package, and to understand important implementation details as a device SDK developer: EtherCAT ROS Configurator API Documentation.

We aim to make EtherCAT devices more accessible to the open source robotics community since it allows to leverage the best real-time control capabilities of several actuators and all the benefits of the EtherCAT communnication protocol. Therefore, contributions to this package are wholeheartedly welcome! Please adhere to the contributor covenant while making contributions to this package. Strict actions will be taken against deviants.

EtherCAT ROS Configurator uses the EtherCAT master generation and handling capabilities of the EtherCAT Device Configurator package. EtherCAT ROS Configurator is in no way involved with or supported by the creators of EtherCAT Device Configurator.