Skip to main content

Getting Started

This tutorial will guide you step-by-step on how to set up the environment and install all dependencies.

Prerequisites​

warning

This tutorial assumes you are running on Ubuntu 24.04 LTS (Noble Numbat) on a native Linux machine or on Windows11 with WSL2.

1. Install ROS 2​

The official installation process is available at https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html. Following are the steps summarized to get started.

locale  # check for UTF-8

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

locale  # verify settings

1.2 Enable the Universe repository​

sudo apt install software-properties-common
sudo add-apt-repository universe

1.3 Add the ROS 2 apt repository​

sudo apt update && sudo apt install curl -y
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb

1.4 Install development tools​

sudo apt update && sudo apt install ros-dev-tools

1.5 Update system packages​

sudo apt update
sudo apt upgrade

1.6 Install ROS 2 Jazzy Desktop​

sudo apt install ros-jazzy-desktop

1.7 Source the environment​

tip

Add the ROS 2 setup script to your shell profile so it loads automatically in every new terminal:

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

1.8 Verify the installation​

note

You can skip this step — come back to it only if something isn't working as expected.

Open two terminals and run the classic talker–listener demo:

Terminal 1 — C++ talker:

source /opt/ros/jazzy/setup.bash
ros2 run demo_nodes_cpp talker

Terminal 2 — Python listener:

source /opt/ros/jazzy/setup.bash
ros2 run demo_nodes_py listener

You should see the talker publishing messages and the listener printing I heard: [...]. Installation is successful.

2. Install ROS 2 Dependencies​

The control pipeline of the robot requires the following packages to be installed.

sudo apt update
sudo apt install -y \
  ros-jazzy-moveit \
  ros-jazzy-pinocchio \ 
  ros-jazzy-ros2-control \
  ros-jazzy-ros2-controllers \
  ros-jazzy-joint-state-publisher \
  ros-jazzy-joint-state-publisher-gui \
  ros-jazzy-robot-state-publisher
note

If you are running on a native Linux machine, or you just want to test out the simulation examples, you can skip to the next page.

3. Windows Users with WSL2 (continue)​

When using WSL 2, USB devices (including serial/COM ports) are not accessible by default. The usbipd-win tool bridges this gap by forwarding USB devices from Windows into the WSL environment.

3.1 Install usbipd-win in PowerShell (as Administrator)​

Open PowerShell as Administrator and run:

winget install --interactive --exact dorssel.usbipd-win

A firewall rule named usbipd is created automatically, allowing connections on TCP port 3240. If you use a third-party firewall, ensure this port is permitted.

3.2 Install USB/IP tools inside WSL (Ubuntu)​

Inside your WSL Ubuntu terminal:

sudo apt update
sudo apt install -y linux-tools-virtual hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip \
  /usr/lib/linux-tools/*/usbip 20

3.3 Connect a COM device — step by step​

Step 1 — Plug in your USB/serial device to the Windows host.​

Step 2 — List all connected USB devices (PowerShell as Administrator):​

usbipd list

You will see output like:

BUSID  VID:PID    DEVICE                          STATE
1-3    0403:6001  USB Serial Converter             Not shared
2-1    046d:c52b  USB Input Device                 Not shared

Find your COM device (e.g., FTDI, CH340, CP210x) and note its BUSID.

Step 3 — Bind (share) the device — requires Administrator:​

usbipd bind --busid <BUSID>
# Example:
usbipd bind --busid 1-3

Binding is persistent — you only need to do this once per device, even after reboots.

Step 4 — Attach the device to WSL (PowerShell, no Administrator required after bind):​

usbipd attach --wsl --busid <BUSID>
# Example:
usbipd attach --wsl --busid 1-3

Step 5 — Verify inside WSL:​

lsusb        # check the device appears
ls /dev/ttyUSB*   # or /dev/ttyACM* depending on the device

Your device will typically appear as /dev/ttyUSB0 or /dev/ttyACM0.

Step 6 — Grant serial port permissions (WSL):​

sudo chmod 666 /dev/ttyUSB0
# Or add your user to the dialout group (permanent):
sudo usermod -aG dialout $USER

Log out and back in (or restart WSL) for the group change to take effect.

3.4 Detach the device when done (PowerShell)​

usbipd detach --busid <BUSID>

After a reboot or if the device is replugged, you must run usbipd attach again. The bind step does not need to be repeated.

3.5 Auto-attach on reconnect (optional)​

usbipd attach --wsl --busid <BUSID> --auto-attach

This keeps the device attached to WSL and automatically re-attaches if it resets or is replugged (useful for microcontrollers that reset on flash).