-
Notifications
You must be signed in to change notification settings - Fork 11
Home
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.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 H22PRO-1136. 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 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 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).
There are several methods of installation available:
1. Download the source from either the repository (see "Repository," below) or a source archive, extract it somewhere, and install it into your Python distribution:
- 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 installc) 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\andC:\Python26\Scripts\, respectively (assuming Python 2.6 installed inC:\Python26\).2. 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 c, above).
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.
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
- 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