Add ROS 1 to ROS 2 migration note for group parameter handling

[MariuszSzczepanikSpyrosoft]

Add information to help developers safely migrate parameter updates by highlighting that ROS 2's default set_parameters service behaves differently than ROS 1's dynamic_reconfigure regarding atomic updates. Points users to set_parameters_atomically service to maintain atomic behavior during migration.

[fujitatomoya]

I am not sure why you are comparing dynamic_reconfigure package behavior that is NOT in rosmaster parameter XMLRPC server against the ROS 2 parameter services? i think what we would want to add here is that difference between rosmaster XMLRPC service behavior and ROS 2 parameter services of each node. (for example, ros::param::getCached is not supported with ROS 2 parameter interface.)

the default set_parameters, i do not really understand default by here. because ROS 2 provides both set_parameters and set_parameters_atomically that are different services with good explanation around line 93-96. if we only have set_parameters service that works in default non-atomic operation, but we can change this behavior with option to be atomic, then i think we can say default is non-atomic operation?

i may be mistaken something here...

just fyi, rosmaster parameter XMLRPC server only handles parameter request one by one.
https://github.com/strawlab/ros_comm/blob/6f7ea2feeb3c890699518cb6eb3d33faa15c5306/tools/rosmaster/src/rosmaster/master_api.py#L327-L351

[kscottz]

The document and sub-section are the right place for this to land and this greatly clarifies the available API.

This works for me. Thanks a bunch! We really appreciate it!

[MariuszSzczepanikSpyrosoft]

I am not sure why you are comparing dynamic_reconfigure package behavior that is NOT in rosmaster parameter XMLRPC server against the ROS 2 parameter services? i think what we would want to add here is that difference between rosmaster XMLRPC service behavior and ROS 2 parameter services of each node. (for example, ros::param::getCached is not supported with ROS 2 parameter interface.)

the default set_parameters, i do not really understand default by here. because ROS 2 provides both set_parameters and set_parameters_atomically that are different services with good explanation around line 93-96. if we only have set_parameters service that works in default non-atomic operation, but we can change this behavior with option to be atomic, then i think we can say default is non-atomic operation?

i may be mistaken something here...

just fyi, rosmaster parameter XMLRPC server only handles parameter request one by one. https://github.com/strawlab/ros_comm/blob/6f7ea2feeb3c890699518cb6eb3d33faa15c5306/tools/rosmaster/src/rosmaster/master_api.py#L327-L351

Hi @fujitatomoya, thank you for your detailed feedback! I understand your concern about comparing different parameter handling mechanisms.

My addition focuses specifically on migrating parameter groups from ROS 1 to ROS 2, particularly for users who currently rely on dynamic_reconfigure for groups parameter updates. While you're absolutely right that the rosmaster XMLRPC server handles parameters individually, many ROS 1 systems use dynamic_reconfigure specifically for group parameter updates (like PID tuning) where atomic operations are crucial.

I noticed that the current documentation doesn't address how to migrate from dynamic_reconfigure to ROS 2's parameter system, which might lead developers to incorrectly use set_parameters when they need groups operations. You make a valid point about the word "default", I can remove it since ROS 2 indeed provides two distinct services.

[fujitatomoya]

My addition focuses specifically on migrating parameter groups from ROS 1 to ROS 2

in that case, probably we would want to add this description to https://docs.ros.org/en/rolling/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.html instead?
that is where explains the parameter migration from ROS 1 to ROS 2.

current change adds the ROS 1 migration note to generic ROS 2 parameter concept, i do not think this is the right place for the people who are looking for the migration information?

many ROS 1 systems use dynamic_reconfigure specifically for group parameter updates (like PID tuning) where atomic operations are crucial.

how about adding the section for Interacting with parameters, and links it to the migration note? that would guide the user who uses dynamic_reconfigure package and ROS 2 set_parameters_atomically service?

[MariuszSzczepanikSpyrosoft]

My addition focuses specifically on migrating parameter groups from ROS 1 to ROS 2

in that case, probably we would want to add this description to https://docs.ros.org/en/rolling/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.html instead? that is where explains the parameter migration from ROS 1 to ROS 2.

