NUClear

NUClear is the software framework used in the main NUbots codebase. It is a message passing system designed to be modular and fast.

This page is intended to be a practical summary of the official NUClear documentation, which contains a detailed description of NUClear. The NUClear Roles repository contains a detailed description of the NUClear roles system, much of which the roles section in this page is based off.

Components

PowerPlant

The PowerPlant is the central message system through which reactors communicate. It takes ownership of any data emitted by reactors into the system and executes the required reactions. NUClear is multi-threaded. The PowerPlant handles all threading logic.

Reactors

A reactor can be thought of as a module. All modules in the NUClear system are an extension of NUClear::Reactor. Reactors define reactions and the conditions under which they will process. They may also emit data to the PowerPlant.

Reactions and Tasks

Reactions run tasks when the required data is available and/or when certain conditions are true. A task is the current execution of a defined reaction within the system. These functions are bound by NUClear as callbacks, and it is the execution of these callbacks which will assign tasks to a thread.

Reactions are created by subscribing to the PowerPlant through DSL On Statements.

NUClear DSL

On Statements

Reactors make subscriptions to the PowerPlant using on statements, which define the conditions for reactions to run.

An on statement has the following form

Copy
on<...>(...).then(...);

This can be split into three parts. The first is the on<...> which is the DSL request. The (...) contains any runtime arguments. .then(...); is the callback, which is what will be executed when the reaction is triggered.

DSL Request

The DSL request is "fused" together by combining any number of DSL words. The combination of these words will define the kind of reaction which is being requested. For example, Trigger will define a reaction that should occur when a required data type is emitted, while Every will define periodic reactions.

For reactions to occur, at least one Binding DSL word should be present in the DSL Request. The binding DSL words are: Trigger, With, Every, Always, Startup, Shutdown, TCP, UDP, and Network.

More information on DSL words for on statements can be found in the NUClear documentation.

Runtime arguments

Some DSL words will provide the ability to make changes to the system during runtime. This means that NUClear avoids the need for a system restart should a configuration, port number, or file need to be changed while the system is running.

The DSL words that take runtime arguments are: IO, TCP, UDP and Configuration.

Callback

The callback which will execute when the reaction is triggered during runtime can be defined using a C++ lambda function. These are of the form

Copy
[this](args...){
    statements...
}

The args will generally be based off the conditions for the reaction, such as access to data. For example:

Copy
on<Trigger<dataType>>().then([this](const dataType& value) {
    // Do things
});

Capturing the this pointer will allow your reaction to access other members of your Reactor (e.g. configuration data).

Emit Statements

Emit statements are used by Reactors wanting to emit data to the PowerPlant. When using NUClear, data will most likely be emitted during a reaction. However, where necessary, emissions can also occur during reactor construction, or in some cases from within the PowerPlant itself.

Any data emitted to the PowerPlant will be sent with a unique pointer. The PowerPlant will take ownership of this pointer and run any necessary callbacks to trigger reactions.

Data can be emitted under varying scopes. These can be local or network emissions. More information can be found on emit statements in the NUClear documentation.

Local Emissions

Local emissions send data to the local instance of the NUClear PowerPlant. Essentially this is the current running process. There are a number of scopes under which these emissions can take place. The syntax for these emissions are emit<Scope::SCOPE>(data, args...);, where SCOPE is replaced with a scope as defined below.

Network Emitting

Network emissions can be used to send data through the network on which the current system is running.

Managing Reactions

During system runtime, executing reactions can be managed via their associated reaction handles. A reaction handle is provided for binding on statements. Once an on statement has been bound, the reaction handle will be enabled. If necessary, reactions can toggle between enabled and disabled during runtime.

NUClear Roles

The NUClear Roles system is a build and messaging system for the NUClear framework. It uses CMake and Python to manage the construction of various executables made up of a selection of modules. These executables are called roles.

CMake is used as the main system for generating the libraries and executables that are used for the final binary. Note that it utilises globbing to find the sources that are used for modules. If you add or remove a file, you must rerun CMake to locate the new files.

Directories

There are six main directories in the NUClear Roles system and can be seen in the main NUbots codebase.

