iCub-main
objectsPropertiesCollector

Provides a on-line yarp-oriented database to collect properties of objects that are of interest for your specific application. More...

+ Collaboration diagram for objectsPropertiesCollector:

Provides a on-line yarp-oriented database to collect properties of objects that are of interest for your specific application.

Copyright (C) 2010 RobotCub Consortium

Author: Ugo Pattacini

Date: first release 06/10/2010

CopyPolicy: Released under the terms of the GNU GPL v2.0.

Description

Provides a on-line yarp-oriented database to collect properties such as positions, colors, shapes, grasping points and so on about objects that are of interest for your specific application, i.e. normally real objects that the robot can play with but ideally any kind of objects you can think of. The user can set, get, add, remove items and make queries to the database.
Importantly, the module is capable of running in real-time.

Protocol

Notation used hereafter to explain available commands: [.] is a Vocab, "." is a string, <.> is a Value (i.e. string, double, int) or a List (so that also complex properties such as images can be attached to the objects).

Reserved properties tags:

The commands sent as bottles to the module port /<moduleName>/rpc are the following:

add
Format: [add] (("prop0" <val0>) ("prop1" <val1>) ...)
Reply: [nack]; [ack] ("id" <num>)
Action: a new item is added to the database with the given properties.
A unique identifier is returned that is used to access the item.

del
Format: [del] (("id" <num>) (propSet ("prop0" "prop1" ...)))
Reply: [nack]; [ack]
Action: remove from the database the specified properties belonging to the item specified with the given identifier.
The special command "del ((id <num>))" removes the whole item.
The special command "[del] (all)" clears the current content of the database.

get
Format: [get] (("id" <num>) (propSet ("prop0" "prop1" ...)))
Reply: [nack]; [ack] (("prop0" <val0>) ("prop1" <val1>) ...)
Action: return the required properties assigned to the stored item.
The special command "[get] ((id <num>))" returns all the properties.

set
Format: [set] (("id" <num>) ("prop0" <val0>) ...)
Reply: [nack]; [ack]
Action: add/modify properties of the stored item.

lock
Format: [lock] (("id" <num>))
Reply: [nack]; [ack]
Action: lock the specified item; this way only the port owner can modify it later on through a [set] request.

unlock
Format: [unlock] (("id" <num>))
Reply: [nack]; [ack]
Action: unlock the specified item.

owner
Format: [owner] (("id" <num>))
Reply: [nack]; [ack] ("owner_name")
Action: ask for the port name of the item owner; a name equal to "all" means that the item is not locked by any agent.

time
Format: [time] (("id" <num>))
Reply: [nack]; [ack] (<time>)
Action: retrieve the time elapsed in seconds from the last change occured on the stored item.
Negative values of <time> indicates that the item has not been modified since it was loaded within the database.

dump
Format: [dump]
Reply: [ack]
Action: ask the database to dump on the screen all the stored items along with their properties.

synchronous broadcast
Format: [sync] [start] <T>/[stop]
Reply: [nack]; [ack]
Action: ask the database to start/stop broadcasting its content to a yarp port each <T> seconds. The parameter <T> is optional.

asynchronous broadcast
Format: [async] [on]/[off]
Reply: [nack]; [ack]
Action: ask the database to enable/disable the broadcast toward a yarp port whenever a change in the content occurs.

ask
Format: [ask] (("prop0" "<" <val0>) || ("prop1" ">=" <val1>) ...)
Reply: [nack]; [ack] ("id" (<num0> <num1> ...))
Action: query the database to find all the items whose properties match the conditions given in the command. You can compose multiple conditions using the boolean operators such as "||" for or and "&&" for and and each condition has to be expressed giving the property name, the value to compare with and the corresponding relational operator (e.g. ">", "<=", "==", ...).
Commands such as "[ask] ((prop0) || (prop1))" will query whether the properties exist or not.
The special command "[ask] (all)" returns the whole set of ids present within the database.
In order to simplify the implementation, nested conditions such as (cond1) && ((cond2) || (cond3)) are not handled; however, this is not a real limitation since nested conditions can be properly expanded: indeed, the previous example can be cast back to (cond1)&&(cond2) || (cond1)&&(cond3).

quit
Format: [quit]
Reply: [ack]
Action: quit the module.

Libraries

Parameters

–name moduleName

–db dbFileName

–context contextName

–no-load-db

–no-save-db

–sync-bc <T>

–async-bc

–stats

Ports Accessed

None.

Ports Created

Input Data Files

None.

Output Data Files

None.

Configuration Files

None.

Tested OS

Linux and Windows.

Examples

Several examples of the requests you may forward to the database:

command: [add] ((name ball) (color red) (x 1))
reply: [ack] (id 0)
command: [add] ((name octopus) (color blue) (x 2))
reply: [ack] (id 1)
command: [set] ((id 1) (x 3))
reply: [ack]
command: [get] ((id 1))
reply: [ack] ((name octopus) (color blue) (x 3))
command: [ask] ((x < 10) && (color == blue))
reply: [ack] (id (1))
Author
Ugo Pattacini