New Parameter Server API

Contents

New Parameter Server API

Glossary

Public/Private parameter: A public parameter is a parameter that can be access by any node directly or using any tool, e.g. services or topics. A private parameter is an internal parameter of a node. It just can be access by the owner node.
Static/Dynamic parameter: A static parameter is a parameter that can be set just once, i.e. constants. To change the value of a static parameter, it has to be deleted and created again. A dynamic parameter is a parameter that can be set at any time.
Global/Local parameter: A global parameter lifecycle is tied to the roscore. It lives until it is explicitily deleted or the roscore die. A local parameter lifecycle is tied to a node. It lives as long as the node lives.
Group of parameters: A group of parameters is a set of parameters that have something in common. A group of parameters makes easier to manage a bunch of them.
On update notifications: Nodes receive a notification with the new value of a parameter.
On change notifications: Nodes receive a notification with a request of change for a parameter. A change can be accepted or rejected.
External documentation: Any documentation reference which is not in the source code. e.g. wiki. A file such as .cfg (used by dynamic_reconfigure) is in the source code.

Current tools

Parameter Server

Parameters in the parameter server are:

global. They die when the roscore die.
public. Any node can change any value. Parameters can also be semi-private parameters because this parameters are protected from accidental name collision, but they are accessible from other parts of the system.
semi-dynamic. Parameters can be changed at any time but is quite expensive.
no grouping.
no on update notifications.
no on change notifications.
External documentation needed.

Benefits/Drawbacks

+ Init parameters before the node is created to initialize the node with those values.
+ If a node suddenly dies, its configuration can be checked.
- Can't know which node is using which parameters.
- Explicit check of parameters values to watch for changes.
- Change of a parameter could be ignored.
- Changing and requesting parameters is expensive (performance).

Dynamic reconfigure

Parameters in dynamic reconfigure are:

local. Lifecycle tied to the node.
public. Any node can change the values.
dynamic. Parameters can be changed at any time.
Grouping by means of .cfg file.
on update notifications using a topic.
on change notification using a callback and a topic.
No external documentation needed (.cfg file)

Benefits/Drawbacks

+ Configuration of parameters isolated in a file (.cfg). Documentation in source code.
+ Reuse of existing tools (topics). Easier to maintain.
+ Implicit parameter grouping with the config file.
+ GUI and CLI to request and change parameters.
- Creating a new node to manage the parameters.
- Parameters can be rejected without explicitly notify the node requesting for the change.
- Can't guarantee nodes receive correctly an update notification.
- No c++ API to request and change parameters.

Decisions

Public/Private parameters

Private parameters are necessary to initialize a node. Currently a mix between default values in source code and values in parameter server is used. The parameter server value has priority before the default value in source code. This parameters shouldn't be accessible, except for debug purposes. In that case they could be read but not written.

Public parameters change the behaviour of the node. They should be accessible to every node in an easy form.

For debugging it would be nice to have all parameters (public and private) to check why the node fail.

Static/Dynamic parameters

Static parameters can only be set in the initialization. They can be read but not written (just like constants). Static parameters are useful to publish any information of the node that can't be change. It is just to inform. Any attempt to change a static parameter should be rejected.

In the other hand, dynamic parameters can be set at any time. Changing a parameter changes the behaviour of the node.

Both parameters are useful but dynamic parameters are more important than static parameters.

Global/Local parameters (Maybe this is not the best name for this section)

Global parameters lifecycle is tied to the system (roscore). This parameters live as long as the system is up. All parameters in the parameter server are global. Global parameters are useful to initialize a node with values declared at runtime.

Local parameters lifecycle is tied to one node. The parameter exist as long as the node live. Local parameters encourage encapsulations and independence of the nodes.

When possible local parameters should used rather than global. I think an hybrid system is the best solution. Use global parameters to initialize local parameters with custom values. After that use local parameters.

There are some cases that a global parameters have to be used in the system. e.g. to share state of the system among all nodes. Unstead of using a global parameter my suggestion would be to use a top level node that carries this parameter and use the notification system implemented to notify nodes of changes.

Group of parameters

Grouping parameters will ease handling a set of parameters. Parameters that are used to perform the same goal should be grouped.

I think nodes should have just one group of parameters. If a node needs two different groups of parameters, maybe it is an indicator that a node is doing too many things. Nodes should do just one thing.

On update notifications

Important! Useful to be aware of changes in other nodes.

On change notifications

The node receives a notifications of change. The node can accept or reject the new parameters. Again, to encourage encapsulation only the parameter's owner should be requested. Any other node should not take part in that decision.

Even if the parameters are accepted or not the requestor has to be informed.

External documentation

Having parameters documented in an external system, like the wiki, it is quite easy to not have code and wiki in sync. Parameters should be self documented in source code. They could be documented in an external file or in the source code itself.

Nodes already have some external files to describe services and messages. I think forcing the users to create a new file to define parameters is not a good idea. I think a better solution would be defining parameters in the source code itself, so the user focus just in his code.

With this last solution, even if the user wants to declare parameters in an independent file, it can be done. Parameters can be declared in a header file a imported in the main source code file.

Features list

Public dynamic parameters
: Parameters are public. Every node can read and write any parameter. This is how it is implemented now.
: + Easy to access a parameter.
: - Every node can change any parameter.
: - An incorrect value may drop the system down (indispensable watch and control changes)

Notes: (WJW) Actually, this is how static parameters are implemented now, the dynamic_reconfigure system does not allow for global "dynamic" parameters. I guess we have to better describe the static vs dynamic parameters, when I say static I mean parameters in the parameter server, because they are usually only checked once when a node starts, though it is true that they can change during run time.

Private dynamic parameters
: Parameters are private to a node.
: + Increase encapsulation.
: - Who can change the parameter value?

On update notifications
: Nodes are notified when a parameter changes.
: + Do something when a parameter changes.

On change notifications / reject changes
: Nodes are notified when a parameter change is requested. Changes can be validated or not.
: + Control parameter values.
: - If nodes have access to any parameter, any node can accept or reject parameters of other nodes.

Parameter grouping
: Handle a bunch of parameters together.
: + Make easier handling a group of parameters that have a goal in common.
: - Too big groups can bury parameters.

External configuration
: Use an external file to setup the parameters.
: + Documentation of the parameters in source code.
: - Document parameters in external reference.
: - Code bloat. Too many configuration files (msg, srv, params...)

Static parameters
: Constants. Can be set just once.
: + Forbid changes on a parameter. Just informative data.

Parameter lifecycle with master
: Parameter lifecycle is tide to the master. Global parameters?
: + If a node crash, parameters are still available.
: - When a parameter shutdown, usually node parameters are no longer needed (Manual cleaning?)

Parameter lifecycle tide to a node
: If a node dies, the parameters of that node are removed.
: - If a node crash, parameters aren't available anymore.
: + If a parameter shutdowns, parameters are automatically deleted.

Last read
: Last time a parameter was readed
: + Detect useless parameters