Setup

This guide will walk you through setting up the simulation environment including Unity and ROS.

Start with a Ubuntu 20.04 desktop installation (or Virtual Machine).

Unity Editor

To install the Unity Editor, we need to (1) download Unity Hub, (2) create Unity Account and login, and (3) install the correct Unity Version. Besides our tutorial, you can follow the Unity Getting Started Guide.

Note: If you plan on using an Ubuntu VM, install UnityHub and UnityEditor on the host (outside of the virtual machine). Allow communication between Unity (on the host) and ROS (inside of the VM) by allowing communication between the host and VM on port 10000 in your virtualisation software.

Following the guide, run the following command to add the Unity Hub repository:

sudo sh -c 'echo "deb https://hub.unity3d.com/linux/repos/deb stable main" > /etc/apt/sources.list.d/unityhub.list'

To add the public signing key, run the following command:

wget -qO - https://hub.unity3d.com/linux/keys/public | sudo apt-key add -

Then update the package cache and install the package using:

sudo apt update
sudo apt-get install unityhub
  • If you do not have an account, create a Unity account now.

Note: signing up for a student account, though not required, will give you access to some free assets: https://assetstore.unity.com/browse/student-plan-pack

  • Login to UnityHub.

Note: UnityHub can have trouble when Firefox is set to the default browser on Ubuntu 20.04. Installing the Google Chrome browser can fix this: wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && sudo apt install ./google-chrome-stable_current_amd64.deb. You may also need to set Chrome as the default browser.

Click the 2020.3.21f1 link in the Unity Archive under the Unity 2020.x tab. Accept the popup to allow the link to run via xdg-open and then follow the installation tutorial in Unity Hub.

If prompted, accept the defaults to install Unity and optionally install any target build environments that you may want to build for in the future.

Unity Project

  • Clone the unity project—the location of this project is not important, but we'll clone it to the home directory:
git clone --recurse-submodules https://github.com/yale-sean/social_sim_unity.git ~/social_sim_unity

In Unity Hub, add the project you just cloned by clicking the "Add" button. Choose the folder named "social_sim_unity" in the home directory. Once that folder is selected, click the "Ok" button to confirm your selection.

Note: if you are unable to add the project, create a new, blank project by clicking the "New" button, restart Unity Hub, and then try adding social_sim_unity project again

When opening the project for the first time, it is normal that it takes a long time to load all the assets.

ROS Setup

There are two ways to setup ROS: You can either install ROS or use the Docker configuration below.

Install ROS and Use Preconfigured Workspace.

Install by following the ROS Noetic Setup Guide. If you run into any problem or want to learn more about ROS Noetic, see ROS Noetic. Then, you can use the sim_ws as a starting point for your catkin workspace. Start by checking out the repository.

git clone https://github.com/yale-sean/sim_ws ~/sim_ws

Then, run the installer scripts to install all required packages:

cd ~/sim_ws/
./scripts/setup.sh

Note: This script will checkout the code from GitHub and build the workspace for you. If you run into issues, try building the Catkin workspace from scratch and checking out the code manually.

Note: This script runs apt-get update, which sometimes produces an error "the following signatures couldn't be verified because the public key is not available: NO PUBKEY $YOUR-KEY". To fix this, run `sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys $YOUR-KEY" for each missing key (see this post)

After you are done, make sure you add source commands in your .bashrc file so ROS knows where your installed ROS packages are every time you open a terminal:

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

You will see an error like -bash: $HOME/sim_ws/devel/setup.bash: No such file or directory, which is fine. You can now build the workspace:

cd $HOME/sim_ws
catkin_make

Then you can source the .bashrc file again without error.

(Optional) Docker Setup

Instead of creating and installing a workspace from scratch, you can use our Docker configuration to create a set of virtual machines in which the simulation platform can be run.

An advantage of this is that we also provide tools like a Tmuxinator configuration to easily start the necessary ROS components.

The Docker configuration is only tested on an Ubuntu 18.04 host machine with an CUDA compatible NVIDIA graphics card.

First, install the dependencies:

Also, don't forget to add your user to the docker group, as described in the Docker documentation post-install instructions for linux: https://docs.docker.com/engine/install/linux-postinstall/.

To use the Docker configuration:

  • Clone the workspace into your home folder and cd into the workspace:
git clone --recurse-submodules https://github.com/yale-sean/sim_ws.git ~/sim_ws
cd ~/sim_ws
  • Build the Docker containers
./container build ros
  • Start the containers with
./container start ros
  • Enter a shell in the Docker Virtual Machine in your ROS workspace
./container shell ros
  • Then within a container, run the checkout script to checkout the required repositories
./scripts/checkout.sh
  • Build the workspace:
catkin_make

(Optional) Catkin Workspace From Scratch

If you installed ROS and have trouble using the preconfigured workspace, it's also possible to setup your workspace in ~/sim_ws from scratch.

Checkout manually

From the sim_ws directory, run the commands found in the checkout.sh script.

Build the Workspace
source /opt/ros/noetic/setup.bash
source ~/sim_ws/devel/setup.bash
catkin_make -DCMAKE_BUILD_TYPE=Release

It is also recommended to add the source commands to your .bashrc:

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