rtctree module

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

Requirements

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

Installation

There 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:
    1. Deploy the source.
       $ cd /home/blurgle/src/
       $ tar -xvzf rtctree-2.0.0.tar.gz
    2. Run setup.py.
       $ python setup.py install
    3. 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\) .
  • 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.

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 ()
This is a tree like a file system created by searching the name server ~ to get the naming context, component and manager. It can be handled in exactly the same way as handling a normal file system. The tree represents the naming contexts, managers, and components registered in all 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 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.

Paths

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
Shows the component called ConsoleIn0.rtc registered under naming_context on the name server running on localhost. When you want to get the object of that component from the tree, you need to change the path to 'Python' with parse_path.
 ['/', '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 the sample example code, refer the rtshell Source code. You can find how to use the rtctree library to perform most of the actions possible using RTSystemEditor.

Changelog

3.0

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

2.0

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

Download

latest Releases : 2.0.0-RELESE

2.0.0-RELESE Download page

Number of Projects

Choreonoid

Motion editor/Dynamics simulator

OpenHRP3

Dynamics simulator

OpenRTP

Integrated Development Platform

AIST RTC collection

RT-Components collection by AIST

TORK

Tokyo Opensource Robotics Association

DAQ-Middleware

Middleware for DAQ (Data Aquisition) by KEK