Skip to content

Installation Guide

This guide will walk you through setting up the SCARA ROS2 EtherCAT Workshop on your system.

System Requirements

Required Setup

  • Operating System: Ubuntu 24.04 LTS
  • ROS Distribution: ROS2 Jazzy
  • Disk Space: ~5 GB free space
  • Memory: 4 GB RAM minimum (8 GB recommended)

Prerequisites: EtherCAT Master and Driver

Before building the workshop, you must install:

  • IgH EtherLab EtherCAT Master (required for real EtherCAT hardware)
  • ethercat_driver_ros2 (ROS 2 EtherCAT driver stack)

Follow the EtherCAT Tutorial for detailed instructions, or use the summary below:

0. Install IgH EtherCAT Master

Follow the official guide: IgH EtherCAT Master Installation

1. Install ethercat_driver_ros2

You can build it from source in your ROS 2 workspace, or use the prebuilt Docker image (see Docker setup).

For source build, see the EtherCAT Tutorial for step-by-step instructions.

Step-by-Step Installation

1. Install ROS2 Jazzy

Follow the official ROS2 installation instructions for Ubuntu 24.04:

# Add ROS2 apt repository
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# Install ROS2 Jazzy Desktop
sudo apt update
sudo apt install ros-jazzy-desktop -y

For detailed instructions, visit the official ROS2 documentation.

2. Source ROS2 Environment

After installation, source your ROS2 environment:

source /opt/ros/jazzy/setup.bash

Auto-sourcing

If you're only using ROS2 Jazzy, add the source command to your ~/.bashrc file: 

echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc

3. Install Colcon

Colcon is the build tool for ROS2 workspaces:

sudo apt install python3-colcon-common-extensions

4. Create a ROS2 Workspace

Create a workspace directory for the tutorial:

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

5. Clone the Repository

Clone the workshop repository into your workspace:

cd ~/ros2_ws/src
git clone https://github.com/ICube-Robotics/ecat_ros2_workshop.git

6. Install Dependencies

Use rosdep to install all required dependencies:

cd ~/ros2_ws
sudo apt update
rosdep update
rosdep install --from-paths src --ignore-src -y -r

Note

If this is your first time using rosdep, you may need to initialize it: 

sudo rosdep init
rosdep update

7. Build the Workspace

Build the workspace using colcon:

cd ~/ros2_ws
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release --symlink-install

Build Options

  • --cmake-args -DCMAKE_BUILD_TYPE=Release: Optimizes the build for performance
  • --symlink-install: Creates symbolic links instead of copying files (useful during development)

8. Source the Workspace

After building, source the workspace:

source ~/ros2_ws/install/setup.bash

Auto-sourcing Workspace

Add this to your ~/.bashrc for automatic sourcing: 

echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

Verify Installation

Test that everything is installed correctly:

# Check if packages are available
ros2 pkg list | grep scara

# Launch the SCARA robot (should open RViz2)
ros2 launch scara_bringup scara.launch.py

If RViz2 opens with the SCARA robot displayed, your installation is successful! 🎉

Troubleshooting

Common Issues

Missing Dependencies

If you encounter missing dependencies during build:

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -y -r --rosdistro jazzy

Build Errors

If the build fails, try cleaning the workspace and rebuilding:

cd ~/ros2_ws
rm -rf build install log
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release --symlink-install

RViz2 Not Opening

If RViz2 doesn't open or displays errors:

# Install RViz2 if missing
sudo apt install ros-jazzy-rviz2

# Check OpenGL support
glxinfo | grep "OpenGL"

Getting Help

If you're still experiencing issues:

  1. Check the GitHub Issues
  2. Review the ROS2 troubleshooting guide
  3. Contact the maintainers (see Contacts)

Next Steps

Now that your environment is set up, you can:

Ready to start? Begin with the ros2_control Overview