Error message

  • Can not get file info (nid=1503, src=tree.PNG)
  • Can not get file info (nid=1503, src=tree.PNG)

rtctree

rtctree is a Python library for interacting with and managing running RT Components.

Introduction

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 developed at the National Institute of Advanced Industrial Science and Technology. Approval number . The development was financially supported by the New Energy and Industrial Technology Development Organisation Project for Strategic Development of Advanced Robotics Elemental Technologies. This software is licensed under the Eclipse Public License -v 1.0 (EPL). See http://www.opensource.org/licenses/eclipse-1.0.txt.

Requirements

rtctree requires omniorb-py, including omniidl with the Python backend. If you have installed OpenRTM-python, you will have these installed already. If not, you will need to install them manually.

rtctree uses the new string formatting operations that were introduced in Python 2.6. It will not function with an earlier version of Python. It has not been tested with Python 3 and it is likely that several changes will be necessary to make it function using this version of Python.

For Ubuntu users, if you are using a version of Ubuntu prior to 9.04, you will need to install a suitable Python version by hand. You may want to consider upgrading to Ubuntu 9.04 or later (10.04 offers LTS).

Installation

There are several methods of installation available:
  • Download the source from either the repository (see Repository, below) or
  • a source archive, extract it somewhere, and install it into your Python distribution:
    1. Extract the source, e.g. to a directory /home/blurgle/src/rtctree
       $ cd /home/blurgle/src/
       $ tar -xvzf rtctree-2.0.0.tar.gz
    2. Run setup.py to install rtctree to your default Python installation:
       $ python setup.py install
    3. If necessary, set environment variables. These should be set by default, but if not you will need to set them yourself. On Windows, you will need to ensure that your Python site-packages directory is in the PYTHONPATH variable and the Python scripts directory is in the PATH variable. Typically, these will be something like C:\Python26\Lib\site-packages\ and C:\Python26\Scripts\, respectively (assuming Python 2.6 installed in C:\Python26\).
  • Use the Windows installer. This will perform the same job as running setup.py (see #2), but saves opening a command prompt. You may still need to add paths to your environment variables (see step iii, above).

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 core of the library is the RTC Tree:

 from rtctree.tree import create_rtctree
 tree = create_rtctree()
This is a file system-like tree built by parsing name servers to find directories, components and managers. You can treat it exactly the same way as you treat a normal file system. The tree represents the naming contexts, managers and components registered all on known name servers in a tree structure:

tree.PNG

Each directory in the tree represents a naming context, which may be the root context of a name server, a normal naming context, or a manager. These are represented by NameServer, Directory and Manager objects, respectively.


Name servers are treated as directories off the root directory, /. Below them are files and sub-directories. A sub-directory represents a naming context below the root naming context of a name server or a manager.


Files are components, represented by the Component class.


Component objects store a variety of information about the component they represent. You can access the component's ports, configuration sets, and so on. Use these objects to change configuration values, connect ports to each other, start and stop components, etc.


Using Manager objects, you can create new component instances at run-time, and remove running component instances.


All nodes in the tree also store the CORBA object reference to the object they represent. By accessing this object, you can call the IDL methods. If something is not currently available in rtctree, calling the IDL method on the CORBA object directly will be able to achieve what you want to do.

Building the tree

The arguments to the tree factory function determine which name servers are parsed to build the tree. See that function's documentation for details. In general, you can pass in a list of server addresses and/or a list of paths (the first component of each path is treated as a name server). The environment variable RTCTREE_NAMESERVERS will also be checked for any additional name servers to parse. This is a semi-colon separated list of name server addresses.

Paths

Nodes in the tree are addressed using paths. A path is a list of strings, each representing a level in the tree one deeper than the previous list item. Absolute paths are necessary to address into the tree object. Addressing from nodes allows relative paths, provided that the path exists below the node.


When represented as text, these paths resemble file system paths. The root of the tree is represented by / (\ on Windows systems). The first level of entries are name server addresses. Entries below the first level are components, managers and naming contexts (which are represented as directories). The utility function parse_path will parse a text string path into a list of path entries that can be used to address nodes in the tree.


For example, the path

 /localhost/naming_context/ConsoleIn0.rtc
represents the component ConsoleIn0.rtc, registered in the naming_context naming context on the name server running at localhost. When used to find the node in the tree representing this component, the path should be a Python list:

 ['/', 'localhost', 'naming_context', 'ConsoleIn0.rtc']

Useful functions

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.

Repository

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.

Changelog

3.0

rtctree is a Python library for interacting with and managing running RT Components.

Introduction

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 developed at the National Institute of Advanced Industrial Science and Technology. Approval number . The development was financially supported by the New Energy and Industrial Technology Development Organisation Project for Strategic Development of Advanced Robotics Elemental Technologies. This software is licensed under the Eclipse Public License -v 1.0 (EPL). See http://www.opensource.org/licenses/eclipse-1.0.txt.

Requirements

rtctree requires omniorb-py, including omniidl with the Python backend. If you have installed OpenRTM-python, you will have these installed already. If not, you will need to install them manually.

rtctree uses the new string formatting operations that were introduced in Python 2.6. It will not function with an earlier version of Python. It has not been tested with Python 3 and it is likely that several changes will be necessary to make it function using this version of Python.

For Ubuntu users, if you are using a version of Ubuntu prior to 9.04, you will need to install a suitable Python version by hand. You may want to consider upgrading to Ubuntu 9.04 or later (10.04 offers LTS).

Installation

There are several methods of installation available:
  • Download the source from either the repository (see Repository, below) or
  • a source archive, extract it somewhere, and install it into your Python distribution:
    1. Extract the source, e.g. to a directory /home/blurgle/src/rtctree
       $ cd /home/blurgle/src/
       $ tar -xvzf rtctree-2.0.0.tar.gz
    2. Run setup.py to install rtctree to your default Python installation:
       $ python setup.py install
    3. If necessary, set environment variables. These should be set by default, but if not you will need to set them yourself. On Windows, you will need to ensure that your Python site-packages directory is in the PYTHONPATH variable and the Python scripts directory is in the PATH variable. Typically, these will be something like C:\Python26\Lib\site-packages\ and C:\Python26\Scripts\, respectively (assuming Python 2.6 installed in C:\Python26\).
  • Use the Windows installer. This will perform the same job as running setup.py (see #2), but saves opening a command prompt. You may still need to add paths to your environment variables (see step iii, above).

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 core of the library is the RTC Tree:

 import rtctree.tree
 tree = rtctree.tree.RTCTree()
This is a file system-like tree built by parsing name servers to find directories, components and managers. You can treat it exactly the same way as you treat a normal file system. The tree represents the naming contexts, managers and components registered all on known name servers in a tree structure:

tree.PNG

Each directory in the tree represents a naming context, which may be the root context of a name server, a normal naming context, or a manager. These are represented by NameServer, Directory and Manager objects, respectively.


Name servers are treated as directories off the root directory, /. Below them are files and sub-directories. A sub-directory represents a naming context below the root naming context of a name server or a manager.


Files are components, represented by the Component class.


Component objects store a variety of information about the component they represent. You can access the component's ports, configuration sets, and so on. Use these objects to change configuration values, connect ports to each other, start and stop components, etc.


Using Manager objects, you can create new component instances at run-time, and remove running component instances.


All nodes in the tree also store the CORBA object reference to the object they represent. By accessing this object, you can call the IDL methods. If something is not currently available in rtctree, calling the IDL method on the CORBA object directly will be able to achieve what you want to do.

Building the tree

The arguments to the tree factory function determine which name servers are parsed to build the tree. See that function's documentation for details. In general, you can pass in a list of server addresses and/or a list of paths (the first component of each path is treated as a name server). The environment variable RTCTREE_NAMESERVERS will also be checked for any additional name servers to parse. This is a semi-colon separated list of name server addresses.

Paths

Nodes in the tree are addressed using paths. A path is a list of strings, each representing a level in the tree one deeper than the previous list item. Absolute paths are necessary to address into the tree object. Addressing from nodes allows relative paths, provided that the path exists below the node.


When represented as text, these paths resemble file system paths. The root of the tree is represented by / (\ on Windows systems). The first level of entries are name server addresses. Entries below the first level are components, managers and naming contexts (which are represented as directories). The utility function parse_path will parse a text string path into a list of path entries that can be used to address nodes in the tree.


For example, the path

 /localhost/naming_context/ConsoleIn0.rtc
represents the component ConsoleIn0.rtc, registered in the naming_context naming context on the name server running at localhost. When used to find the node in the tree representing this component, the path should be a Python list:

 ['/', 'localhost', 'naming_context', 'ConsoleIn0.rtc']

Useful functions

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.

Repository

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.

Changelog

3.0

  • Do not treat exceptions while parsing managers as fatal
  • Other zombie-catching improvements
  • Detect zombie managers
  • New API calls to get composite component information
  • New API call to get a connection from a port by ID
  • Added API ability to give away the ORB
  • Added path formatter
  • Pretty-print exceptions
  • Other performance improvements (e.g. removed double parsing)
  • Added ability to restrict parsed paths (improves startup speed)
  • Added Zombie node
  • New API call to make a component exit
  • Removed defunct create_rtctree call
  • Exposed remove_node API call
  • Changed node.full_path to return a list, added node.full_path_str

2.0

  • Parse more information about execution contexts
  • Added the ability to use a provided ORB instead of creating one
  • Exposed the reparse_connections() method
  • New API call to get the ORB used for a node
  • New API call to unbind a name from a context
  • Allow access to more CORBA objects
  • Catch more zombies
  • Handle unknown CORBA object types.
  • Handle the case of unknown port owners.
  • Added locks to make rtctree objects thread-safe.
  • Added API for forcing a re-parse of any object in the tree.
  • Cleaned up init functions for proper inheritence handling.
  • New API call to get the state of a component in a specific EC.
  • New API call to update the state of a component in a specific EC.

latest Releases

For Begginers

Windows msi(installer) package (only trying samples)

Development environment is required for RT-Component development. See download page for details.

Number of Projects

Join our slack

Enter email address for slack invite.

OpenHRP3

Dynamics simulator

OpenHRI

Human-Robot-Interaction RTCs

OpenRTP

Integrated Development Platform

OpenINVENT

Mobile Robot RTCs