Provides a on-line yarp-oriented database to collect properties of objects that are of interest for your specific application.
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:
- id is used to specify the unique integer identifier assigned to each stored item.
- lifeTimer specifies the forgetting factor given in seconds, meaning that after lifeTimer seconds since its creation, the item is removed automatically from the database. The user can read this property at run-time, can even modify it or assign it to an object after its creation.
- propSet is used to specify a list of properties over which execute the given command.
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
- YARP libraries.
Parameters
–name moduleName
- The parameter moduleName identifies the module's name; all the open ports will be tagged with the prefix /<moduleName>/. If not specified objectsPropertiesCollector is assumed.
–db dbFileName
- The parameter dbFileName specifies the name of the database to load at startup (if already existing) and save at shutdown.
–context contextName
- To specify the context where to search for the database file; objectsPropertiesCollector is the default context.
–no-load-db
- If this options is given then an empty database is started.
–no-save-db
- If this option is given then the content of database is not saved at shutdown.
–sync-bc <T>
- Broadcast the database content each T seconds. If not specified, a period of 1.0 second is assumed.
–async-bc
- Broadcast the database content whenever a change occurs.
–stats
- Enable statistics printouts.
Ports Accessed
None.
Ports Created
- / <moduleName>/rpc the remote procedure call port used to send requests to the database and receive replies.
- / <moduleName>/broadcast:o the port used to broadcast the database content in synchronous and asynchronous mode.
- / <moduleName>/modify:i the port used to modify the database content complying with the data format implemented for the broadcast port.
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:
