Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
API for interacting with running RT-Components and managing RTM-based systems using OpenRTM-aist. http://openrtm.org
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Type||Name||Latest commit message||Commit time|
|Failed to load latest commit information.|
======= RTCTree ======= Introduction ============ 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. 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 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. Installation ============ 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. 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:: \ |-+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. 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. .. _PEP8: http://www.python.org/dev/peps/pep-0008/ Further documentation and examples ================================== 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. 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 .. _github: http://github.com/gbiggs/rtctree Changelog ========= 4.2 --- - Implemented support for FSM4RTC (@yosuke) - Added doctests (@yosuke) 4.1 --- - Switched setup from distutils to setuptools - Dropped support for Python 2.6 4.0 --- - 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. 3.0.1 ----- - Compatibility release for rtshell-3.0.1. 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