Configuration and Script System

The configuration and script system

The Configuration System

The NUbots configuration system is based on a hierarchical YAML file system.

The hierarchical structure is as follows

config/
├── nugus1/
│   └── ExampleModule.yaml
├── nugus2/
│   └── ExampleModule.yaml
├── robocup/
│   └── ExampleModule.yaml
└── ExampleModule.yaml

The file config/ExampleModule.yaml must exist for every module that uses configuration. This file defines all of the configuration for the module. config/nugus1/ExampleModule.yaml is an optional file and allows you to provide robot-specific overrides for specific configuration values, in this case it would provide overrides for the nugus1 robot. Similarly, config/robocup/ExampleModule.yaml allows for the robocup role to further override configuration values.

It is intended that all configuration values exist in the default configuration file and that only a subset of configuration values appear in the robot-specific and role-specific override files.

There are exceptions to this, the Camera module being the best example.

The Camera module introduces the serial_number field in the robot-specific override files as every robot will have different cameras installed in it. However, it makes no sense for the default configuration file to contain the serial_number field as there is no viable default value for this field.

The robot-specific override is intended to allow configuration values to be tweaked to account a slight variation in the robots hardware. For instance, the cameras on each robot have different serial numbers.

The role-specific override is intended to change a modules behaviour based on which role is running. For instance, disabling the transmission of certain NUsight2 traffic while playing a competition game.

To reiterate how the configuration system loads and merges configuration files

  1. The default configuration file config/ModuleName.yaml is loaded. This forms the base configuration for the module
  2. A check is made to see if config/RobotName/ModuleName.yaml exists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration
  3. A check is made to see if config/RoleName/ModuleName.yaml exists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration
  4. If any of these 3 configuration files are modified then 1-3 are run again

It it also supported for a module to have multiple configuration files arranged into a folder hierarchy. In this case the configuration system is directed to monitor for any changes in an entire folder. Once again, the Camera module provides a good example of this. The same rules still apply, however, rather than the "default file" needing to exist, the "default folder" must exist. The merging rules will apply on a per-file basis whenever a change to a file is detected in the folder that is being monitored.

A module can create multiple Configuration reactions, each one monitoring a different file or folder. The above detailed rules apply to each reaction individually.

The Script System

The script system works very much like the configuration system described above. However, default scripts are moved to a platform type folder and the merging of values is skipped as it doesn't make sense to try and merge two scripts.

In the script system, we first check for a robot-specific script. If a robot-specific script does not exist, then we check for a platform-specific script.

scripts/
├── nugus/
│   └── Stand.yaml
└── nugus2/
   └── Stand.yaml

To reiterate how the script system loads script files

  1. A check is made to see if config/RobotName/Script.yaml exists. If it does, it is loaded.
  2. If it doesn't exist, a check is made to see if config/PlatformName/Script.yaml exists. If it does, it is loaded.
Foundations
Mathematics
Subsystems
Input
Copyright © 2021 NUbots - CC-BY-4.0
Deploys by Netlify