Description

rtshell provides commands used to manage individual RT components and managers, as well as complete RT Systems. It can be used with the OpenRTM-aist middleware or middlewares that use a compatible CORBA-based introspection system.

Many of the commands allow components and managers running on nameservers to be treated like a file system. Directories can be entered, components can be cat'd and activated/deactivated/reset, connections made and removed, and so on. Other commands are used in conjunction with RtsProfile XML/YAML files to manage complete RT Systems.

The commands are aimed at users of OpenRTM-aist who wish to manage components on low-resource systems, systems where a GUI is not available (particularly where no network connection is available to manage components from another computer), as well as those who face other difficulties using RTSystemEditor. Being familiar with using a command-line is a benefit when using these commands of rtshell.

Commands

rtact

Activate components.

rtcat

View component information and meta-data.

rtcheck

Check the consistency of a running system against an RTSProfile.

rtcomp

Create composite components.

rtcon

Connect ports together.

rtconf

View and change configuration parameters and sets.

rtcryo

Preserve a running system as an RTSProfile.

rtcwd

Change the current working directory in the RTC Tree.

rtdeact

Deactivate components.

rtdel

Delete registrations from a name server.

rtdis

Disconnect ports.

rtdoc

Print RT-Component documentation.

rtexit

Make an RT-Component stop running and exit.

rtfind

Search for components, managers, etc. in the known name servers.

rtinject

Inject data into an input port.

rtlog

Record and replay logs of data sent by ports.

rtls

List a directory in the RTC Tree.

rtmgr

Use managers to create and delete RT-Components.

rtprint

Display the data being written by an output port.

rtpwd

Print the current working directory in the RTC Tree.

rtreset

Reset components in the error state.

rtresurrect

Restore a running system from an RTSProfile.

rtstart

Start an entire RT-System using an RTSProfile.

rtstodot

Visualise the running RT-System using the dot file format.

rtstop

Stop an entire RT-System using an RTSProfile.

rtteardown

Remove all connections in an RT-System using an RTSProfile.

RTC Tree

The commands operate on the RTC Tree. This is a file system-like tree built by parsing name servers to find directories, components and managers. It can be treated like a normal file system.

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.

The name servers parsed to build the tree are taken from two sources. The first is the path given to a command. This is appended to the current working directory of the tree, and the first element is treated as a name server.

The second source for name servers is the RTCTREE_NAMESERVERS environment variable. This is a semi-colon separated list of name server addresses.

Shell completion

Users of a Bash-compatible shell can use the included completion script to make using the commands easier. The script is installed in ${prefix}/share/rtshell. Run the following command to load it:

$ source bash_completion

This can be added to the ~/.bashrc file to have it loaded in every new shell instance. Here are some examples of completion:

$ rtcwd [TAB]
$ rtcwd localhost/
$ rtcwd localhost/[TAB]
$ rtcwd localhost/kenroke.host_cxt/
$ rtcwd localhost/kenroke.host_cxt/[TAB][TAB]
ConsoleIn0.rtc  ConfigSample0.rtc  manager.mgr  Sensor0.rtc
$ rtcwd localhost/kenroke.host_cxt/[ENTER]
$ rtconf ConfigSample0.rtc set [TAB]
double_param0  double_param1  int_param0     int_param1     str_param0
str_param1     vector_param0
$ rtcon Sensor0.rtc:[TAB]
in   out

System requirements

rtshell requires rtctree 3.0. It must be installed for the commands to function.

The commands that work with RTSProfile files require rtsprofile 2.0. It must be installed for these commands to function.

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

rtinject, rtlog and rtprint require the Python version of OpenRTM-aist.

For Ubuntu users using a version of Ubuntu prior to 9.04, a suitable Python version must be installed by hand. Consider upgrading to Ubuntu 9.04 or later (10.04 offers LTS).

Paths

rtshell uses paths to indicate objects in the RTC Tree. A path is the address of object. Name servers and naming contexts on name servers are considered directories. Managers and RT-Components are considered 'files'. As with the POSIX cat command, the path specified as an argument to commands is appended to the current rtshell working directory, which is stored in the RTCSH_CWD environment variable and changeable using the rtcwd command.

The available paths depend on the known name servers at the time the command is executed. This is a combination of the servers listed in the RTCSH_NAMESERVERS environment variable and the servers used in given paths.

For example, /localhost/comp0.rtc refers to the component named comp0.rtc registered on the name server at localhost. /localhost/manager/comp0.rtc refers to the component comp0.rtc in the directory manager on the localhost name server. ./comp0.rtc refers to that component in the current directory.

When specifying a port on an RT-Component, it should be placed after the path, separated by a colon. For example, /localhost/comp0.rtc:data refers to the port data on the component comp0.rtc.

Some commands that create new ports accept extra options in the paths, such as a name for the automatically generated port, or a formatter. The format for specifying these paths is:

path:port.name#formatter

For example:

/localhost/blurg.host_cxt/comp0.rtc:input.stuff#a_printer

This specifies that the automatically generated port should be named stuff, and the data type it handles should be printed using the a_printer function (which must be available, usually it is provided by the user in a loadable module). The port will be connected to the input port of the comp0.rtc component.

The name component is optional. If it is not present, neither should the . character be. For example:

/localhost/blurg.host_cxt/comp0.rtc:input#a_printer

The formatter component is optional. If it is not present, neither should the # character be. For example:

/localhost/blurg.host_cxt/comp0.rtc:input.stuff

Environment

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, making it available for browsing with rtshell. Optional.

RTSH_CWD

The current working directory in the tree. Do not set this variable; it is set automatically by rtshell.

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 rtshell should interact with. For example, in a Bash shell, the following command will set the known name serves to localhost, 192.168.0.1:65346 and example.com:

$ export RTCTREE_NAMESERVERS=localhost;192.168.0.1:65346;example.com

Diagnostics

Returns zero on success and non-zero on failure.

Verbose output and error messages are printed to stderr.

Bugs

The tools have been reported to not work well with the JAVA ORB.

See also

rtact (1), rtcat (1), rtcheck (1), rtcomp (1), rtcon (1), rtconf (1), rtcryo (1), rtcwd (1), rtdeact (1), rtdel (1), rtdis (1), rtexit (1), rtfind (1), rtinject (1), rtlog (1), rtls (1), rtmgr (1), rtprint (1), rtpwd (1), rtreset (1), rtresurrect (1), rtstart (1), rtstodot (1), rtstop (1), rtteardown (1)