RTCTree is a Python library providing an easy-to-use API for interacting with running RT Components and RTM-based systems running on OpenRTM-aist-1. 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 H23PRO-1229. 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 GNU Lesser General Public License version 3 (LGPL3). See LICENSE.txt.

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 requires Python 2.7. 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.

Sphinx must be installed to build the documentation.

There are several methods of installation available:

1. (Preferred method) Use pip to install the PyPi package.

a. Install pip if it is not already installed. See https://pip.pypa.io/en/latest/installing/

b. Execute the following command to install RTCTree::

$ pip install rtctree

2. Download the source from either the repository (see "Repository," below) or a source archive, extract it somewhere, and install it into your Python distribution:

a. Extract the source, e.g. to a directory /home/blag/src/rtctree

b. Run setup.py to install RTCTree to your default Python installation::

$ python setup.py install

3. On Windows, use the Windows installer.

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 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::

|-+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 represents a naming context, which may be a normal naming context or the root context of a name server. These are represented by NameServer and Directory objects.

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.

Files are components and managers, represented by the Component and Manager classes, respectively.

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.

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.

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.

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 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.

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.

.. _PEP8: http://www.python.org/dev/peps/pep-0008/

For further documentation, see the generated API documentation.

For examples, see the rtshell set of utilities. These illustrate using RTCTree to perform most of the actions possible using RTSystemEditor.

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

.. _github: http://github.com/gbiggs/rtctree

• Implemented support for FSM4RTC (@yosuke)
• Added doctests (@yosuke)

• Switched setup from distutils to setuptools
• Dropped support for Python 2.6

• Added complete support for the ExecutionContext interface.
• Support for the Logger SDO interface.
• Support for the ComponentObserver SDO interface.
• Support three-or-more port connections.
• Deprecated Port.get_connection_by_dest()
• Added Port.get_connections_by_dest()
• Added Port.get_connections_by_dests()
• Fixed a bug where finding a connection with a given destination would return all connections on the port.

• Compatibility release for rtshell-3.0.1.

• 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

• 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