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!
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
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
$ sudo apt install git-all
$ sudo apt install python-tk
Once you have these, you're good to go!
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
$ cd ~/catkin_ws/src
Download repos.yaml into
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
And in another terminal window launch 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.
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.
Setting an Initial Position
Give the car an initial position by clicking
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
Shift + Click and draging will move the map around.
To learn about programming the car, continue to the Intro to ROS Tutorial.