rtt_dynamic_reconfigure

This package provides a way to manipulate the properties of an Orocos RTT component via the ROS dynamic_reconfigure interface.

Dynamic reconfigure uses a combination of ROS topics, services, and the parameter server to enable quick reconfiguration of parameters over the network.

Usage

With an automatically generated config

The easiest way to use rtt_dynamic_reconfigure is to use the special AutoConfig config type. AutoConfig automatically generates a dynamic_reconfigure config description from the set of properties of the TaskContext it is loaded into. No new properties will be created.

rtt_dynamic_reconfigure already comes with a precompiled service plugin for the AutoConfig type. Simply add a dynamic_reconfigure server to any component by loading the reconfigure service:

import("rtt_dynamic_reconfigure");
loadService("my_component", "reconfigure")
my_component.reconfigure.advertise("/my_component")

The disadvantage of this method is that the minimum and maximum values requrired for dynamic_reconfigure are unknown. The current values of the properties are advertised as default values. However, you can overwrite the automatically choosen minimum/maximum values before calling the advertise() operation:

import("rtt_dynamic_reconfigure");
loadService("my_component", "reconfigure")
my_component.reconfigure.min.int_property = 0
my_component.reconfigure.max.int_property = 100
my_component.reconfigure.advertise("~/my_component")

Using a custom config file

The rtt_dynamic_reconfigure package comes with a templated rtt_dynamic_reconfigure::Server<ConfigType> class that implements the core functionality of a dynamic_reconfigure server. Usually the ConfigType class header is generated automatically from a *.cfg file by dynamic_reconfigure’s generate_dynamic_reconfigure_options() cmake macro. This config file describes all available parameters and their minimum, maximum and default values.

In order to use rtt_dynamic_reconfigure with a custom config, you first need to create the .cfg file as explained in this tutorial. Afterwards you can add a rtt_dynamic_reconfigure service plugin to your package:

project(my_package)
find_package(dynamic_reconfigure)
generate_dynamic_reconfigure_options(cfg/MyPackage.cfg)

orocos_plugin(my_package_reconfigure_service src/reconfigure_service.cpp)
add_dependencies(rtt_dynamic_reconfigure_tests_service ${PROJECT_NAME}_gencfg)

The reconfigure_service.cpp source file instantiates the rtt_dynamic_reconfigure::Server<ConfigType> for the new config type MyPackageConfig, implements the rtt_dynamic_reconfigure::Updater<ConfigType> class that explains how to fill the config from a PropertyBag and vice-versa and registers the server as a service plugin:

#include <rtt_dynamic_reconfigure/server.h>
#include <my_package/MyPackageConfig.h>         // <-- This header is created by generate_dynamic_reconfigure_options(cfg/MyPackage.cfg)

using namespace my_package;

namespace rtt_dynamic_reconfigure {

template <>
struct Updater<MyPackageConfig> {
  static bool propertiesFromConfig(MyPackageConfig &config, uint32_t level, RTT::PropertyBag &bag) {
    setProperty<int>("int_param", bag, config.int_param);
    setProperty<double>("double_param", bag, config.double_param);
    setProperty<std::string>("str_param", bag, config.str_param);
    setProperty<bool>("bool_param", bag, config.bool_param);
    return true;
  }
  static bool configFromProperties(MyPackageConfig &config, const RTT::PropertyBag &bag) {
    getProperty<int>("int_param", bag, config.int_param);
    getProperty<double>("double_param", bag, config.double_param);
    getProperty<std::string>("str_param", bag, config.str_param);
    getProperty<bool>("bool_param", bag, config.bool_param);
    return true;
  }
};

} // namespace rtt_dynamic_reconfigure

RTT_DYNAMIC_RECONFIGURE_SERVICE_PLUGIN(MyPackageConfig, "my_package_reconfigure")

The rtt_dynamic_reconfigure::setProperty<T>(...) and rtt_dynamic_reconfigure::getProperty<T>(...) helper functions can be used in the Updater implementation. Properties that do not exist yet in the owner’s TaskContext will be created automatically.

Alternatively, the TaskContext in which the service is loaded can inherit and implement the Updater<MyPackageConfig> class directly. In this case you do not need to provide a specialized version of it.

Note: The Updater<ConfigType>::propertiesFromConfig(...) implementation should create properties that are references to the respective fields in the ConfigType struct. This is the case if the properties are added with bag->addProperty(const std::string &name, T &attr) or with the rtt_dynamic_reconfigure::setProperty<T>(...) helper function.

Once the service plugin is compiled you can load it in any component. The properties with the given names

import("rtt_ros");
ros.import("my_package");
loadService("my_component", "my_package_reconfigure")
my_component.reconfigure.advertise("~/my_component")

