• Introduction
• Requirements
• Installation
• Environment variables
• The RTC Tree
  • Building the tree
  • Paths
  • Useful functions
• API naming conventions
• Repository
• Further documentation and examples
• Changelog
  • 3.0
  • 2.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 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

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

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.

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

 ['/', '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.

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.