[Playerstage-developers] Property Bags

[Geoffrey B. <g....@au...>]

Toby has just committed some code that adds a new feature to Player: 
property bag support. This consists of a new member variable of all 
drivers (propertyBag), a generic interface with 6 messages for getting 
and setting integer, double and string properties, and client support. 
The general design for this was done by Toby (implementation is my fault 
for complaining to him that I needed something to do).

With a property bag, we can set and get various properties of a driver 
separate from the specific device interfaces. Each driver has a set of 
properties that are set at construction time. As an example of how this 
works, I'll use a laser driver using a generic ranger interface (not yet 
implemented, I'll get to that next weekend).

The driver class for the laser device's driver contains some members of 
the type DoubleProperty (base class: Property). Each property stores a 
value (in this case, a double; IntProperty and StringProperty are also 
available). Let's say the driver has two properties to represent its 
minimum and maximum range:

DoubleProperty MinRange, MaxRange;

In its constructor, it sets default values for these properties:

LaserDriver::LaserDriver (ConfigFile *cf, int section)
     : MinRange (0~m), MaxRange (4.5~m)
{

It must also add these properties to its bag using the driver class 
member function RegisterProperty:

     this->RegisterProperty ("minrange", &this->MinRange, cf, section);
     this->RegisterProperty ("maxrange", &this->MaxRange, cf, section);

Note the the config file info being passed in to this function: 
properties can read their values from the config file themselves, so the 
driver code doesn't have to do it manually anymore.

Now, clients can read these properties using the 
playerc_device_get_*prop functions (and the C++ equivalents). They can 
also set them, so if your driver has a value that can be configured by 
clients, you can use a property. This means you don't have to design a 
new interface to do it. More importantly, it will help avoid interface 
creep. We won't need to add a new interface to customise an existing one 
just for some unique parameter.

There is also a new utility called playerprop. You can use this to read 
and set properties of a driver. It's fairly self-explanatory.

Also note that the intent of properties is to configure drivers and 
provide configuration information, not data. They are not meant to 
replace the opaque interface for sending large quantities of data, or 
data that updates regularly (particularly as they are only ever pulled 
by the client, never pushed out).

In the future when designing new interfaces, we should try and avoid 
adding messages or message members for values that are specific to one 
or a few implementations, and note in the interface's docs that those 
properties should be provided by drivers implementing the interface. We 
want to avoid having interfaces that are too specific. Property bags 
should allow for much more generality by providing a level of 
customisation for drivers. In the long term we may want to look at 
replacing configuration requests with properties.

Geoff

-- 
Robotics research group, University of Auckland
http://www.ece.auckland.ac.nz/~gbig005/