Setting Up Webots

Setup instructions for Webots.

Updated Last updated 28 Mar 2024

Webots is a physics environment created by Cyberbotics. This guide details how to set up Webots. It gives instructions on setting up Ubuntu (WSL) inside Windows for Windows users, and the rest of the guide is aimed at Ubuntu users (including Windows WSL Ubuntu users). If you would like to learn more about Webots itself, refer to the Webots User Guide.

Prerequisites

Windows

Follow the instructions for setting up Ubuntu in WSL on the Getting Started NUbook page under the Windows tab in the Docker section.
Since Webots uses a GUI, we will need to set up a way to launch and display the program. Use these instructions which is for a similar scenario, but with GitKraken instead of Webots. Take note of the following changes:
- You can ignore installing and launching GitKraken. Instead, we will use the Webots instructions later in this guide to install and launch Webots.
- When running XLaunch configuration, uncheck 'Native opengl' on the third window.
- To prevent having to set the DISPLAY environment variable every time, run the following command in Ubuntu:
```
echo 'export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '\''{print $2; exit;}'\''):0.0' >> ~/.bashrc
```
To be able to copy and paste into the Ubuntu terminal, right-click on the bar at the top of the Ubuntu window. Then click on Properties, and enable Use Ctrl+Shift+C/V as Copy/Paste in the Options tab. Note that this is Ctrl+Shift+C/V not Ctrl+C/V.

In Ubuntu run

sudo apt-get update
sudo apt-get install -y libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libxkbcommon0 libxdamage-dev

You will need XLaunch running every time you want to run Webots.

If Webots crashes with an error similar to the one below, go back to the XLaunch display settings and choose "One large window" instead of "Multiple windows".

XIO: fatal IO error 0 (Success) on X server "145.54.182.1:0.0" after 5824 requests (5824 known processed) with 0 events

Follow the rest of the steps on this page within Ubuntu.

Arch Linux

Run the following to obtain the required dependencies.

pacman -S --needed git lsb-release cmake swig glu glib2 freeimage freetype2 libxml2 libzip boost-libs gd libgcrypt libzip readline pbzip2 pciutils wget zip unzip jdk-openjdk libusb

Download our usb patch which helps the makefile link libusb properly.
After you do the clone step below, move the patch file webots_usb.patch into your webots install folder, and run git apply webots_usb.patch inside that folder to apply it. After that, you should be able to run make -j$(nproc) as usual.

Install libraries for cmake, protobuf, eigen, yaml-cpp, ninja-build, and clang-tidy:

sudo apt-get update
sudo apt-get install cmake-curses-gui libprotobuf-dev protobuf-compiler libeigen3-dev libyaml-cpp-dev ninja-build clang-tidy python3-dev libjpeg9-dev

Install Webots

Install Webots 2022b from the GitHub release.
Set your WEBOTS_HOME environment variable in ~/.bashrc. Check that webots exists in /usr/local/webots
1. Run nano ~/.bashrc to view and edit your bashrc file.
2. Add in export WEBOTS_HOME=/usr/local/webots (or replace any existing lines with this new path).
Note that if webots is somewhere else, find it and use that path instead.
Alternatively you can run echo export WEBOTS_HOME=/usr/local/webots >> ~/.bashrc to append the line to the bashrc file.

Running the Official RoboCup Simulation in Webots

Get the Repository

Move into the directory you would like the clone into. The following command will put you in your home directory.
```
cd ~
```

Clone the RoboCup TC Virtual Season repository:

git clone https://github.com/NUbots/hlvs_webots.git

Set Up the Controllers

Install dependencies for the referee:

cd hlvs_webots
pip3 install -r controllers/referee/requirements.txt

Build the RoboCup controllers:
```
make -j$(nproc)
```
You must have WEBOTS_HOME set or this will fail.

Install Game Controller

Install the ant build tool and Java Development Kit:
```
sudo apt-get install ant default-jdk
```
Clone the RoboCup TC GameController repo:
```
cd ~
git clone https://github.com/RoboCup-Humanoid-TC/GameController.git
```
The first command can be changed to any directory you would like. If you're not sure, just follow what is in this guide.
Change into the cloned directory and build the GameController:
```
cd GameController
ant
```
Add the JAVA_HOME and GAME_CONTROLLER_HOME env variable to your .bashrc file:
```
echo export JAVA_HOME=/usr/lib/jvm/default-java >> ~/.bashrc
echo export GAME_CONTROLLER_HOME=$(pwd) >> ~/.bashrc
source ~/.bashrc
```
The second command assumes you are still in the GameController directory from the previous step.

Run Webots with GameController