Roles

Roles are executables containing a specified list of modules. They are called <executablename>.role, where <executablename> is the name of the final binary that will be created.

The name of each module is described as a fully qualified C++ class without the initial module namespace. These modules will then be installed in order when the executable is run. This is important to note as it means modules that have dependencies on other modules may want to be lower in the list. For example installing log handler modules should happen before installing other modules so their output can be seen. It will use this name to locate the module so the directory structure must match the name. An example of a role file would be:

Copy
NUCLEAR_ROLE(
    # Some global modules that are useful
    extension::FileWatcher
    support::logging::ConsoleLogHandler

    # Input from USB3 Cameras
    input::Camera
)

This role file would create an executable with the modules module::extension::FileWatcher, module::support::logging::ConsoleLogHandler and module::input::Camera. This file is a CMake file so you are able to use # to declare comments.

NBS Files

NBS files are NUClear Binary Stream files. To make it easier to serialise streams of messages for storage sharing and playback, NUClear Roles defines a format for serialising messages to files. This format is based on the Neutron messaging system and NUClear's networking protocol. An nbs file has the following frames repeated continuously:

All values within this format are little endian.

An .nbz or .nbs.gz file is a compressed nbs file using gzip.

NBS files can have an associated index file. This allows for quicker random access to the coresponding nbs file. An .nbs.idx file has the following frames, each compressed with gzip, repeated continuously:

All values within the index file are little endian.

Neutrons

Reactors emit data in the form of messages called Neutrons. Neutrons are Protobuf messages in a C++ wrapper. These are all located in the shared/message/ directory, and have the .proto extension. An example is WalkCommand.proto:

Copy
syntax = "proto3";

package message.motion;

import "Vector.proto";

message WalkCommand {
    uint64 subsumptionId = 1;  // reservation identifier for servo control
    vec3   command       = 2;  // x and y are velocity in m/s and angle is in rads/s
}

Examples

These examples use links to specific commits in the NUbots GitHub repository. They are likely out of date and don't reflect the functionality in the current main branch. They are intended to be used as examples to help understand the NUClear framework.

On Statements

Looking at SensorFilter.cpp we can see some examples of NUClear on statements.

The first on statement is located at line 94 of SensorFilter.cpp.

Copy
on<Configuration>("SensorFilter.yaml").then([this](const Configuration& config) {
    log_level = cfg["log_level"].as<NUClear::LogLevel>();
    // Button config
    config.buttons.debounceThreshold = cfg["buttons"]["debounce_threshold"].as<int>();
    ...
});

The DSL request is on<Configuration>. This means the runtime argument here is ("SensorFilter.yaml"). This is the configuration file. The callback is

Copy
then([this](const Configuration& config) {
    log_level = cfg["log_level"].as<NUClear::LogLevel>();
    // Button config
    config.buttons.debounceThreshold = cfg["buttons"]["debounce_threshold"].as<int>();
    ...
});

The const Configuration& config is a parameter of type Configuration. We can see examples of how this type works in the lines after it. cfg["buttons"]["debounce_threshold"].as<int>() finds the value labelled as ["buttons"]["debounce_threshold"] in the configuration file and retrieves it as an int type.

This value is then stored in the member variable debounceThreshold in the struct buttons.

This reaction is used at startup to set many variables from a configuration file. The next on statement does this as well, but with the FootDownNetwork.yaml configuration file.

The third on statement uses the DSL words Last, Trigger, With and Single.

Copy
on<Last<20, Trigger<RawSensors>>, With<KinematicsModel>, Single>().then(
            [this](const std::list<std::shared_ptr<const RawSensors>>& sensors, const KinematicsModel& model) {
    ...
});

The DSL request is on<Last<20, Trigger<RawSensors>>, With<KinematicsModel>, Single>. This says that we will create a task for this reaction when we receive a RawSensors message. The last 20 received RawSensors messages will be stored in a std::list. With<KinematicsModel> will get the last available KinematicsModel message. The KinematicsModel message is emitted once on<Configuration> in the KinematicsConfiguration module to provide measurements for the robot. Finally, the Single word is used to only run one task for this reaction at any given time. If a RawSensors message is received while a task is already running, a new task will not be created.