current change adds the ROS 1 migration note to generic ROS 2 parameter concept, i do not think this is the right place for the people who are looking for the migration information?

many ROS 1 systems use dynamic_reconfigure specifically for group parameter updates (like PID tuning) where atomic operations are crucial.

how about adding the section for Interacting with parameters, and links it to the migration note? that would guide the user who uses dynamic_reconfigure package and ROS 2 set_parameters_atomically service?

Thank you @fujitatomoya for your valuable feedback and suggestions.

I understand your point about the migration guide being a logical place for this information. However, after analyzing the documentation structure, I believe the current location might be more appropriate for the following reasons:

• the Migration Parameters guide (Migrating-Parameters.rst) focuses primarily on high-level parameter concepts and YAML file migration patterns, rather than implementation-specific details. I want to avoid mixing logical level migration concepts with C++ interface implementations.
• the About-Parameters.rst file already contains a dedicated "Migrating from ROS 1" section that discusses implementation level differences (please check: https://github.com/ros2/ros2_documentation/pull/4983/files#diff-ca66c3d91ee020d44cf53a260be4bfb2b5575260941d96a8759b3b65160e1364L117-L118), including code interfaces. This seems like the natural place to document the migration path for parameter group handling.

I'm open to further discussion about the best way to structure this information.

[fujitatomoya]

the Migration Parameters guide (Migrating-Parameters.rst) focuses primarily on high-level parameter concepts and YAML file migration patterns, rather than implementation-specific details.

i think this can be changed to add more concept, it does not have to be YAML file migration patterns.

the About-Parameters.rst file already contains a dedicated "Migrating from ROS 1"

this is true.

How about adding the section and description in https://docs.ros.org/en/rolling/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.html#migrating-parameters, and add the link from Migrating from ROS 1 like YAML file migration patterns? in the future, we can add more package specific information like this there too, instead of adding this ROS 1 package specific migration explanation in ROS 2 that is my major concern for the maintenance. i am also open for discussion on where this kind of description should stay. thanks for iterating.

[MariuszSzczepanikSpyrosoft]

YAML file migration patterns

OK @fujitatomoya, if I understand correctly, you propose moving the content of the current migrating-from-ros-1 section (https://docs.ros.org/en/rolling/Concepts/Basic/About-Parameters.html#migrating-from-ros-1) along with my PR modifications to:
https://docs.ros.org/en/rolling/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.html

This way, the Table of Contents would look something like this:

   Migrating YAML Parameter Files
      YAML file example
      Accessing parameters inside node
      Feature parity
 + Migration code from ROS 1 
     + Parameter groups

For me, this is fine, and I can make this modification. However, I want to ensure I fully understand the concept and avoid any misunderstandings or breaking the existing structure.

@fujitatomoya, is this correct from your point of view?
@kscottz, @clalancette, @audrow do you have any strong opinions about these changes?

[fujitatomoya]

yes that is what i mean. we can keep the links about migration procedure but main purpose is that contents align with main page title in consistent. i think we would not want to keep adding the ROS 1 specific packages migration explanation on https://docs.ros.org/en/rolling/Concepts/Basic/About-Parameters.html#migrating-from-ros-1

let's wait for the feedback from other people before changing it, thanks for your patience and understanding 👍

[MariuszSzczepanikSpyrosoft]

It looks like there are no objections to the files structure changes for the ROS1 to ROS2 migration guide, so I've adopted @fujitatomoya suggestion. I've moved the migration-specific content to the dedicated migration guide file.

[fujitatomoya]

@MariuszSzczepanikSpyrosoft really appreciate your effort. last comment, after that i will approve this. CC: @kscottz

[kscottz]

If @fujitatomoya is happy after this last change, then I am happy.

@MariuszSzczepanikSpyrosoft we really appreciate your help with this!

[MariuszSzczepanikSpyrosoft]

I have committed the patch proposed by @fujitatomoya .

Huge thanks @kscottz, @fujitatomoya for the great collaboration and valuable feedback during the review!

[fujitatomoya]

@MariuszSzczepanikSpyrosoft sorry that is my bad coming from suggested patch, could you apply the fix?

[fujitatomoya]

@MariuszSzczepanikSpyrosoft i just merged this into rolling, backports are staging.

again, thank you very much!