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.
Roles
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 Name | Usage |
|---|---|
balllocalisation | Test and tune how well the robot detects balls on a field. |
cameratest | Test if the cameras are working and calibrate the cameras. |
filter_playback | Play back raw sensor data. Used in conjunction with NUsight to view the filtered data. |
firmwareinstaller | Install CM740 firmware to the robot. |
gamecontrollertest | Test the connection between the robot and GameController. |
gazebo | Run motions with a robot in Gazebo. |
headbehtest | Test head behaviour, particularly with balls and goals. |
keyboardwalk | Demonstrate the robot manually with a keyboard, particularly in a setting without a field. |
keyboardwalkfake | Test 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. |
localisationtest | Test localisation in a simulated environment. |
lookatball | Test the robot's ability to track a ball with head behaviour. |
lookatgoal | Test head behaviour with localisation, which should make the robot look at the goals. |
natnet | Get motion capture data from a Motive motion capture system. |
nusighttest | Test the connection with NUsight. This role doesn't run anything that can send data. |
playback | Play back data to view in NUsight without triggering any other processes in the system. |
ps3walk | Demonstrate the robot manually with a PS3 controller, particularly in a setting without a field. |
robocup | Play RoboCup games on the real robot. |
scriptrunner | Run scripts such as the Stand.yaml script, which is useful to run before doing anything with the robot. |
scripttuner | Tune/modify/create scripts. |
scripttunerwebots | Tune/modify/create scripts in the webots simulator. |
sensortest | Test odometry (needs NUsight). Check for broken servos without the robot moving, because servo errors and warnings will be printed to the terminal. |
visualmesh_fake | Test the vision system, such as detection of balls and goals, in a simulated environment. |
visualmesh | Test the vision system on a real robot. |
webots_keyboard | Test motions in Webots with manual control. |
webots | Test the connection between the robot code and Webots. |
webotsrobocup | Play 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.
