Skip to content

Latest commit

 

History

History
244 lines (158 loc) · 10.3 KB

01-getting-started.mdx

File metadata and controls

244 lines (158 loc) · 10.3 KB
Raw
section chapter title description slug
Guides
Main Codebase
Getting Started
Setting up your environment and getting started with NUbots development.
/guides/main/getting-started

Prerequisites

Git

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.

Ubuntu

  1. Add Docker's stable repository and update the apt package index.

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
  bionic \
  stable"
sudo add-apt-repository universe
sudo apt update

    If you are on Linux Mint, this will give a malformed input error. Remove [arch=amd64] and rerun.

    sudo add-apt-repository \
 "deb https://download.docker.com/linux/ubuntu \
 bionic \
 stable"

  2. Install the latest version of Docker.

    sudo apt-get install docker-ce docker-ce-cli containerd.io
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

Currently, Windows 10 Pro, Enterprise, or Education is needed to use Docker.

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

  5. Download and install Docker for Windows. Choose the latest stable version.

  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.

Notes on using WSL on Windows:

  • The commands in the rest of this guide should be run in the WSL Ubuntu terminal, except for the commands that should be run on a real robot.

  • When you clone/download the code, you should do so in the WSL Ubuntu terminal, from your home folder. 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

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 all 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 try things out.

  1. Clone the repo by running the following command in a terminal. If you're on Windows, do this in the WSL Ubuntu terminal, after running cd ~ to go to your home folder.

    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

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. You do this by running a command in the form:

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

  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 -i

    This will show a menu to choose 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.

    Next, press c to configure and then g to generate the build list and exit the menu.

  3. Now build the code by running:

    ./b build

  4. 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 have two options for running: on an actual robot, or on your computer using a simulated 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.

Running on a Real Robot

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.

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

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

    ./robocup