Introduction to the NUbots codebase and high-level architecture.
Updated 8 Sept 2021

The NUbots repository is the main codebase that runs on the robots. Its purpose is to control the robot during RoboCup matches. The NUbots codebase, along with all other NUbots code, is open source and can be found on GitHub. The primary language in the NUbots codebase is C++.

The main parts of the NUbots codebase are behaviour, motion, vision, and localisation. Behaviours include strategy, planning and skills. Motion includes kicking, getting up, and walking. Vision includes ball, goal and field detectors. Localisation determines where the robot, ball and the field are in the world through odometry.

At the top level, the robot will use strategy to decide what to do based on the game state. This includes unique behaviour for penalty shoot-outs.

The next level down is planning. This includes planning the path to walk along to get to the ball facing the right goal. Below planning is skills. Skills include kicking, walking, getting up, and looking at objects.

Next is motions. Motions include how the robot moves its feet to walk, and what movements it does to kick or get up.

After motions is hardware IO. The hardware will output the commands and input the information from the world. This will then go through a sensor filter so that the robot can interpret the information. This information then influences strategy.

All these modules are connected using NUClear which is a message passing software architecture. More can be found on NUClear here.

Flow of the NUbots codebase


The robot codebase contains roles, which are recipes for creating a binary to run on a robot. A role file lists all the modules to be used in that binary. Only modules included in the role file will run, provided the code is triggered. All roles can be found in the roles folder in the first level of the repository and have the extension .role. For specifics about the NUClear roles system, see the NUClear page.

When adding modules to the list in a role, use the syntax path::to::module. For example, if you want to include the DataLogging module, check the path to that module relative to the module folder. The path is support/logging/DataLogging, so we include the line support::logging::DataLogging.

The following is a table of roles that exist in the NUbots codebase and possible use cases for them.

Role NameUsage
balllocalisationTest and tune how well the robot detects balls on a field.
cameratestTest if the cameras are working and calibrate the cameras.
filter_playbackPlay back raw sensor data. Used in conjunction with NUsight to view the filtered data.
firmwareinstallerInstall CM740 firmware to the robot.
gamecontrollertestTest the connection between the robot and GameController.
gazeboRun motions with a robot in Gazebo.
headbehtestTest head behaviour, particularly with balls and goals.
keyboardwalkDemonstrate the robot manually with a keyboard, particularly in a setting without a field.
keyboardwalkfakeTest parts of the code without a real robot. Demonstrate basic functionality of the robot. Part of the Getting Started example since it does not require a real robot.
localisationtestTest localisation in a simulated environment.
lookatballTest the robot's ability to track a ball with head behaviour.
lookatgoalTest head behaviour with localisation, which should make the robot look at the goals.
natnetGet motion capture data from a Motive motion capture system.
nusighttestTest the connection with NUsight. This role doesn't run anything that can send data.
playbackPlay back data to view in NUsight without triggering any other processes in the system.
ps3walkDemonstrate the robot manually with a PS3 controller, particularly in a setting without a field.
robocupPlay RoboCup games on the real robot.
scriptrunnerRun scripts such as the Stand.yaml script, which is useful to run before doing anything with the robot.
scripttunerTune/modify/create scripts.
scripttunerwebotsTune/modify/create scripts in the webots simulator.
sensortestTest odometry (needs NUsight). Check for broken servos without the robot moving, because servo errors and warnings will be printed to the terminal.
visualmesh_fakeTest the vision system, such as detection of balls and goals, in a simulated environment.
visualmeshTest the vision system on a real robot.
webots_keyboardTest motions in Webots with manual control.
webotsTest the connection between the robot code and Webots.
webotsrobocupPlay RoboCup games in the Webots simulator.

In a role, you should have only one platform. Possible platforms are platform::darwin::HardwareIO, platform::darwin::HardwareSimulator, platform::Webots and platform::Gazebo.

Any code should run with platform::darwin::HardwareSimulator, but this is a very basic simulated robot and does not consider gravity - this may be useful if you want to see a motion run on the robot without the robot falling down, or if you want to test if the code runs without setting up the real robot or a simulator.

platform::darwin::HardwareIO is used for the real robot. You will get a runtime error if you do not run this on a robot, as it will be unable to find the hardware needed.

platform::Webots is used with the Webots simulator. The code will only run if an appropriate Webots controller is running.

platform::Gazebo is used with the Gazebo simulator. It will only work with the appropriate Gazebo plugin.

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