Computer Setup


Setup Checklist

Complete all of the following steps to setup your Intro Robotics programming environment:

Choose/Setup Your Programming Environment

For this course, the most ideal programming environment is the Ubuntu 20.04 Operating System. There are many ways to configure an Ubuntu 20.04 programming environment (virtual machines, an Ubuntu 20.04 partition on your laptop). Additionally, you can use ROS outside Ubuntu (ROS for Windows, ROS2, ROS through Windows Subsystem for Linux). Here are our recommendations for configuring your programming environment based on the native operating system of your computer:


ROS Installation

(Skip this section you're using the VirtualBox Ubuntu VM - it already has ROS installed)

ROS Installation

Follow these instructions to install ROS Noetic, installing ros-noetic-desktop-full.

Installing the Necessary Dependencies for ROS and Turtlebot3

These instructions are based on those found on the ROBOTIS website. Install these necessary ROS dependencies:

$ sudo apt-get install ros-noetic-joy ros-noetic-teleop-twist-joy ros-noetic-teleop-twist-keyboard ros-noetic-laser-proc ros-noetic-rgbd-launch ros-noetic-rosserial-arduino ros-noetic-rosserial-python ros-noetic-rosserial-client ros-noetic-rosserial-msgs ros-noetic-amcl ros-noetic-map-server ros-noetic-move-base ros-noetic-urdf ros-noetic-xacro ros-noetic-compressed-image-transport ros-noetic-rqt-image-view ros-noetic-gmapping ros-noetic-navigation ros-noetic-interactive-markers
$ sudo apt-get install ros-noetic-ros-control*
$ sudo apt-get install ros-noetic-control* -o Dpkg::Options::="--force-overwrite"
$ sudo apt-get install ros-noetic-moveit*

Setting Up Your Catkin Workspace

Creating Your catkin_ws

These instructions are based on this ROS tutorial page. Carry out the following commands: 

$ source /opt/ros/noetic/setup.bash
$ mkdir -p ~/catkin_ws/src
$ cd ~/catkin_ws/
$ catkin_make

Then, add the source catkin_ws/devel/setup.bash command to your ~/.bashrc file. 

$ echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
Note: Every time you run the catkin_make command or open a new terminal, you'll need to source the catkin_ws/devel/setup.bash file, which is why we're adding it to the ~/.bashrc file.

To ensure that you've set up your catkin workspace properly: 1) close your current terminal window, 2) open a new terminal window, and 3) enter the command roscd. If you've set up your catkin workspace correctly, you should now be in the directory ~/catkin_ws/devel.

Turtlebot3 ROS Setup

Next, navigate to your catkin workspace's src folder and clone the necessary git repositories used for the Turtlebot3: 

$ cd ~/catkin_ws/src
$ git clone https://github.com/ROBOTIS-GIT/turtlebot3_msgs.git
$ git clone -b noetic-devel https://github.com/ROBOTIS-GIT/turtlebot3.git
$ git clone https://github.com/ROBOTIS-GIT/turtlebot3_simulations.git
$ git clone -b develop https://github.com/ROBOTIS-GIT/turtlebot3_manipulation.git
$ git clone https://github.com/ROBOTIS-GIT/turtlebot3_manipulation_simulations.git
$ git clone https://github.com/ROBOTIS-GIT/open_manipulator_dependencies.git

Finally, run the catkin_make command within your catkin workspace, source the devel/setup.bash file, and set your default turtlebot3 model to the waffle pi. 

$ cd ~/catkin_ws && catkin_make
$ source devel/setup.bash
$ echo "export TURTLEBOT3_MODEL=waffle_pi" >> ~/.bashrc

You can test to ensure that you've installed all of the Turtlebot3 packages and dependencies by trying out a built-in teleoperation demo of the Turtlebot3 in a simulated house environment. You'll need to run the following commands in 3 separate terminal windows (or terminal tabs).

Terminal 1: 

$ roscore

Terminal 2: 

$ roslaunch turtlebot3_gazebo turtlebot3_house.launch

You should now see a Turtlebot3 waffle (without the arm) within a simulated house environment:

Topics in HRI

Terminal 3: 

$ roslaunch turtlebot3_teleop turtlebot3_teleop_key.launch

Follow the directions in the terminal to teleoperate your simulated turtlebot3!

Class Repo/Package Setup

In the last step, we setup the the class repository. The class package is where you will place your scripts and use common course utilities. Navigate to your catkin workspace's src folder, clone the class repository and pull all of its submodules:

$ cd ~/catkin_ws/src
$ git clone https://github.com/Intro-Robotics-UChicago-Spring-2022/intro_robo.git
$ cd intro_robo
$ git submodule update --init --recursive

Then, similar to before, run the catkin_make command within your catkin workspace and source the devel/setup.bash file. 

$ cd ~/catkin_ws && catkin_make
$ source devel/setup.bash

The class repository contains several important catkin packages:

We will update the class package throughout the course to add new class meeting packages. Hence, you should update this package and build it prior to each class meeting. You can do so via the following commands:

$ cd ~/catkin_ws/src/intro_robo
$ git submodule update --init --recursive
$ cd ~/catkin_ws && catkin_make
$ source devel/setup.bash

Setting Up Your IDE

Recommended IDE

We recommend using VSCode to develop ROS applications. The autocomplete features from VSC extensions are very helpful when first learning rospy.

These are the extensions that we found helpful:

Here's also a guide to managing extensions in VSCode.


Hints & Tricks

If you are unfamiliar with Ubuntu or Gnome, we recommend that you take some time to familiarize with the user interface and the functionalities. Here is a short intro the gnome desktop. Additionally, students in the past have found the following tidbits helpful,


Setting Up an Ubuntu Virtual Machine (VM) with VirtualBox

Setup

To get started with an Ubuntu VM, you'll first need to download VirtualBox, an open-source virtualization program available on most major operating systems. You can download the appropriate version for your machine here, under "VirtualBox platform packages". Once downloaded, follow the installation wizard provided by VirtualBox.

Loading In the VM Files

Once VirtualBox is installed, you can now load in the Ubuntu VM we've created for this class. Follow these steps:

  1. Download both the .vmdk and .ovf file from this link. Make sure both files are downloaded to the same directory.
  2. Open the VirtualBox GUI. At the top menu bar, navigate to File > Import Appliance.
  3. In the popup window, locate the directory where your .ovf file is saved and import it into the blank "File:" field. Press "Continue".
  4. From here, proceed with all of the default configurations and select "Import".
  5. You should now see the VM in the GUI. However, the VM will fail to start until the base RAM and Video Memory are sufficiently increased.
  6. Go to Settings > System and increase "Base Memory" to 2048MB.
  7. Then, go to Settings > Display and increase "Video Memory" to 40MB.
Note: In our experience, 2GB of RAM and 40MB of video memory causes Gazebo and RViz to run extremely slowly, especially when run simultaneously. We recommend upping the allocations to 4GB of RAM and 80MB of video memory, if possible. Even then, there is noticeable lag in operating Gazebo and RViz.

Your VM should now be ready to boot!

The default password for the VM is: ubuntu.

Note: If you are using a Mac and you get an error when starting your VM for the first time that says "Kernel driver not installed (rc=-1908)", we found this fix helpful to get around that error.

Shutting Down Your VM

When you want to power off the VM, simply close the window running the VM. You will be presented with three options:

Do NOT select "Power off the machine"! This option has been known to cause many issues. Instead, select either "Save the machine state" (recommended option, as it saves the VM the way you leave it) or "Send the shutdown signal" (shuts down the VM).

Configuring Wireless Network on Your VM

In order to teleoperate the Turtlebot3, your machine and your Ubuntu VM will need to be connected to it via the same Wi-Fi network. This network will most likely be the router that is being used for the class (intro-robo). Follow the steps below:

  1. Ensure that YOUR machine (not the VM) is connected to the intended router. (This will likely be specified in class.)
  2. Open the VirtualBox GUI and check that your Ubuntu VM is in a shutdown state. If it is in a saved state (it will say "Saved" underneath the VM name), open the VM and close it again, this time sending it into the shutdown state.
  3. Once you've ensured the Ubuntu VM is shut down, go to Settings > Network in the GUI.
    1. Go to the Adapter 1 tab, which should be the default. In the Attached to: field, set the option to Bridged Adapter, if it isn't already.
    2. Still under Adapter 1, set the Name: field to your wireless adapter. On a Mac, this will likely be en0: Wi-Fi (Wireless).
    3. Now, in the advanced settings for Adapter 1, click the refresh button to the right of the MAC Address field to ensure that your virtual machine has a unique address.
      refresh MAC address
    4. Go to the Adapter 2 tab. Set Attached to: to Internal Network. The Name: field should already be set to intnet -- go ahead and change it if it's not.
  4. Your VM should now be connected to your machine's WiFi network, enabling it to subsequently connect with the Turtlebot.

ROS on Your VM

ROS should already be installed on your VM, but you will not be able to use ROS commands from the terminal without running a setup script. If this is your first time launching the VM, run the following commands to ensure that the setup script is executed every time you open a new terminal. 

$ echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
    $ source ~/.bashrc
You can check that the setup script has been executed by running the roscore command in a terminal window. You should see an output that looks like the following: 

... logging to ~/.ros/log/9cf88ce4-b14d-11df-8a75-00251148e8cf/roslaunch-machine_name-13039.log
    Checking log directory for disk usage. This may take awhile.
    Press Ctrl-C to interrupt
    Done checking log file disk usage. Usage is <1GB.

    started roslaunch server http://machine_name:33919/
    ros_comm version 1.15.8

    SUMMARY
    ======

    PARAMETERS
     * /rosdistro: noetic
     * /rosversion: 1.15.8

    NODES

    auto-starting new master
    process[master]: started with pid [13054]
    ROS_MASTER_URI=http://machine_name:11311/

    setting /run_id to 9cf88ce4-b14d-11df-8a75-00251148e8cf
    process[rosout-1]: started with pid [13067]
    started core service [/rosout]

You might see one of the following two errors:

If you do see one of these two errors or are otherwise unable to run roscore, re-run the commands to automatically execute the setup script: 

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

Now, you should be able to run roscore and it should show the correct output.

If you are still not seeing the correct output when you run roscore, please reach out to the teaching team for help by posting in the #computer-setup-help channel in our course Slack.


Acknowledgments

We give a BIG thank you to Colin Hudler and UChicago CS techstaff for their help and support in setting up the VM as well as their ongoing support for ensuring that each student in the class get a working programming environment for Intro Robotics. We also thank Borja Sotomayor for sharing the instructions he and his team developed for setting up a UTM VM for M1 Macs.


© Sarah Sebo