Find your primary local IP address by running the following.
```
hostname -I
```
Your primary IP address is often the first of the addresses in the output returned. For example, if hostname -I returns 10.1.0.207 10.1.0.139 172.17.0.1, use 10.1.0.207.
Set the GAME_CONTROLLER_UDP_FILTER env variable to your local IP address from step 1 to ensure your instance of GameController is not affected by other instances of GameController on the network.
```
export GAME_CONTROLLER_UDP_FILTER=<IP_ADDRESS> # replace <IP_ADDRESS> with your IP address from step 1
```
Run the following to open Webots with the RoboCup world and the GameController:
```
webots ~/hlvs_webots/worlds/robocup.wbt
```
Sometimes closing Webots doesn't properly close the GameController subprocess. If this happens you'll get an error about GameController when you next launch Webots. To fix, run the following command which terminates the GameController process, then start Webots again:
```
kill -9 $(pgrep -fi GameControllerSimulator.jar)
```

Set Up with the NUbots Robot Code

Running the RoboCup scenario requires two things: the Webots simulator, of which there is one instance; and the robot code, of which there can be any number of instances equal to the number of robots you would like to run. These programs can be run on any combination of computers. All robots and the Webots simulator can be run locally on one computer, or a separate computer for the Webots simulator and each robot, or any combination inbetween.

Use the Getting Started page to set up the codebase, configure and build on all computers that will be running robot code, if not done so already. When configuring, ensure that ROLE_webots-robocup is ON.
Set your UDP filter on all computers that will be running robot code to prevent them from receiving conflicting GameController packets. Go to the GameController configuration file and set udp_filter_address to the <IP_ADDRESS> from the previous section in step 2.
Ensure the IP and ports are set up correctly. If you are running everything locally on the one computer, the default settings should work as is. If Webots and the robot code are run on separate computers, do the following:
1. As done previously, get the hostname of each computer by running hostname -I in a terminal on each computer.
2. On each computer you will be running the robot code on, run ./b edit config/Webots.yaml and change the IP in server_address to the hostname of the Webots simulator computer found in the previous step. For any robots running on the same computer as the Webots simulator, do not change the IP.
3. On the computer you will be running the Webots simulator on, open the hlvs_webots repo in a text editor. Open the file controllers/referee/game.json (you can use Ctrl+p, search for game.json and the first file should be the correct one).
4. Under red: hosts: add the IP address given by the following command for any computers you are running the robot code on. Robots running on the same computer as the Webots simulation do not need their hostname or IP address listed.
  Windows
```
cat /etc/resolv.conf | grep nameserver | cut -d ' ' -f2
```
  Linux
```
hostname -I
```
On the computer you will be running the Webots simulator on, open the hlvs_webots repo in a text editor. Open the file controllers/referee/game.json. Set use_bouncing_server to false. Set red: config to "./teams/nubots.json". If you are running NUgus robots for both teams, set blue: config to "./teams/nubots.json" as well.

Run the Webots simulator:

webots ~/hlvs_webots/worlds/robocup.wbt

Running One Robot

If you want to test the behaviour of one robot in the Webots RoboCup scenario, you can run the binary from the usual NUbots docker container. The robot can be run on the same computer or on a different computer to the Webots simulator.

Run ./b run webots/robocup on the computer you want to run the robot code on.

Running Multiple Robots

If you're running more than one robot, you will need to set up a Docker container for each robot. There can be any combination of different or same computers for each robot container and webots itself. E.g. you can run webots itself and a robot on one computer, three robots on another computer, and three on another computer. The more computers you have, the more complicated the IP set up will be for the config files.

On all computers that will be running robot code, run ./b webots build webots/robocup once to build the container with the webots/robocup role. Even if you are running multiple robots on that computer, you only need to run this once.

Run the container with the following command

docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=<ROBOT_ID> -e ROBOCUP_TEAM_COLOR=<TEAM_COLOUR> -e ROBOCUP_SIMULATOR_ADDR=<WEBOTS_IP>:<ROBOT_PORT> robocup-vhsc-nubots:robocup webots/robocup

Specify <ROBOT_ID>, <TEAM_COLOUR> and <ROBOT_PORT> depending on which robot you want to run.

For example, if you are running everything locally on one computer, and you want to connect to robot number 1 on the red team, run the following.

docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=1 -e ROBOCUP_TEAM_COLOR=red -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10001 robocup-vhsc-nubots:robocup webots/robocup

Open a new terminal for each robot you want to run.

If you want to run two teams of three NUgus robots all locally on the one computer with Webots, run each of the following lines in different terminals once Webots is running.

docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=1 -e ROBOCUP_TEAM_COLOR=red -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10001 robocup-vhsc-nubots:robocup webots/robocup
docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=2 -e ROBOCUP_TEAM_COLOR=red -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10002 robocup-vhsc-nubots:robocup webots/robocup
docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=3 -e ROBOCUP_TEAM_COLOR=red -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10003 robocup-vhsc-nubots:robocup webots/robocup
docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=1 -e ROBOCUP_TEAM_COLOR=blue -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10021 robocup-vhsc-nubots:robocup webots/robocup
docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=2 -e ROBOCUP_TEAM_COLOR=blue -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10022 robocup-vhsc-nubots:robocup webots/robocup
docker container run --rm --network=host -e ROBOCUP_ROBOT_ID=3 -e ROBOCUP_TEAM_COLOR=blue -e ROBOCUP_SIMULATOR_ADDR=127.0.1.1:10023 robocup-vhsc-nubots:robocup webots/robocup

Running a NUbots Environment

Follow these steps to set up a NUbots developed environment rather than the RoboCup environment.

Clone the NUWebots repository:

cd ~
git clone https://github.com/NUbots/NUWebots.git

Move to the NUWebots folder:
```
cd NUWebots
```
Install the python dependencies:
```
pip3 install -r requirements.txt
```

Configure the codebase by running:

./b configure

You must have WEBOTS_HOME set or this will fail.

Optional Flags

We can configure with several optional flags as follows:

./b configure [-i] [-- <flags>]

where -i runs an interactive configuration with ccmake, and <flags> can be any valid cmake command line flag. Some useful cmake flags are:

Flag	Effect	Default
`-DUSE_ASAN=ON`	Compile with address sanitizer	`OFF`
`-DUSE_UBSAN=ON`	Compile with undefined behaviour sanitizer	`OFF`
`-DENABLE_CLANG_TIDY=ON`	Analyse the code being compiled with clang-tidy	`OFF`
`-DWEBOTS_HOME=path/to/webots`	Tells the compiler where webots is (usually implicitly set by environment variable)	`/usr/local/webots`
`-DCMAKE_BUILD_TYPE=<build type>`	Tells the compiler what type of build type to use, out of {`Release`, `Debug`, `MinSizeRel`, `RelWithDebInfo`}	`Release`

Build the codebase by running
```
./b build
```
Launch Webots by running
```
webots
```
Open a NUbots world file inside Webots.
1. Click on File->Open World....
2. In the pop-up, navigate to the ~/NUWebots/worlds folder on your computer and open the world you would like to run.

Creating a New Controller

From the root of the NUWebots repository run

./b controller generate <name of controller>

Where <name of controller> is the name you want to use for the new controller. A folder and files will be created with this name, so they must be valid file names (don't use spaces in your controller name).

Recording a Game

NUbots runs full Webots games to benchmark the current performance of the code. The following steps describe how to create a video of a full game.

Ensure you have followed the previous steps Install Webots and Running the Official RoboCup Simulation in Webots.
Set up the game configuration.
1. Open the game.json file.
2. Change the "blue": "id" to 13.
3. Change the "blue": "config" field to "team_1.json".
Open a terminal and run the following to open Webots with the RoboCup world and the GameController:
```
webots ~/hlvs_webots/worlds/robocup.wbt
```
Pause the simulation when it opens. The world and robots will load in but the game will not start yet.
Open a separate terminal in the directory where your NUbots/NUbots code is and build the robot code.
```
./b webots build webots/robocup
```
Run the robots
```
./b webots game -r 6 webots/robocup
```
This will start six robots, three for each team.
Adjust the view in Webots so that the whole field is visible.
Click the HTML5 animation record button in Webots, as shown in the image below. This will record an interactive version of the game.
HTML5 animation record button in Webots
Click the button directly to the left of the HTML5 animation button to simultaneously record a standard video of the game.
Once the game has finished, press Esc to exit fullscreen mode and when prompted save the video. This video can be shared in the Google Drive or on our YouTube channel.
Click the HTML5 animation record button again to stop the recording and when prompted save the recording. This can be uploaded to the Google Drive and can be used to review the game with more flexibility than a standard video.

Viewing a HTML5 Animation

If you created or downloaded a HTML5 animation as above and would like to view it, follow these instructions.

Install Node.js.
Open a terminal in the folder the animation is located in and run
```
http-server
```
Open the URL in a browser. It is typically http://127.0.0.1:8080.
Navigate to the .html document in the browser. The Webots world should load and you should be able to play the simulation as if it were a video, with the ability to move around the scene.

On this page