Setting Up Webots

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

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

Copy
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

1. Install Webots 2022b from the GitHub release.

2. 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 a Robot in Webots

NUbots has their own collection of Webots controllers, models and environments to assist with development. To set up these resources:

1. Clone the NUWebots repository and move into the folder

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

2. Install the python dependencies:

   Copy
   pip3 install -r requirements.txt

3. Configure the codebase:

   Copy
   ./b configure

   You must have WEBOTS_HOME set or this will fail.

   Optional Flags

   We can configure with several optional flags as follows:

   Copy
   ./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

4. Build the codebase:

   Copy
   ./b build

5. Launch Webots:

   Copy
   webots

6. 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.

While a world like vision_collection is self contained, most worlds require that a robot binary is running to control a robot in the simulation. First we consider the single robot scenario.

1. Set up the codebase using the Getting Started page and build at least one Webots role.

   Webots roles are found in the roles/webots folder in the main codebase, and are prefixed with webots in ./b configure -i.

2. Run the binary using ./b run <role_name>. <role_name> is the role you built in the previous step and want to run. By default, this should connect to the robot in the simulator listening on port 10001.

3. (Optional) If you want to run webots/robocup, you will need GameController.

   1. Install the ant build tool and Java Development Kit:

      Copy
      sudo apt-get install ant default-jdk

   2. Clone the RoboCup TC GameController repo and move into the folder:

      Copy
      cd ~
      git clone https://github.com/RoboCup-Humanoid-TC/GameController.git
      cd GameController

   3. Build GameController:

      Copy
      ant

   4. Add the JAVA_HOME and GAME_CONTROLLER_HOME env variables to your .bashrc file:

      Copy
      echo export JAVA_HOME=/usr/lib/jvm/default-java >> ~/.bashrc
      echo export GAME_CONTROLLER_HOME=$(pwd) >> ~/.bashrc
      source ~/.bashrc

      This assumes you are still in the GameController directory from the previous step.

   5. (If running in the lab) GameController broadcasts to the network, so if anyone else is running an instance of GameController it will confuse the robot. It is a good idea to filter the GameController IP to prevent issues:

      1. Find your IP address using:

         Copy
         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.

      2. Open GameController.yaml in the main codebase and set udp_filter_address to your local IP address from step 1.

   6. Open a new terminal window and run:

      Copy
      cd ${GAME_CONTROLLER_HOME}/build/jar
      java -jar GameController.jar

      This starts the GameController java application.

      GameController will ask you to select settings for the game. Select the first team to be team 12. If you are running opponent robots, select the other team to be team 13. If you are not running opponent robots, then the second team number is not important. In most cases, select 'Normal Game'. Click 'Start' to start GameController.

With the robot binary running and the simulator world running, you should see a NUgus robot in Webots move. If you encounter issues, check both the robot terminal and Webots terminal for errors.

If you would like to connect to a different robot, you will need to use command line arguments to specify the robot. There are 8 robots in the 4v4 world. The following table specifies the settings for each robot in Webots. The first row contains the default settings in the main codebase.

To run a specific robot, run:

Copy
./b run <role_name> --webots_port <webots_port> --player_id <player_id> --team_id <team_id>

For example to run Red 2:

Copy
./b run webots/robocup --webots_port 10022 --player_id 2 --team_id 13

Multiple robots can be run at the same time by running the command in separate terminals. For quick use, there is a multi robot tool which facilitates running multiple robots in the one terminal.

Copy
./b multi <role_name> <num_robots> [--single_team]

<role_name> is the role for each robot to run, such as webots/robocup. <num_robots> is the number of robots to run per team. [--single_team] is an optional flag to only run robots for team 12.

Running the Official RoboCup Simulation in Webots

RoboCup 2021 was held remotely and the Humanoid League opted to run the competition using Webots. A collection of tools for Webots were developed by the Technical Committee and Cyberbotics. The world developed for official virtual matches includes an automatic referee which controls the game state with the help of GameController and manages penalties and placing. This world is useful to use when testing behaviour with GameController.

