Getting Started

Setting up your environment and getting started with NUbots development.
Updated 22 June 2022

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. This will happen later 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/Linux Mint

To install on Ubuntu, use the official Docker instructions. These work with Linux Mint, with some adjustments. There are multiple ways to install Docker, as detailed on the website. NUbots recommends the following for installing Docker

  1. Navigate to the section where you Install Docker using the Repository. Complete the three steps under the heading 'Set Up the Repository'.

    If you are using Linux Mint, please read the info bubble below.

    The third step will not work on Linux Mint for two reasons.

    1. You will get a malformed input error. Removing [arch=amd64] fixes this.

    2. You cannot use the command $(lsb_release -cs) on Linux Mint. This command returns the name of the Ubuntu LTS. On Linux Mint, you will need to manually enter the LTS name.

      If you are using the latest Linux Mint version, 'Ulyana', you will need to replace the command with focal. This refers to the Ubuntu LTS that Linux Mint Ulyana is build off, 'Focal Fossa'.

      If you are using an old version of Linux Mint, you can find out what Ubuntu LTS it uses on the Linux Mint all downloads page. For example, if you are using Linux Mint Tricia, use bionic.

    If you are using Linux Mint Ulyana - the latest Linux Mint version - then your command for step three will be

    sudo add-apt-repository \
    "deb https://download.docker.com/linux/ubuntu \
    focal \
    stable"
  2. Complete the three steps under the heading 'Install Docker Engine', which is just below the previous section, 'Set Up the Repository'. After you complete this step, you are finished with the Docker install page.

  3. Install python3 and pip.

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

    sudo usermod -aG docker "${USER}"
  5. 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 20.04 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-20.04 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 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 (e.g. 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.
    • nuc7i7bnh - 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 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 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. This will show a confirmation menu, press e to go back to the main menu. Press g to generate the build list, and then press e to exit.

  3. Build the code by running:

    ./b build

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::darwin::HardwareSimulator, a module that simulates robot hardware input and output.

If you are following the example, run ./b run fake_keyboardwalk. If you are on Windows or MacOS, see the note below.

Windows and MacOS users who want to connect to NUsight will need to set up the docker network and run

./b run fake_keyboardwalk --network nuclearnet

See the NUsight section below for details.

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
    • <robot> corresponds to the name of the robot such as n1 or nugus1
  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.

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

You will need this for our example to see the robot walking when we run fake_keyboardwalk.

Before setting up NUsight you'll need to configure what messages you want to send to NUsight. Open up the NetworkForwarder configuration file by running:

./b edit config/NetworkForwarder.yaml

This will open the file using the nano editor. If you are not familiar with nano, check out this YouTube guide to help you complete this step.

Set the messages you would like NUsight to receive to 'true'. For our example, you need message.input.Sensors set to true.

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

Ubuntu/Linux Mint
  1. Install Node.js by running

    curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
    sudo apt-get install -y nodejs
  2. Install npm by running

    sudo apt install npm
  3. Configure the package repository and install yarn by running

    curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
    echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
    sudo apt update && sudo apt install yarn
  4. Get the dependencies for NUsight by running

    ./b yarn
  5. Build NUsight by running

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

    ifconfig

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

  7. 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 yarn prod.

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

Windows/MacOS
  1. NUsight is within the NUbots repository. Move into the NUsight directory by running

    cd nusight2
  2. Create the Docker nuclearnet network to allow communication between the NUsight Docker container and the NUbots Docker container.

    docker network create nuclearnet
  3. Run a NUbots binary in another window, with our newly created network nuclearnet. For example, if you want to run the fake_keyboardwalk binary, use the command

    ./b run fake_keyboardwalk --network nuclearnet
  4. Make the Docker script executable by running

    chmod +x ./docker
  5. Install the NUsight dependencies in the container and build NUsight for prod in the container

    ./docker yarn
    ./docker yarn build
  6. Inspect the network to find the NUbots container's IP address

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

    The IP address given will be referred to as <ADDRESS>. You will need to be running a binary in NUbots or this will not work. See step 3 for details.

  7. Run NUsight with the NUbots container address

    ./docker yarn prod --address <ADDRESS>
  8. 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 (with --network nuclearnet if using Windows or MacOS), and with NUsight running and your browser open to localhost:9090, do the following

  • Select the 'localisation' tab in NUsight.

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

  • 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 it likely won't move in the world.

Copyright © 2022 NUbots - CC-BY-4.0
Deploys by Netlify