Environment Setup Guide

Target Stack

• Windows 10/11
• WSL 2
• Ubuntu 24.04 LTS
• ROS 2 Jazzy
• Gazebo Harmonic

Notes:

• Please select branch -version1
• Do not install gazebo or gazebo11
• gazebo refers to Gazebo Classic, not Gazebo Harmonic

---

1. Install WSL

Open PowerShell as Administrator and run:

wsl --install

Check WSL status:

wsl --status
wsl --version

Set WSL 2 as default:

wsl --set-default-version 2

Update WSL if needed:

wsl --update

---

2. Install Ubuntu 24.04

List available distributions:

wsl --list --online

Install Ubuntu 24.04:

wsl --install -d Ubuntu-24.04

If the download gets stuck:

wsl --install --web-download -d Ubuntu-24.04

Launch Ubuntu:

wsl -d Ubuntu-24.04

On first launch, create your Linux username and password.

Check Ubuntu version:

lsb_release -a
uname -a

---

3. Update Ubuntu

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl gnupg lsb-release software-properties-common locales

---

4. Configure Locale

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

---

5. Install ROS 2 Jazzy

Enable the universe repository:

sudo add-apt-repository universe
sudo apt update

Add the ROS 2 apt source:

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

Install ROS 2 Jazzy:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ros-jazzy-desktop ros-dev-tools

Load ROS automatically:

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

Verify ROS:

printenv ROS_DISTRO
which ros2
ros2 topic -h

Expected:

• ROS_DISTRO = jazzy
• ros2 exists in /opt/ros/jazzy/bin/ros2

---

6. Install Gazebo Harmonic

Add the Gazebo apt source:

sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] https://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt update

Install Gazebo Harmonic:

sudo apt install -y gz-harmonic

Install ROS-Gazebo integration:

sudo apt install -y ros-jazzy-ros-gz

Verify Gazebo:

which gz
gz sim --version

---

7. Launch Gazebo

Launch Gazebo directly:

gz sim

Launch an empty world:

gz sim empty.sdf

Launch Gazebo from ROS:

ros2 launch ros_gz_sim gz_sim.launch.py gz_args:=empty.sdf

---

8. Environment Variables

Recommended ~/.bashrc entries:

source /opt/ros/jazzy/setup.bash
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Reload:

source ~/.bashrc

---

9. Useful Checks

WSL:

wsl --status
wsl --version
wsl --list --verbose

Ubuntu:

lsb_release -a

ROS:

printenv ROS_DISTRO
which ros2
ros2 topic list

Gazebo:

which gz
gz sim --version

---

10. Common Issues

WSL install stuck:

wsl --shutdown
wsl --update
wsl --install --web-download -d Ubuntu-24.04

Wsl/InstallDistro/0x80072f78:

• switch network
• disable proxy or filtering software
• retry with --web-download

ros2 --version fails:

• this is normal
• use printenv ROS_DISTRO, which ros2, or ros2 topic -h

gz: command not found:

• Gazebo Harmonic is not installed correctly
• repeat Section 6

Gazebo GUI does not open in WSL:

• check WSLg
• update WSL
• check graphics driver support

---

11. Final Verification

Run:

printenv ROS_DISTRO
which ros2
which gz
gz sim --version
ros2 launch ros_gz_sim gz_sim.launch.py gz_args:=empty.sdf

Expected:

• ROS 2 Jazzy is available
• Gazebo Harmonic is available
• Gazebo launches correctly

---

12. Build the Workspace and Launch Simulation

After the environment is ready, use the following workflow to build the ROS 2 workspace and launch the simulation scenes.

12.1 Install colcon

If colcon is not installed yet, run:

sudo apt update
sudo apt install -y python3-colcon-common-extensions

Verify:

colcon --help

12.2 Build the Workspace

Go to your ROS 2 workspace root directory:

cd ~/your_ws

Build the packages:

colcon build

12.3 Source the Workspace

After building, refresh the environment:

source install/setup.bash

If needed, run the ROS global setup first:

source /opt/ros/jazzy/setup.bash
source install/setup.bash

12.4 Launch the Simulation Scenes

Run the required launch file after sourcing the workspace.

Scene 1: Elevator Area

ros2 launch hmi_scene scene_state_publishers.launch

Scene 2: Open Field

ros2 launch hmi_scene open_area_scene.launch

12.5 Recommended Launch Workflow

Use the following order each time:

cd ~/your_ws
source /opt/ros/jazzy/setup.bash
colcon build
source install/setup.bash
ros2 launch hmi_test experiment_logger.launch.py
ros2 launch hmi_scene open_area_scene.launch

or

cd ~/your_ws
source /opt/ros/jazzy/setup.bash
colcon build
source install/setup.bash
ros2 launch hmi_test experiment_logger.launch.py
ros2 launch hmi_scene scene_state_publishers.launch