rtctree is a Python library for interacting with and managing running RT Components.
rtctree is a Python library providing an easy-to-use API for interacting with running RT Components and RTM-based systemsrunning on OpenRTM-aist-1.0. It allows developers to manage these systems from other programs without needing to learn the CORBA API. Components can be started, stopped, connected together, have their configuration changed, and so on.
This software is being developed by National Institute of Advanced Industrial Science and Technology, with support of the next generation robot intelligent technology development project of NEDO (New Energy and Industrial Technology Development Organization).
- Python module for ominorb-py and omniidl and omniidl is required.
- Python 2.6 or higher is required because it uses functions that do not exist under Python 2.5.
- If you are using Ubuntu 9.04, you will need to install Python 2.6 manually. Therefore, Ubuntu 9.04 or higher is recommended.
InstallationThere are several methods of installation available:
- After downloading from the repository (see [[repository> #repo] below)] or source archive, decompress and install it in the appropriate directory:
- Deploy the source.
$ cd /home/blurgle/src/ $ tar -xvzf rtctree-2.0.0.tar.gz
- Run setup.py.
$ python setup.py install
- Set environment variables as necessary. This is set by default, but if it is not set you need to set it yourself. On Windows, please make sure that Python's site-packages directory is set to PYTHONPATH environment variable and Python script's directory is set to PATH environment variable. Normally these are C:\Python 26\Lib\site-packages\ and C:\Python 26\Scripts\ (if Python was installed on C:\Python 26\) .
- Deploy the source.
- We recommend using installer on Windows. By using setup.py you can set it more easily than the result. However, depending on the environment, it may be necessary to further set environment variables.
The following environment variables are used:
|RTCTREE_ORB_ARGS||A list of arguments, separated by semi-colons, to pass to the ORB when creating it. Optional.|
|RTCTREE_NAMESERVERS||A list of name server addresses, separated by semi-colons, to parse when creating the RTCTree. Each server in the list will be added to the tree. Optional.|
The only variable that should normally be set by the user is RTCTREE_NAMESERVERS. Set this to a list of name server addresses, separated by semi-colons, that you want rtcshell to interact with. For example, in a Bash shell, you can run the following:
$ export RTCTREE_NAMESERVERS=localhost;192.168.0.1:65346;example.com
The RTC Tree
The main part of the library is the RTC tree.
import rtctree.tree tree = rtctree.tree.RTCTree ()
\ |-+localhost | |-+naming_context | | |--ConsoleIn0.rtc | | |--ConsoleOut0.rtc | | | |--another_naming_context | |--Sensor0.rtc | |-+192.168.0.5 |--Motor0.rtc |--Controller0.rtc
Each directory in the tree is the normal naming context or root server's root context. The root context of the name server is indicated by NameServer class. Also, the naming context is represented by the 'Directory' class, and the manager is represented by Manager class.
The name server is treated as a directory from the root directory. Below that are files and subdirectories. The subdirectory points to the naming context and manager under the root context.
The files are components and managers. Components are represented by the Component class.
Contains various information about the component represented by the component object. You can activate and deactivate components, manage component ports, connect ports, and configure configuration settings.
You can create new component instances in the manager and erase the components.
Every node in the tree also contains a reference to the CORBA object in the objects they represent. You can call IDL methods by accessing this object. Even if there are currently impossible functions with rtctree, you can call IDL methods directly using this CORBA object.
Building the tree
The argument of the factory function of the tree ( create_tree () ) specifies the name server to be analyzed for constructing the tree. Please refer to the function's documentation for details. In general, you can build a tree by passing a list of nameserver addresses or a list of paths. The environment variable RTCTREE_NAMESERVERS is also checked.
Nodes in the tree are specified by path. The path is a list of strings. The level on the right is one level deeper than the one on the left. An absolute path is required to specify a tree object. If the path exists below the node, relative path specification from the node is also possible.
These path strings are similar to file system path specifications. The root of the tree is indicated by / ( \ for Windows). The first level is the address of the name server. The level below it is Component, Manager and Naming Context (as a directory). The function parse_path changes the path of the string to the path for the RTC tree.
For example, the following path:
['/', 'localhost', 'naming_context', 'ConsoleIn0.rtc']
Useful member functions of the RTCTree class and node classes that will be of particular interest are shown below. This is not a complete list of all available functionality. Users are encouraged to check the full API documentation for additional functionality, and examine the rtcshell source code for usage examples.
|RTCTree.has_path||Checks if a path is present in the tree. Use this to quickly check if a component exists.|
|RTCTree.get_node||Retrieves a node from the tree based on a path. Use this to get components, directories, etc. from the tree.|
|RTCTree.is_component||Tests if the given path points to a Component object. Tree nodes have a property, is_component, that performs the same function directly on a node. is_directory, is_manager and is_nameserver functions and properties are also available.|
|RTCTree.iterate()||Use this function to perform an action on every node in the tree, or only those nodes matching a given filter. The return result of each call will be returned from iterate as a list. This function is particularly useful. See rtcshell's rtls command for an example of using iterate().|
|Node.children||This property gives a list of the node's children. You can use this, for example, to get all the components in a directory of the tree.|
|Node.full_path||The full path of the node from the root of the tree.|
|Node.name||The name of this node; i.e. its entry in the tree.|
|Node.parent_name||The name of this node's parent (if it has one).|
|Node.root||Given a node, use this property to get the root node of the tree it is in, on which you can perform nearly all functions you can perform on the tree object.|
|Component.activate_in_ec()||Activate the component in the execution context at the given index. For most components, only one EC is present and so the index should be 0.|
|Component.deactivate_in_ec()||Deactivate the component in an execution context.|
|Component.reset_in_ec()||Reset the component in an execution context.|
|Component.state_in_ec()||Get the state in a specific execution context.|
|Component.alive||Test if the component is alive.|
|Component.owned_ecs||The list of execution contexts owned by the component.|
|Component.participating_ecs||The list of execution contexts the component is participating in.|
|Component.state||The overall state of the component, created by merging its state in each execution context.|
|Component.state_string||The overall state of the component as a string.|
|Component.disconnect_all()||Disconnect all connections from all ports of this component.|
|Component.get_port_by_name()||Find a port of this component by name.|
|Component.ports||The list of the component's ports. Similar lists exist for input, output and service ports. Component.connected_ports The list of the component's ports that are connected. Similar lists exist for connected input, output and service ports.|
|Component.object||Get the CORBA LightweightRTObject that this component wraps.|
|Component.activate_conf_set||Activate a configuration set by name.|
|Component.set_conf_set_value||Set the value of a parameter in a configuration set.|
|Component.active_conf_set||The currently-active configuration set.|
|Component.active_conf_set_name||The name of the currently-active configuration set.|
|Component.conf_sets||The list of configuration sets.|
|Port.connect()||Connect this port to another port.|
|Port.disconnect_all()||Disconnect all connections on this port.|
|Port.get_connection_by_dest()||Get a connection on this port by the destination port.|
|Port.get_connection_by_name()||Get a connection on this port by its name.|
|Port.connections||The connections on this port.|
|Port.is_connected||Checks if this port is connected or not.|
|Port.name||The name of this port.|
|Port.object||The CORBA PortService object that this component wraps.|
|Port.name||The port's owner (usually a Component object).|
|Port.porttype||The type of the port (DataInPort, DataOutPort or CorbaPort).|
|Connection.disconnect()||Remove this connection between ports.|
|Connection.ports||The list of ports involved in this connection.|
|ConfigurationSet.has_param()||Checks if a parameter is present in the configuration set.|
|ConfigurationSet.set_param()||Sets the value of a parameter in this configuration set.|
|ExecutionContext.activate_component()||Activate a component within this execution context.|
|ExecutionContext.deactivate_component()||Deactivate a component within this execution context.|
|ExecutionContext.reset_component()||Reset a component within this execution context.|
|ExecutionContext.get_component_state()||Get the state of a component within this execution context.|
|ExecutionContext.running||Check if this execution context is running or not.|
|Manager.create_component()||Create a new component instance.|
|Manager.delete_component()||Destroy a component instance.|
|dict_to_nvlist()||Converts a Python dictionary into a CORBA namevalue list.|
|nvlist_to_dict()||Converts a CORBA namevalue list into a Python dictionary.|
API naming conventions
rtctree follows the standard Python naming conventions as laid out in PEP8.
Most importantly, the private, internal API functions begin with an underscore (_). If a function begins with an underscore, it is not intended for use outside the class and doing so could lead to undefined behaviour. Only use those API functions that do not begin with an underscore and have a docstring in your programs.
The latest source is stored in a Git repository at github. You can download it as a zip file or tarball by clicking the "Download Source" link in the top right of the page. Alternatively, use Git to clone the repository. This is better if you wish to contribute patches.
$ git clone git://github.com/gbiggs/rtctree.git
Further documentation and examples
For further documentation, see the Doxygen-generated API documentation.
For examples, see the rtcshell set of utilities. These illustrate using rtctree to perform most of the actions possible using RTSystemEditor.
- I warned an exception.
- Improved handling of zombies.
- Zombie detection manager.
- Added API to get information on composite components.
- Added API to obtain connection by ID from port.
- Added API to pass ORB.
- Added path formatter.
- We made it easy to display exceptions easily.
- Improved performance
- Added the function to limit the path to be analyzed.
- Added a zombie node.
- Added API to terminate the component.
- The create_rtctree () function was deleted. Please use RTCTree ().
- Added remove_node () API.
- Changed node.full_path to a list and added node.full_path_str.
- We have analyzed more information about execution context.
- The ORB object is given externally.
- I made reparse_connections () function public.
- Added a new API to get the ORB used in the node.
- Added new API to unbind name from context.
- Enabled access to more CORBA objects.
- Zombie recognition efficiency has improved.
- Corrected how to handle unknown CORBA objects.
- Fixed how to handle port whose owner is unknown.
- Added lock to thread-safe rtctree object.
- Added an API to reload objects in the tree.
- Fixed the init function for proper inheritence handling.
- Added a new API to get the state of the component in a specific EC.
- Added a new API to update the state of components within a particular EC.