Run the MuSHR platform on your machine!

Beginner Tutorial | Expected duration is 30 minutes


This tutorial will get you started with MuSHR in simulation!


To get the simulator running on your machine so that you can begin hacking immediately!


A Ubuntu Linux machine. If you don't run linux natively then get a Ubuntu VM: OSX, Windows.

We also provide a virtual machine image that already has the MuSHR stack setup, it can be downloaded here. The username is robot and the password is prl_robot. If you use this image, you can start the VM and then skip to the Running the Simulator section.

Window Subsystem for Linux (WSL): There has also been success getting the quickstart to run using WSL. When running rivz you'll need to disable native opengl. There will be a note (Note for WSL) in the section running rviz.


First we need to make sure you have a few dependencies installed. All commands are to be executed in a terminal (CTRL + ALT + T). Here is what you need:

  • ROS Melodic Desktop Full (for Ubuntu 18.04) or ROS Kinetic (for Ubuntu 16.04) You could also try installing ROS on another supported platform, but as of right now this tutorial has not been tested on non-Ubuntu machines.
  • A catkin_ws
  • git:
$ sudo apt install git-all
  • tkinter:
$ sudo apt install python-tk
  • A github account. You can sign up for one here.
  • vcstool

Once you have these, you're good to go!

Install Sim

Now that we have the dependencies, lets get started! We'll start by making sure we have all the necessary ROS packages. Select one of the following, based off the version of ROS you installed.


$ sudo apt install -y ros-melodic-ackermann-msgs ros-melodic-map-server ros-melodic-serial ros-melodic-urg-node ros-melodic-robot-state-publisher ros-melodic-xacro


$ sudo apt install -y ros-kinetic-ackermann-msgs ros-kinetic-map-server ros-kinetic-serial ros-kinetic-urg-node ros-kinetic-robot-state-publisher ros-kinetic-xacro

Now, let's clone the necessary repos. First go to your catkin_ws/src directory:

$ cd ~/catkin_ws/src

Download repos.yaml into ~/catkin_ws/src.

And clone the necessary repos using vcstool:

$ vcs import < repos.yaml

We need the realsense2_description directory only:

$ mv ~/catkin_ws/src/mushr/mushr_hardware/realsense/realsense2_description ~/catkin_ws/src/mushr/mushr_hardware/realsense2_description
$ rm -rf ~/catkin_ws/src/mushr/mushr_hardware/realsense

We need to also install rangelibc. First, if you don't have Cython installed, install it now:

$ sudo pip install Cython 

Now that Cython's installed, you can install rangelibc:

$ cd ~/catkin_ws/src/range_libc/pywrapper
$ sudo python setup.py install
$ cd ~/catkin_ws/src && rm -rf range_libc

We will now run catkin_make to setup all the packages:

$ cd ~/catkin_ws && catkin_make

Setting up our environment

To make sure our environment is setup we run:

If you are using a shell other than bash, be sure to put these “source” commands in the analagous file for your shell.

Kinetic (Ubuntu 16.04)

$ echo 'source /opt/ros/kinetic/setup.bash' >> ~/.bashrc
$ echo 'source ~/catkin_ws/devel/setup.bash' >> ~/.bashrc
$ . ~/.bashrc

Melodic (Ubuntu 18.04)

$ echo 'source /opt/ros/melodic/setup.bash' >> ~/.bashrc
$ echo 'source ~/catkin_ws/devel/setup.bash' >> ~/.bashrc
$ . ~/.bashrc

Putting these lines in the ~/.bashrc guarantee they run on the startup of a new shell.

Finally, move the “Outrun” themed .rviz file to ~/.rviz to get our default setup:

$ cp ~/catkin_ws/src/mushr/mushr_utils/rviz/default.rviz ~/.rviz/

That's it! Time to run it.

Running the Simulator

To start the sim run:

$ roslaunch mushr_sim teleop.launch
Teleop window that should appear after starting the sim

Teleop window that should appear after starting the sim

And in another terminal window launch rviz:

$ rviz

**WSL Users Note:** In order for Open GL to find a display you'll need to do an extra step to get rviz to work. See Install VcXsrv to get it working.

The rviz window with the car model should appear (see below). Rviz is useful for visualizing what the car is thinking/seeing. Currently it is set to visualize the car, map, and laserscan but rviz can be used for much more.

This is an image of the rviz window that should pop up.

This is an image of the rviz window that should pop up.

Setting an Initial Position

Give the car an initial position by clicking

in rviz and clicking and dragging in the main window. Now you can click on the small gray window and use the WASD keys to drive the car around! You can set the position at any time to reset the pose.

The main pane will show a map of an empty square space. The ligher areas are the space where the simulated car can drive around. The darker areas are walls.

Clicking and dragging will change the perspective of rviz, while Shift + Click and draging will move the map around.

Going Further

To learn about programming the car, continue to the Intro to ROS Tutorial.


If you plan to use any part of the the MuSHR platform, including tutorials, codebase, or hardware instructions for a project or paper, please cite MuSHR: A Low-Cost, Open-Source Robotic Racecar for Education and Research :

 title={{M}u{SHR}: {A} Low-Cost, Open-Source Robotic Racecar for Education and Research},
 author={Srinivasa, Siddhartha S. and Lancaster, Patrick and Michalove, Johan and Schmittle, Matt and Summers, Colin and Rockett, Matthew and Smith, Joshua R. and Chouhury, Sanjiban and Mavrogiannis, Christoforos and Sadeghi, Fereshteh},