Getting Started

Throughout this guide we will focus on completing a specific example task. This task will involve setting up the codebase, running the fake/keyboardwalk binary (which uses simulated hardware) and seeing the robot move in NUsight.

Prerequisites

Git

For our example, we will need Git to get the codebase later on in this guide.

Git is a version control tool. We use it to track changes to the codebase and work together on the same codebase without getting in each other's way.

To work on the NUbots code, you'll need to know the basics of using Git, specifically:

• how to clone remote repositories onto your computer
• how to create branches
• how to add and commit changes
• how to fetch, pull, and push changes

You can do all the above using Git in the terminal, or you can use a Git GUI tool such as GitKraken or GitHub Desktop. There is a guide to using Git in NUbots here.

Docker

Docker is a container system that allows you to install development tools and run builds in an isolated environment that won't affect the rest of your system. We use it to set up the NUbots build system and run builds and binaries.

You will need to perform the steps correctly to set up Docker for your operating system to complete the example.

A Text Editor

This section is not required for our example, but it is a good step to do in case you need to edit code in the future.

You'll need a text editor to make changes to the code. We recommend Visual Studio Code, but feel free to use your favourite editor.

To ensure a consistent code style, NUbots uses clang-format, a tool that reformats code files in the repository to have the same style, even if they're written by different people. For convenience, you can install the clang-format extension in Visual Studio Code to automatically format the files when you make changes.

Another useful tool for editing NUbots code in Visual Studio Code is the Remote Development extension pack. This pack allows Visual Studio Code to work from within the Docker container, using the tools and libraries installed there.

Getting the Code

With all the prerequisites in place, you can now clone the NUbots repository from GitHub to build it and run the code. This is an important step in our example.

1. Clone the repo by running the following command in a terminal.

   Copy
   git clone --recursive https://github.com/NUbots/NUbots.git

   The repo will be cloned into a NUbots directory in the current working directory.

2. Change into the cloned directory and install the required Python dependencies.

   Copy
   cd NUbots
   sudo -H pip3 install -r tools/requirements.txt

Building the Code

Run all these commands for our example, and pay special attention to the instructions in the second step relating to our example.

To build the code, open a terminal and change into the NUbots code directory. Then do the following:

1. Select the platform (type of computer) that the built binaries will run on and create the Docker image. You do this by running the command:

   Copy
   ./b target <PLATFORM>

   Replace <PLATFORM> with your desired platform. The available platforms are:

   • generic - used to build the code for a "generic" computer. This will enable you to run the built binaries on the computer you're building the code on.
   • nuc12wshi7 - used to build the code for the platform that the robots run on. This will build binaries that are optimised for the NUgus robots.

   If you are following the example, use generic.

2. With the target platform selected, choose the binaries (called "roles") that you want to build. You do this by running the following command:

   Copy
   ./b configure
   ./b configure -i

   Note that you will need to do configure without -i the very first time you do this. Using -i will show a menu that will allow you to choose the roles to build. Enable the roles you want to build and disable the ones you don't by highlighting them using the ↑ and ↓ arrow keys and pressing the spacebar to toggle on and off.

   If you are following the fake/keyboardwalk example, you will need to make sure ROLE_fake-keyboardwalk is set to ON. Find the list of items that are prefixed with ROLE_ and set all to OFF except for fake-keyboardwalk, which should be ON. You do not need to change any other build options in this example.

   Press c to configure. Once configuration has finished, press g to generate the build list. Press e to exit if it has not automatically returned you to the terminal.

3. Build the code by running:

   Copy
   ./b build

Running the Code

With the code built, you can run the code on a real robot or on your computer using a simulated robot. If you are following the example in this guide, go to 'Running with a Simulated Robot' below, and skip 'Running on a Real Robot'.

Running with a Simulated Robot

If you are not running the code on a robot, you will need to use a simulated robot. If, for example, you want to run a role called "test", you would run

Copy
./b run test

Roles run this way generally contain platform::HardwareSimulator, a module that simulates robot hardware input and output, or platform::Webots, a module that communicates with the simulated robot in Webots.

If you are following the example, run ./b run fake/keyboardwalk.

Running on a Real Robot

You can skip this section if you are following the example.

To run the code on a robot, you need to make sure the robot is powered on, install the built roles onto the robot, and then ssh into the robot to run the installed roles.

1. Install the built roles onto a robot by running:

   Copy
   ./b install [options] <robot>

   Where:

   • [options] corresponds to zero, one, or multiple options as detailed in the Build System page
   • <robot> corresponds to the name of the robot such as n1 or nugus1, or an IP address

2. Next, open a new terminal and ssh into the robot by running:

   Copy
   ssh nubots@<address>

   Where <address> is the IP address of the robot, in the form 10.1.1.x, with x being the specific robot's number, i.e. 1, 2, or 3.

3. Now you can run any role you have built and installed onto the robot. For example, if you built the scriptrunner role and want to make the robot stand up, you would run:

   Copy
   ./scriptrunner Stand.yaml

   This will start the binary to run the stand script, but the robot won't move until you press the green middle button on its back.

   In addition to the stand script, the scriptrunner role can run other scripts. These can be found in the scripts folder. See Configuration and Script System for details.

   You can also run other roles that are not scriptrunner. For example, to run the robocup role enter the command:

   Copy
   ./robocup

Get, Build and Run NUsight

NUsight is a visual debugging web application used at NUbots that visually represents what the robot is doing. It can be used to view output from any platform, whether that is a real NUgus robot or a simulation. Read more on the capabilities of NUsight on the NUsight page.

NUsight is needed to see the robot walking when we run fake/keyboardwalk.

Open up a new terminal to run NUsight and NUbots code side by side.

1. Get the dependencies for NUsight by running

   Copy
   ./b yarn

2. Build NUsight by running

   Copy
   ./b yarn build

3. Find the IP address of the Docker container.

   In Linux, run

   Copy
   ifconfig

   In Windows WSL, make sure you are running a binary (eg fake/keyboardwalk) in your original terminal, and in your second terminal run

   Copy
   docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker ps | grep nubots:selected | cut -d " " -f1)

   There will be an entry called docker0, or similar. Find the address after the word broadcast. We will refer to this address as <ADDRESS>.

4. Run the following command to run NUsight

   Copy
   ./b yarn prod --address <ADDRESS>

   If you are on the NUbots lab network epsilon-z you do not need the --address argument. Just run ./b yarn prod.

5. The terminal will output a link - localhost:9090. Visit it to view NUsight.

Example

In this section we will finish off our example of setting up the codebase, running the fake/keyboardwalk binary and seeing the robot walk in NUsight.

By now you will have gone through this page and have everything set up to make the robot walk. Ensure you have all the following steps complete

• Prerequisite: Git

• Prerequisite: Docker

• Getting the Code

• Building the Code

• Running the Code: Running with a Simulated Robot

• Build and Run NUsight

With the fake/keyboardwalk binary running, and with NUsight running and your browser open to localhost:9090, do the following

1. Select the 'localisation' tab in NUsight.

2. You will see a stationary robot. To focus on the robot, click inside the window and press space to change perspective.

3. To make the robot walk, go into the terminal that is running fake/keyboardwalk and hit e to enable walking. Use w, a, s and d to make the robot move. Note that this is a basic simulation that does not use gravity, so the robot will move its limbs but may not move in the world.