Configuration and Script System

The configuration and script system
Alex Biddulph GitHub avatarYsobel Sims GitHub avatar
Updated 10 June 2022

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
| webots/
│   └── 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/webots/ExampleModule.yaml is an optional file and allows you to provide platform-specific overrides for specific configuration values, in this case it would provide overrides for any webots robots. This is useful when webots and the real nugus robot use different configurations values. 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. It overrides the default and platform-specific configuration files. Similarly, config/robocup/ExampleModule.yaml allows for the robocup role to further override configuration values. It overrides the default, platform-specific and robot-specific configuration files.

It is intended that all configuration values exist in the default configuration file and that only a subset of configuration values appear in the platform-specific, 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 platform-specific override is intended to allow for different configuration values between real robots and webots. For instance, the real NUgus robot uses a different Visual Mesh network compared to the robots run in the Webots simulator.

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/PlatformName/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/RobotName/ModuleName.yaml exists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration
  4. 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
  5. If any of these 3 configuration files are modified then steps 1-4 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.

Robot platform is derivated from the hostname/robot name. The hostname of binaries run in Docker is docker, unless the binary being run contains the word webots. In this case, the hostname will be webots.

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.

Robot platform is derivated from the hostname/robot name. The hostname of binaries run in Docker is docker, unless the binary being run contains the word webots. In this case, the hostname will be webots.

Foundations
Mathematics
Subsystems
Input
Copyright © 2022 NUbots - CC-BY-4.0
Deploys by Netlify