The following instructions sets up the official RoboCup Webots simulation. Note that we use our own NUbots fork of the repository, so that configuration files are ready-to-use for team members.

1. Move into the directory you would like the clone into and clone the repository. The following commands will clone in the home directory:

   Copy
   cd ~
   git clone https://github.com/NUbots/hlvs_webots.git

2. Install dependencies for the referee:

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

3. Build the RoboCup controllers:

   Copy
   make -j$(nproc)

   You must have WEBOTS_HOME set or this will fail.

4. Install GameController using the instructions in the previous section if not completed. Do not explicitly run GameController, as the autoref will run it automatically.

   If you are running this in the NUbots lab, note that GameController broadcasts to the network. Any other GameController instance from another computer on the network will confuse the robot and the autoref in Webots. Therefore, it is good to filter the messages. Filtering on the robot is addressed in the previous section.

   To set the GameController UDP filter for Webots:

   1. Find your IP address using:

      Copy
      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.

   2. Set the GAME_CONTROLLER_UDP_FILTER env variable to your local IP address from step 1.

      Copy
      export GAME_CONTROLLER_UDP_FILTER=<IP_ADDRESS> # replace <IP_ADDRESS> with your IP address from step 1

5. Run the following to open Webots with the RoboCup world and the GameController:

   Copy
   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:

   Copy
   kill -9 $(pgrep -fi GameControllerSimulator.jar)

Robots are run in the same way as in the previous section with NUWebots, including the multi robot tool. Only webots/robocup should be used with the RoboCup game world as other programs may not adhere to the autoref rules.

An example for a single robot:

Copy
./b run webots/robocup

An example for a multi robot game with two robots per team:

Copy
./b multi webots/robocup 2

Advanced Run Settings

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. The only restriction is that they are running on the same network.

If the robot is running on a separate computer to the Webots simulator, then the following configuration must be set:

1. Get the IP address of the computer running Webots (hostname -I).

2. Set the server_address field in Webots.yaml to the IP address found in step 1.

3. Get the IP address of the computer running GameController (hostname -I). For the TC RoboCup environment, this will be the IP of the computer running Webots.

4. Set the GameController.yaml UDP filter to the IP address found in step 3.

5. Get the IP address of the computer running the robot (hostname -I). The Webots world must be configured to allow the connection from the other computer.

   For the NUWebots worlds, open the world file in a text editor and append the IP address to the controller_args for the desired robot.

   For the TC RoboCup world, go to the controller/referee/game.json file. Under hosts, add the robot IP. There is a hosts section for each team (red and blue).

If you suspect an IP address has been set wrong, output in both the robot terminal and Webots console can indicate issues. The Webots console logs if it rejects a connection from an IP address, and the robot will log if it is rejected.

Creating a New Controller

NUWebots is the home of any Webots environments developed by the team. If you are adding new functionality, there is a tool to quickly generate a new controller.

From the root of the NUWebots repository run

Copy
./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

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

1. Ensure you have followed the previous steps Install Webots and Running the Official RoboCup Simulation in Webots.

2. Open a terminal and run the following to open Webots with the RoboCup world and the GameController:

   Copy
   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.

3. Open a separate terminal in the directory where your NUbots/NUbots code is. webots/robocup must be built.

4. Run the robots

   Copy
   ./b multi webots/robocup 4

   This will start eight robots, four for each team. You can adjust this for smaller teams or an empty field game.

5. Adjust the view in Webots so that the whole field is visible.

6. Click the HTML5 animation record button in Webots, as shown in the image below. This will record an interactive version of the game.

   

7. Click the button directly to the left of the HTML5 animation button to simultaneously record a standard video of the game.

8. 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.

9. 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.

1. Install Node.js.

2. Open a terminal in the folder the animation is located in and run

   Copy
   http-server

3. Open the URL in a browser. It is typically http://127.0.0.1:8080.

4. 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.