API review

Proposer: Ze'ev Klapow

Present at review:

  • Jack O'Quin
  • Chad Rockey

What to Review

cfg Files

It is now possible to put parameters into groups like so:

group = gen.add_group("My Group")
group.add("my_group_param", int_t, 0, "An int within My Group", 0)

Groups can have subgroups:

group2 = group.add_group("My Second Group")

Unfortunately this dose not allow parameters to have unique names because in order to preserve backwards compatibility the parameters are still stored directly on the config object as well as within groups.

Python Server API

The config object that is passed to a nodes reconfigure callback now supports dot-syntax, rather than using a dictionary, however the dictionary still works for parameters.


Groups contain 4 main components parameters, subgroups, type and state. All except state are determined by the CFG file and cannot be changed. State allows groups to be disabled which can be done like so:

config.groups.My_Group.state = False

or in cpp

config.groups.my_group.state = false;

Note that in cpp all names are lower case to avoid name conflicts, group names in python are the same as given in the config.

The type field is an extra string in each group description, which is mainly relevant to the client, at the moment I am using it to change the display modes, I currently support "collapse" and "hide", collapse has a button to hide/display the group and hide simply hides/displays based on the state as set by the node.


The client now has a method get_group_descriptions, which returns a tree of groups containing parameters, get_param_descriptions is still available to get a list of all possible params. In order to make changes to the state of a group simply call update group as you would with parameters and add the key groups to the dictionary:

changes = {'groups':{'My_Group':True}}

You can also specify a section of the tree rather than individual groups, as it sometimes easier to simply modify the config object and pass it back to the client.


Reconfigure gui now supports the display of groups. By default groups with no type are simply displayed by a line and label. Additionally the gui now supports 'collapse' groups which have a button that toggle them on and off as well as 'hide' groups which are entirely invisible until activated. The default state for all groups is visible. using the proposed API many more display types could be implemented including tabs.

All of the code is available here https://kforge.ros.org/project/common/services/dynamicreconfig/ on the "groups" branch

You can use this rosinstall to get all of the code dynamic_reconfigure.rosinstall

dynamic_reconfigure has an example server in dynamic_reconfigure/test that demonstrates groups. You can run this by doing

rosrun dynamic_reconfigure testserver

and then launching the gui

rosrun dynamic_reconfigure reconfigure_gui

Question / concerns / comments

  • (Jack) Seems useful. Where is a version I can test with?

  • (Chad) Do we want to phase out the backwards compatibility for the duplicate names in the next (F-turtle?) version with warnings for this one? Allowing duplicates would make using reusing functions for groups easier. I'm assuming I'm reading it right, the description currently says it will not allow unique names.

    • (Jack) There are currently 107 packages listed in the wiki as using dynamic_reconfigure. It should be a very long time before we even consider phasing out backwards compatibility for this component.

  • (Jack) Is there any way to initialize the group state in the .cfg file? For example, I would like to declare a group type="collapse" with initial state False, so the group comes up hidden, but can be selected by the user. I don't think I should have to write server code for that.

  • (Jack) I see a brief description and example of the new Python server interface, but not much for C++. That is an important part of the API.

    The testserver.cpp example queries the state. I discovered by experiment that it can be set the same way. There's also one example above.

  • (Jack) The big problem with this component is that the original version was not properly documented. That makes it difficult to specify the groups changes clearly.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period


Package status change mark change manifest)

  • /!\ Action items that need to be taken.

  • {X} Major issues that need to be resolved

Wiki: dynamic_reconfigure/Reviews/7-1-11_groups (last edited 2011-07-15 04:20:49 by Ze'ev Klapow)