Getting Started

Setting up your environment and getting started with NUbots development.
Ysobel Sims GitHub avatarJosephus Paye II GitHub avatarMikyla Peters GitHub avatarLachlan Court GitHub avatarCorah Oliver GitHub avatar
Updated 6 Oct 2024

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.

Ubuntu

To install on Ubuntu, use the official Docker instructions. These instructions should work for Ubuntu-like Linux distributions, such as Pop!_OS. There are multiple ways to install Docker, as detailed on the website. NUbots recommends the following for installing Docker

  1. Navigate to the section for installing using the Apt repository. Complete the three steps under this section.

  2. Install python3 and pip.

    sudo apt-get install python3 python3-pip
  3. Add the current user to the Docker group, so you can run Docker commands without sudo.

    sudo usermod -aG docker "${USER}"
  4. Reboot to make the group change take effect.

MacOS
  1. Install Homebrew by following the instructions at brew.sh.

  2. Install Python 3 and Docker using Homebrew.

    brew install python3
    brew cask install docker
  3. Run the Docker Desktop app that was installed and ensure that Docker is running by checking that it shows a green dot in the app menu bar.

    Top right screenshot of a macOS system shows the Docker icon with a dropdown menu. The first line in the menu is highlighted and reads 'Docker desktop is running'.
  4. Go to Advanced settings in Docker Desktop's Preferences and increase the memory available to containers to at least 4GB. By default Docker will allocate 2GB of memory to containers, which is not enough to build the NUbots docker image.

Windows
  1. Ensure your Windows build is at least 2004.

    • Press WIN + R.
    • Type winver and hit Enter.
    • Inspect the version to verify it is at least 2004. Upgrade Windows if not.
  2. Enable WSL 2

    • Open Windows Powershell in administrator mode.
    • Run the following to install WSL:
      dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
    • Run the following to enable the Virtual Machine Platform feature needed for WSL:
      dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
    • Restart your computer.
  3. Go to the Microsoft Store. Search for 'Ubuntu 22.04.3 LTS' and install it. Launch Ubuntu.

  4. Ensure Ubuntu is using WSL 2.

    • In Powershell, run:
      wsl --list --verbose
    • If the version is not 2, run:
      wsl --set-version Ubuntu-22.04.3 2
    Note that 'ubuntu' in the last command may need to be capitalised. Check the exact spelling from the list output in the first command of this step.

    If you have issues with the Linux kernel needing to be updated, get the update from the Microsoft page.

  5. Download and install Docker for Windows. Choose the latest stable version. Ensure you enable WSL 2 features.

  6. Configure Docker settings.

    • In the system tray, right-click the Docker icon and select Settings.
    • In General, enable the Use the WSL 2 based engine option.
    • In Resources: WSL Integration enable Ubuntu.
  7. In Ubuntu run sudo apt update followed by sudo apt upgrade.

  8. Ensure you have pip3 by running

    sudo apt install python3-pip
The commands in the rest of this guide should be run in the WSL Ubuntu terminal except where specified to run them elsewhere, such as on a real robot.

When you clone/download the code, you should do so in the WSL Ubuntu terminal, from your home folder. Run cd ~ to navigate to your home folder in Ubuntu.

Outside of WSL, the path to the cloned NUbots code folder will be of the form \\wsl$\Ubuntu\home\<USERNAME>\NUbots, where <USERNAME> is the username you set up for Ubuntu. This path should be the one you use to open the code in text editors such as Visual Studio Code.

GitKraken will not allow you to open the repository outside of WSL. Use the steps described in this article to set up your system to use GitKraken in WSL.

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.

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.

    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.

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

If this fails, run sudo apt-get update && sudo apt-get upgrade.

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:

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

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

    ./b build

If your computer struggles to build and crashes, run ./b build -jx, where x is the number of cores you want to use. A good recommended amount of cores is five, but if you still struggle perhaps use one core.

Some built roles use data from .yaml configuration files. If you change a configuration file, you will need to run ./b build again.

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

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

When running on a real robot, make sure you understand how to safely handle a robot. To make the robot's servos relax, hit the red button on the back of the robot. This is an emergency stop button to prevent harm.

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:

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

    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:

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

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

    ./b yarn
  2. Build NUsight by running

    ./b yarn build
  3. Find the IP address of the Docker container.

    In Linux, run

    ifconfig

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

    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

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

Modules
Vision
Main Codebase
NUClear
NUbots acknowledges the traditional custodians of the lands within our footprint areas: Awabakal, Darkinjung, Biripai, Worimi, Wonnarua, and Eora Nations. We acknowledge that our laboratory is situated on unceded Pambalong land. We pay respect to the wisdom of our Elders past and present.
Copyright © 2024 NUbots - CC-BY-4.0
Deploys by Netlify