Add gzyarp::ConfigurationOverride plugin to permit to override initialConfiguration tag in gzyarp::ControlBoard plugins

[traversaro]

Fix #159 .

This PR still misses some tests, but other then that is complete. It adds a gzyarp::ConfigurationOverride plugin that can be used to override the initialConfiguration tag of gzyarp::ControlBoard plugins in the world files, and hence specify an arbitrary initial configuration for models even without modifying the model itself.

To describe the plugin itself, I would just copy the documentation that I added in the PR.

gzyarp::ConfigurationOverride functionalities

name	filename
gzyarp::ConfigurationOverride	gz-sim-yarp-configurationoverride-system

The gzyarp::ConfigurationOverride plugin can be attached to a model in order to override the configuration of any other gz-sim-yarp plugin that is attached to the same model and that occurs in xml after the insertion of the ConfigurationOverride plugin, even in a nested model.

Each ConfigurationOverride plugin points to another plugin using a unique identifier, and can override the values of its configuration parameters.

The parameters and plugins currently supported by the gzyarp::ConfigurationOverride plugin are:

Parameter SDF Element name	Overrided Plugin
initialConfiguration	gzyarp::ControlBoard

Any other parameter is not overriden. The plan for the future is to support more parameters in the gzyarp::ConfigurationOverride.

Usage

Add the gzyarp::ConfigurationOverride plugin to the model SDF before the overriden plugin declaration (i.e. before the <include>) and define the yarpDeviceName attribute of the yarpPluginConfigurationOverride element as the yarpDeviceName of the YARP plugin that will be overriden.

A typical usage of the gzyarp::ConfigurationOverride plugin is to specify parameters of a model included in a world, without the need to modify the model itself, that is convenient when the model is installed by another package and so it cannot be easily modified.

An example of its usage can be seen in the tutorial/single_pendulum/single_pendulum_world.sdf world.

The relevant snippet is:

    <!-- This is an example of how to override the initial configuration -->
    <plugin name='gzyarp::ConfigurationOverride' filename='gz-sim-yarp-configurationoverride-system'>
      <!-- The yarpPluginConfigurationOverride device is used to override the configuration of
           a given yarp device, whose name is specified via the yarpDeviceName attribute -->
      <yarpPluginConfigurationOverride yarpDeviceName='controlboard_plugin_device'/>

      <!-- If you want to override the initialConfiguration xml element, set it -->
      <initialConfiguration>1.57079632679</initialConfiguration>
    </plugin>

The original initialConfiguration of the controlboard_plugin_device was 0.0, while via the gzyarp::ConfigurationOverride plugin we override its value to be 1.57079632679 rad (i.e. 90 degrees).

Migration from gazebo-yarp-plugins

In gazebo-yarp-plugins with Gazebo Classic, the libgazebo_yarp_configurationoverride.so plugin can be used to override parameters in nested plugins, for example:

    <plugin name='configuration_override' filename='libgazebo_yarp_configurationoverride.so'>
      <yarpPluginConfigurationOverride plugin_name='controlboard_plugin'/>
      <initialConfiguration>1.57079632679</initialConfiguration>
    </plugin>
    <include>
      <uri>model://single_pendulum/model.sdf</uri>
    </include>

the equivalent syntax with gz-sim-yarp-plugins is:

    <!-- This is an example of how to override the initial configuration -->
    <plugin name='gzyarp::ConfigurationOverride' filename='gz-sim-yarp-configurationoverride-system'>
      <!-- The yarpPluginConfigurationOverride device is used to override the configuration of
           a given yarp device, whose name is specified via the yarpDeviceName attribute -->
      <yarpPluginConfigurationOverride yarpDeviceName='controlboard_plugin_device'/>

      <!-- If you want to override the initialConfiguration xml element, set it -->
      <initialConfiguration>1.57079632679</initialConfiguration>
    </plugin>

    <include>
      <uri>model://single_pendulum/model.sdf</uri>
    </include>

Beside the change of the name and filename attributes of the plugin element, the main difference is how we identify the plugin of which we want to override the parameters: in gazebo-yarp-plugins we use the name element of the overriden plugin, that may be unique even if you have multiple controlboards. In gz-sim-yarp-plugins, the name element of each controlboard plugin must be gzyarp::ControlBoard, so it will not be unique among different controlboards. For this reason, to identify the plugin to override we use instead the yarpDeviceName, that is unique for each plugin in the same model, and that needs already to be defined to expose each plugins with Network Wrapper Servers instantiated by the gzyarp::RobotInterface plugin.

[traversaro]

