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.yamlThe 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
- 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, 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.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.
