Support

GlobalConfig

Description

Loads global robot identity configuration and publishes it as a message for other modules.

This module provides a single source of truth for:

• player_id
• team_id

Values are read from GlobalConfig.yaml and can be overridden by command-line arguments.

Usage

Include this module early in your role so modules that depend on global robot identity can trigger correctly.

Optional command-line overrides:

• --player_id <number>
• --team_id <number>

If override values are invalid, the module logs an error and keeps the configured value.

Consumes

• extension::Configuration from GlobalConfig.yaml
• NUClear::message::CommandLineArguments

Emits

• message::support::GlobalConfig

SoccerConfig

Description

Loads soccer field dimensions from configuration and publishes a FieldDescription message used by localisation, vision, and behaviour modules.

In addition to copying field constants from YAML, the module computes derived values such as goalpost positions and goalpost top height.

Usage

Include this module in roles that require field geometry.

The module listens to configuration updates for FieldDescription.yaml and re-emits an updated message::support::FieldDescription when the file changes.

Configuration files are located at:

• module/support/configuration/SoccerConfig/data/config/FieldDescription.yaml
• module/support/configuration/SoccerConfig/data/config/webots/FieldDescription.yaml

Key configured values include field size, line width, goal dimensions, penalty area dimensions, and ball radius.

Consumes

• extension::Configuration from FieldDescription.yaml

Emits

• message::support::FieldDescription

LocalisationSimulator

Description

Utility module for inspecting localisation field transforms.

It periodically logs the Hfw transform matrix from message::localisation::Field, which is useful for simulator debugging and sanity-checking localisation output.

Usage

Include this module in a role when you want a simple heartbeat printout of the current field transform.

Every 3 seconds, if a message::localisation::Field is available, logs Field.Hfw

Consumes

• extension::Configuration from LocalisationSimulator.yaml
• message::localisation::Field

Console Log Handler

Description

Writes log messages to the console.

Usage

Once installed, this module will echo all NUClear log messages to standard output.

Consumes

• NUClear::message::LogMessage containing a message to be logged

DataLogging

Description

Logs serialisable neutrons in nbs files. It also creates nbs.idx files.

Usage

Add the neutron types that you want to record in the config file in the messages list field. Specify the directory you want the log files to be written in the output directories field, the actual nbs and idx files will be created in a subdirectory of the given directory with the same name as the role that these messages were created by running. To specify a maximum size before which the current nbs and idx files will be closed and new nbs and idx files to be created use the output output/split_size field.

Filenames will be of the format year, month, day, T, hours, _, minutes, _, seconds e.g. 20201110T13_31_50.

Files that are currently being written to will have an underscore prepended to the name, which will be removed when the file is closed.

Consumes

• extension::Configuration from DataLogging.yaml
• NUClear::message::CommandLineArguments (used to derive role/binary output folder)
• Dynamically registered serialisable message types enabled in messages config

Emits

• module::support::logging::DataLogging::DataLog (internal sync message used by the logger pipeline)

Dependencies

• NBS encoder/index utilities (utility::nbs::Encoder, utility::nbs::Index)
• zstr (compressed stream support)
• Python 3 at build time (generates per-message recorder handles)

DataPlayback

Description

DataPlayback is a module which will allow you to play back .nbs files as if they were happening in realtime. This can be very useful for when you are trying to diagnose a problem for which you have a recording as you can continuously play back the same data.

The module will buffer up packets from the future and emit them at the same rate that they were emitted originally.

Usage

In order to play back the messages, you need to create a role with this module that has the modules you wish to test. You then need to enable the message types that are the input to these modules by setting them to true in the configuration (e.g. message.input.Sensors: true). Make sure the .nbs file contains the messages you are trying to emit (you can check with ./b nbs stats file).

There are two methods to provide nbs files to this module, via the configuration file or via the command line. If the configuration file has arguments those are used first. If there are no files provided in the configuration file, the arguments from the command line are used instead. This is so that if you have another module in your role that relies on command line arguments you have an alternate way to provide these files.

You can provide multiple .nbs files and they will be played in sequence. For example ./b run <role> recordings/<nbs-file-a> recordings/<nbs-file-b> will run the role and play back

Notes

There is some weird behaviour that will occur when using this module that won't happen in a real system. Take note of these if they influence your usage

• If there are any timestamp fields in the messages, these will not be updated. If you are comparing the timestamps in the messages to the current time they will be wrong.
• When you are providing paths to .nbs files via a ./b run command they are relative to the build directory in docker. There is a symlink to recordings that is placed there to make any nbs file in recordings easier to use but outside of this path you will need to provide the full path from dockers perspective.

FileLogHandler

Description

Writes NUClear log output and reaction exceptions to a log file on disk.

The module listens to runtime log messages and reaction statistics, formats them with source information and level, and appends them to the configured file.

If a reaction reports an exception, it records exception details (and stack information in debug builds).

Usage

Configure the output file path in FileLogHandler.yaml:

• log_file: absolute or relative path to the log file

Behavior:

• Opens the configured file in append mode
• Adds a separator line when configuration is (re)loaded
• Serialises writes with a mutex
• Closes the file on shutdown

Consumes

• extension::Configuration from FileLogHandler.yaml
• NUClear::message::LogMessage
• NUClear::message::ReactionStatistics
• NUClear::Shutdown

MessageLogHandler

Description

This module provides an interface to take the LogMessage and ReactionStatistics messages from NUClear and recodes them into protobuf messages. These messages can then be sent using NetworkForwarder or recorded using DataLogging. Additionally it can be configured to ignore the display level of the logs so that the level can be adjusted at a later time for analysis.

Usage

Include this module and configure NetworkForwarder or DataLogging to forward the LogMessage and ReactionStatistics messages.

Consumes

• NUClear::message::LogMessage
• NUClear::message::ReactionStatistics

Emits

• message::nuclear::LogMessage
• message::nuclear::ReactionStatistics

NUsight

Description

This module simply emits sine wave data points to NUsight. It can be used to quickly test the connection between NUbots and NUsight.

Usage

Include the module in a role, and it will automatically emit messages.

Also ensure that sending data points are enabled in config/NUsight.yaml

Emits

• message::eye::DataPoint

Profiler

Description

The Profiler module in NUbots is designed for profiling the execution of reactions within the system. It measures the execution time of each reaction and aggregates statistical data, such as total, average, minimum, and maximum execution times. This data helps in understanding the performance characteristics of different parts of the system.

Usage

Include this module in role.

Emits

• ReactionProfiles aggregated profiling data, including individual reaction profiles with statistics on execution times.

ReactionTimer

Description

Logs execution duration for reactions using NUClear reaction statistics.

For each ReactionStatistics message, it computes elapsed time from the reaction start and finish timestamps and logs the result in milliseconds.

Usage

Include this module when profiling or debugging reaction performance.

Configuration:

• module/support/ReactionTimer/config/ReactionTimer.yaml
• log_level

Consumes

• extension::Configuration from ReactionTimer.yaml
• NUClear::message::ReactionStatistics

Signal Catcher

Description

This module catches and handles signals.

Usage

When SIGINT (interrupt - Ctrl+C) is received, SignalCatcher attempts to shut down the NUClear power plant and terminate the program. If another SIGINT is received (e.g. because shutting down the power plant did not fully terminate the program) it immediately exits the program with return code 1.

If SIGSEGV (segmentation fault) is received, SignalCatcher throws a message::SegmentationFault exception.