Note that the functionality of the added gzyarp::ControlBoard plugin are quite limited at the moment, but given its internal implementation, my goal is to eventually extend its functionality with the following features:

• Permit to specify arbitrary enable and disable tags for gzyarp::RobotInterface plugin (to solve Ensure that enable_tags and disable_tags options can be passed in a world SDF file to the gazebo_yarp_robotinterface of an included model #163 )
• Permit to override generic parameters specified in YARP's .ini files (useful for example to override PID gains)
• (Unsure about this, but it would be cool/convenient) specify the joints parameters (like initial configuration, PID gains, etc etc) in a more user-friendly oriented way, i.e. by passing the joint list of the joints that we want to override, and override just those joints, without the need to manually specify the yarpDeviceName of all devices involved.

However, this PR already achieves parity with gazebo-yarp-plugins, so it solves one of the most important points in #229 .

[traversaro]

fyi @Nicogene @martinaxgloria, this was another missing features in gz-sim-yarp-plugins that was complicating the migration from gazebo-yarp-plugins .

[traversaro]

Ah, given that I did not add tests, how did I checked this is working?

I run the tutorial/single_pendulum/model.sdf and tutorial/single_pendulum/single_pendulum_world.sdf and compare their initial position, as tutorial/single_pendulum/single_pendulum_world.sdf now uses the configuration override plugin:

cd gz-sim-yarp-plugins/
pixi shell
cd tutorial
export GZ_SIM_RESOURCE_PATH=$GZ_SIM_RESOURCE_PATH:`pwd`
cd single_pendulum
gz sim model.sdf
gz sim single_pendulum_world.sdf

[traversaro]

I added some tests to check that this feature works as intended in https://github.com/robotology/gz-sim-yarp-plugins/tree/addoverrideinitialconftests, but the test fail with mysterious errors like:

8: (2025-02-09 10:46:15.686) [error] [SystemLoader.cc:106] Failed to load system plugin: (Reason: No plugins detected in library)
8: - Requested plugin name: [gzyarp::ConfigurationOverride]
8: - Requested library name: [gz-sim-yarp-configurationoverride-system]
8: - Resolved library path: [/home/traversaro/gz-sim-yarp-plugins/.build_ionic/lib/libgz-sim-yarp-configurationoverride-system.so]

even if the exact same plugin is loaded normally by gz-sim . Interestingly, the same error occurs in ControlBoardCommons test even in master, so I guess this is a separate problem, and it does not make sense to block the PR on this.

[traversaro]

I added some tests to check that this feature works as intended in https://github.com/robotology/gz-sim-yarp-plugins/tree/addoverrideinitialconftests, but the test fail with mysterious errors like:

8: (2025-02-09 10:46:15.686) [error] [SystemLoader.cc:106] Failed to load system plugin: (Reason: No plugins detected in library)
8: - Requested plugin name: [gzyarp::ConfigurationOverride]
8: - Requested library name: [gz-sim-yarp-configurationoverride-system]
8: - Resolved library path: [/home/traversaro/gz-sim-yarp-plugins/.build_ionic/lib/libgz-sim-yarp-configurationoverride-system.so]

even if the exact same plugin is loaded normally by gz-sim . Interestingly, the same error occurs in ControlBoardCommons test even in master, so I guess this is a separate problem, and it does not make sense to block the PR on this.

Moving the test out of ControlBoardCommonsTest.cc and on its own file fixed the test, fortunately as the tests highlighted some bugs that are now solved.

[traversaro]

Now the PR also has tests, so it is ready for review. I did not curated the commits, so if anyone merges please remember to merge with squash.

[traversaro]

I also did a bit of cleanup of the instances of modelScopedName . As depending on a plugin a plugin can also be child of world, model or sensor, I changed most of the instances of modelScopedName to parentEntityScopedName, hopefully this does not adds too much complexity to the PR.

[LoreMoretti]

Awesome!

[traversaro]

@xela-95 thanks for finding the problem in the example world. I documented and fixed the problem in d03178f .

[xela-95]

Thanks @traversaro for addressing the issue in harmonic! Just checking the logs I saw a difference in the two versions:

Harmonic(v8):

[DEBUG] gz-sim-yarp-controlboard-system : robot scoped name:  model/single_pendulum_with_overidden_initial_configuration/model/single_pendulum

Ionic(v9):

[DEBUG] gz-sim-yarp-controlboard-system : robot scoped name:  world/tutorial_controlboard/model/single_pendulum_with_overidden_initial_configuration/model/single_pendulum

[xela-95]

Good to go for me!

[xela-95]

If it is not a problem I will squash together some commits and then merge since lot fo them are meaningful :)

[traversaro]

Feel free to curate the commit as you prefer!