None of the words used require runtime arguments, so we do not have any here. The callback is

Copy
then(
                [this](const std::list<std::shared_ptr<const RawSensors>>& sensors, const KinematicsModel& model) {
    ...
});

The first parameter for this lambda statement is a std::list. This is because the word Last is used. The list will contain those last 20 received messages as specified in the DSL request. It is also valid to use a std::vector for this parameter. The KinematicsModel parameter is not a list because Last only applies to the message in the Trigger.

The next on statement in SensorFilter.cpp uses Trigger, Optional, With, Single, and Priority.

Copy
update_loop =
            on<Trigger<RawSensors>, Optional<With<Sensors>>, With<KinematicsModel>, Single, Priority::HIGH>()
                .then(
                    "Main Sensors Loop",
                    [this](const RawSensors& input,
                           const std::shared_ptr<const Sensors>& previousSensors,
                           const KinematicsModel& kinematicsModel) {
                        auto sensors = std::make_unique<Sensors>();
                        ...
});

The DSL request is on<Trigger<RawSensors>, Optional<With<Sensors>>, With<KinematicsModel>, Single, Priority::HIGH>. This will create a task when RawSensors and KinematicsModel messages are received. We do not need to have received a Sensors message since it is Optional. If a task is already running, a new task will not be created since the Single word is present. Priority::HIGH specifies that the PowerPlant should give this a HIGH priority when scheduling.

Another aspect of this reactor is the update_loop variable. This is a ReactionHandle type and can be found in the header file. The reaction can be enabled by calling update_loop.enable() and disabled by calling update_loop.disable().

As expected, our callback has const RawSensors& input and const KinematicsModel& kinematicsModel since we asked for the RawSensors and the KinematicsModel messages. The interesting part of this is the std::shared_ptr<const Sensors> previousSensors. This will either be a nullptr or a valid Sensors message. There are checks in the function to see if the pointer is null and this determines how the function behaves.

Looking at line 133 of ScriptTuner.cpp we can see an example of an on<IO> reaction.

Copy
on<IO>(STDIN_FILENO, IO::READ).then([this] {
    // Get the character the user has typed
    switch (getch()) {
        ...
    }

    // Update whatever visual changes we made
    refreshView();
});

In this case the DSL request is on<IO> and the runtime arguments are (STDIN_FILENO, IO::READ) which directs the PowerPlant to monitor for new data to read on the standard input file (i.e. the keybaord). Finally, the callback is

Copy
then([this] {
    // Get the character the user has typed
    switch (getch()) {
        ...
    }

    // Update whatever visual changes we made
    refreshView();
});

Emit Statements

An example of local emission can be seen in SensorFilter.cpp where we call

Copy
emit(std::move(sensors));

This emits a Sensors message. This can then be received by reactors waiting for a Sensors message to trigger the reaction.

Looking at line 236 of GameController.cpp, we can see an example of NUClear network emission.

Copy
powerplant.emit_shared<Scope::NETWORK>(std::move(gameState), "nusight", true);

This tells the PowerPlant to emit something across the network. In this case, we are emitting gameState, which is a GameState message. The target is nusight, signifying that it will be received by NUsight. true signifies that it is reliable.

Looking at line 112 of ScriptTuner.cpp, we can see an example of an INITIALIZE scoped emit statement.

Copy
emit<Scope::INITIALIZE>(std::make_unique<RegisterAction>(RegisterAction{
    id,
    "Script Tuner",
    {std::pair<float, std::set<LimbID>>(
        1, {LimbID::LEFT_LEG, LimbID::RIGHT_LEG, LimbID::LEFT_ARM, LimbID::RIGHT_ARM, LimbID::HEAD})},
    [this](const std::set<LimbID>&) {},
    [this](const std::set<LimbID>&) {},
    [this](const std::set<ServoID>&) {}}));

This tells the PowerPlant to emit something at system initialization. In this case, we are emitting a RegisterAction which registers the ScriptTuner module with the subsumption system.