Quickstart

Run the MuSHR platform on your machine!

Beginner Tutorial | Expected duration is 30 minutes


Introduction

This tutorial will get you started with MuSHR in simulation!

Goal

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

Requirements

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

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.

Setup

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.

Melodic:

$ 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

Kinetic:

$ 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 the Paul G. Allen Basement at the University of Washington. The ligher areas are hallways and rooms 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.

Citation

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 :

@article{srinivasa2019mushr,
 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},
 journal={CoRR},
 volume={abs/1908.08031},
 year={2019}
}