Overriding the update operation

Normally rtt_dynamic_reconfigure updates all properties of the TaskContext with the standard RTT::updateProperties() call running in the owner’s thread. Properties cannot be updated while the updateHook() is executed. For the case you want more control over the property updates, you can add a bool updateProperties(const RTT::PropertyBag &source, uint32_t level) operation with a custom implementation to the owner component. If this operation exists, it is used instead of the default implementation. The source bag is the bag filled in a previous Updater<ConfigType>::propertiesFromConfig(...) call.

Adding a property update notification callback

Sometimes it is required that the component is notified whenever properties have been updated by rtt_dynamic_reconfigure. If a void notifyPropertiesUpdated(uint32_t level) operation exists, it is called after every parameter update from a ROS service call.

Service API

reconfigure.advertise(string ns)

Advertise the dynamic_reconfigure topics and service server in the namespace ns.

reconfigure.updated()

Notifies the rtt_dynamic_reconfigure server that some property values have been updated and need to be republished to update the user interface.

reconfigure.refresh()

Refreshs the config description with their updated minimum, maximum and default values. For the AutoConfig config type also rediscovers newly added properties and removes deleted ones.

reconfigure.min, reconfigure.max, reconfigure.dflt

These PropertyBags mirror the properties of the dynamic_reconfigure config and hold the minimum, maximum and default values. Call reconfigure.refresh() after every update to republish the updated config description.

Changelog for package rtt_dynamic_reconfigure

2.9.2 (2019-05-15)

2.9.1 (2017-11-16)

• Merge with version 2.8.6

2.9.0 (2017-05-02)

• rtt_dynamic_reconfigure: create a partially filled PropertyBag from a Config message that only has a subset of fields
• rtt_dynamic_reconfigure: support both, non-const and const updateProperties callback signatures This is an improved version of https://github.com/orocos/rtt_ros_integration/pull/81 that is backwards-compatible to existing components that provide the const-variant of the callback.
• rtt_dynamic_reconfigure: allow the update callback to change the values in the propertybag This fixes a thread-safety issue with the previous commit b603585e9f74b3a553347301b44c73b0249856a1. But the user-defined update callback has to update the referenced bag manually in case it modified some property values.
• rtt_dynamic_reconfigure: publish updated property values in setConfigCallback() instead of desired once Rebuild new_config ConfigType from owner's PropertyBag before serializing and publishing dynamic_reconfigure msg from PropertyBag. The user might have modified the property values in one of the callbacks.
• rtt_dynamic_reconfigure: fixed potential deadlock in refresh() for RTT prior to 2.9 We do not know for sure which thread is calling this method/operation, but we can check if the current thread is the same as the thread that will process the update/notify operation. If yes, we clone the underlying OperationCaller implementation and set the caller to the processing engine. In this case RTT <2.9 should always call the operation directly as if it would be a ClientThread operation: https://github.com/orocos-toolchain/rtt/blob/toolchain-2.8/rtt/base/OperationCallerInterface.hpp#L79 RTT 2.9 and above already checks the caller thread internally and therefore does not require this hack.
• Added individual changelogs and bumped versions to 2.9.0
• Contributors: Johannes Meyer, Viktor Kunovski

2.8.6 (2017-11-15)

• rtt_dynamic_reconfigure: fix a bug that duplicate ids when generating a parameter description from a property tree The [id]{.title-ref} field of each groups in a dynamic_reconfigure/ConfigDescription message must be unique and some groups might reference another as their parent. Without this patch the ids were assigned locally and were only unique within the same group, which confused rqt_reconfigure and the dynparam console client when they try to rebuild the tree hierarchy in more complex cases.
• Contributors: Johannes Meyer

2.8.5 (2017-03-28)

• Merge pull request #86 from orocos/rtt_dynamic_reconfigure-check-updated-properties rtt_dynamic_reconfigure: report updated property values in the service response (indigo-devel)
• Contributors: Johannes Meyer

2.8.4 (2016-11-26)

2.8.3 (2016-07-20)

• rtt_dynamic_reconfigure: fixed potential deadlock in refresh() for RTT prior to 2.9
• rtt_dynamic_reconfigure: set owner of default updateCallback implementation
• Contributors: Johannes Meyer

2.8.2 (2015-06-12)

• rtt_dynamic_reconfigure: added support for Property composition and decomposition and fixed reconfiguration of nested properties
• rtt_dynamic_reconfigure: fixed AutoConfig maximum value for type unsigned int
• rtt_dynamic_reconfigure: fixed property updating from config in AutoConfig
• Contributors: Johannes Meyer

2.8.1 (2015-03-16)

• see rtt_ros_integratoin/CHANGELOG.rst