The Configuration System
The NUbots configuration system is based on a hierarchical YAML file system.
The hierarchical structure is as follows
config/├── euler/│ └── ExampleModule.yaml├── gauss/│ └── ExampleModule.yaml├── robocup/│ └── ExampleModule.yaml└── ExampleModule.yamlThe file config/ExampleModule.yaml must exist for every module that uses configuration. This file defines all of the configuration for the module.
config/euler/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 euler 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.
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, each robot may have slightly different transforms from the head to the pitch joint.
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
- The default configuration file
config/ModuleName.yamlis loaded. This forms the base configuration for the module - A check is made to see if
config/PlatformName/ModuleName.yamlexists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration - A check is made to see if
config/RobotName/ModuleName.yamlexists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration - A check is made to see if
config/RoleName/ModuleName.yamlexists. If it does, it is loaded and all values found therein override the equivalent values in the base configuration - 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.
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/├── booster1/│ └── Stand.yaml└── booster2/ └── Stand.yamlTo reiterate how the script system loads script files
- A check is made to see if
config/RobotName/Script.yamlexists. If it does, it is loaded. - If it doesn't exist, a check is made to see if
config/PlatformName/Script.yamlexists. 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.
