> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4-ros2-repo/stretch_simulation/readme_setup.md).

# Setting up Stretch Simulation

You should go through all the sections in this setup guide to run this package correctly.

> NOTE: If you are running on a Stretch robot, you can skip to [Setting up Mujoco](#setting-up-mujoco-15-minutes)

> NOTE: If you are on Linux or Windows, you can use the [Docker setup](/stretch4-ros2-repo/stretch_simulation/readme_docker.md) to get started using Docker with hardware acceleration.

Estimated install time: `~1-2hrs`.

## Install ROS2 Jazzy (10 minutes)

> NOTE: Please do not run this step if you are running on a Stretch robot.

The commands below are taken from this guide: <https://docs.ros.org/en/jazzy/index.html>

```shell
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

sudo apt update

sudo apt install ros-jazzy-desktop ros-jazzy-rmw-zenoh-cpp ros-dev-tools rviz python3-pip

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

## Setting up `ament_ws` (1 hour)

> NOTE: Please do not run this step if you are running on a Stretch robot.

If you are not running this package on a robot NUC (which is *not* [recommended](#system-requirements)), you will need to set up a ROS2 environment similar to the environment that ships with Stretch.

Please run these commands to install the environment. This will delete the existing `~/ament_ws` directory, so please proceed with caution.

First you should install `NodeJS>=21.x` and `npm` if you don't already have them:

```shell
curl -sL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
```

```sh

curl -sL https://raw.githubusercontent.com/hello-robot/stretch4_ros2/refs/heads/jazzy/stretch_simulation/stretch_ros2_jazzy.repos > /tmp/stretch_ros2_jazzy.repos
curl -sL https://raw.githubusercontent.com/hello-robot/stretch4_ros2/refs/heads/jazzy/stretch_simulation/stretch_create_ament_workspace.sh > /tmp/stretch_create_ament_workspace.sh
sudo bash /tmp/stretch_create_ament_workspace.sh


# Optional: add source install/setup.bash to .bashrc:
echo 'source ~/ament_ws/install/setup.bash' >> ~/.bashrc
```

> Note: If you run into a colcon build error: "fatal error: numpy/ndarrayobject.h: No such file or directory", run `sudo ln -s ~/.local/lib/python3.10/site-packages/numpy/core/ /usr/include/numpy` to resolve it.

A successful `ament_ws` setup will look like this:

```
$ ls ~/ament_ws/src
airy_lidar_filter_cpp  depthai-core  depthai-ros  ros2_numpy   stretch4_ros2  stretch4_web_teleop
```

## Setting up URDF (15 minutes)

Run the commands below or follow the instruction in the [`stretch_description #updating-the-urdf`](/stretch4-ros2-repo/stretch_description.md#updating-the-urdf) README file to set up the URDF meshes.

```shell
source ~/ament_ws/install/setup.bash

git clone https://github.com/hello-robot/stretch4_urdf.git --depth 1 /tmp/stretch4_urdf

cd /tmp/stretch4_urdf
pip install -e .
```

A successful URDF update will look like this:

```
$ ls ~/ament_ws/src/stretch4_ros2/stretch_description/urdf/
d405                             stretch_aruco.xacro     stretch_description_SE3_eoa_wrist_dw3_tool_nil.xacro          stretch_head_nav_cam.xacro        stretch_tool_sg3.xacro
d435i                            stretch_base_imu.xacro  stretch_description_SE3_eoa_wrist_dw3_tool_sg3.xacro          stretch_laser_range_finder.xacro  stretch_tool_tablet_12in.xacro
export_urdf_license_template.md  stretch_d405_sg3.xacro  stretch_description_SE3_eoa_wrist_dw3_tool_tablet_12in.xacro  stretch_main.xacro                stretch_uncalibrated.urdf
export_urdf.sh                   stretch_d435i.xacro     stretch_description.xacro                                     stretch_respeaker.xacro           stretch_wrist_dw3.xacro
```

## Setting up Mujoco (15 minutes)

This ROS 2 package includes nodes and launch files that use the [`stretch4_mujoco`](https://github.com/hello-robot/stretch4_mujoco) repo to interface with Mujoco.

Run the following, after having done the previous ament\_ws setup steps, to start interacting with Stretch in Mujoco using ROS 2:

```shell
pip3 install --upgrade pip #This is important after a fresh install of Ubuntu, for edittable installation of dependencies

source ~/ament_ws/install/setup.bash

# Set-up script to install mujoco and dependencies:
# Note: if you get an externally managed environment error, first run:export PIP_BREAK_SYSTEM_PACKAGES=1
bash ~/ament_ws/src/stretch4_ros2/stretch_simulation/stretch_mujoco_driver/setup.bash

pip install pyquaternion PyOpenGL==3.1.4 # Fixes AttributeError: module 'OpenGL.EGL' has no attribute 'EGLDeviceEXT'

cd ~/ament_ws
source ./install/setup.bash
colcon build
ros2 launch stretch_simulation stretch_mujoco_driver.launch.py mode:=navigation
```

## Setting up Stretch Web Teleop

Make sure you've already completed everything under [Setting up `ament_ws`](#setting-up-ament_ws) above.

Run the following commands to get IK for the gripper working:

```shell
cd stretch_description/urdf
cp ./stretch_uncalibrated.urdf stretch.urdf

sudo apt install rpl
./export_urdf.sh # It's okay if it fails on calibrated params

mkdir -p $HELLO_FLEET_PATH/$HELLO_FLEET_ID/exported_urdf
cp -r ./exported_urdf/* $HELLO_FLEET_PATH/$HELLO_FLEET_ID/exported_urdf
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hello-robot.com/stretch4-ros2-repo/stretch_simulation/readme_setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.