Synopsis

rtstart [options] [RTSProfile file]

Description

Start an RT-System, activating all involved components, using an RTSProfile. Components are activated in the order specified in the RTSProfile. Any components not marked as required in the RTSProfile will be ignored if they are not running.

If no file is given, the RTSProfile is read from standard input.

XML format is used by default; to use RTSProfiles specified in YAML, specify --yaml.

Options

--dry-run	Print what will be done but don't actually do anything.
-x, --xml	Use XML input format.
-y, --yaml	Use YAML input format.

--version	Show program's version number and exit
-h, --help	Show a help message and exit
-v, --verbose	Output verbose information. [Default: False]

Start plans

The RTSProfile describing an RT-System can also specify the ordering of starting and stopping components of that system. It is possible to change the order in which components are started and stopped and specify dependencies between components, for example to ensure one component will not start before another that it requires has started.

rtstart(1) and rtstop(1) use this information when they start and stop systems. rtstart uses the information contained in an Activation block. rtstop uses the information contained in a Deactivation block. When executed, they will build and execute a plan for changing the state of the entire system. They will not exit until the plan completes or an error occurs.

When displayed using the --dry-run or --verbose options, the plan looks similar to that shown below:

{1} Activate /localhost/ConfigSample0.rtc in execution context 0
(Required)
{2} [Order 1] Activate /localhost/Motor0.rtc in execution context 0
(Required)
{4} [Order 3/Wait 5000ms] Activate /localhost/Controller0.rtc in
execution context 0 (Required)
{3} [Order 2/Sync to Motor0, Order 5/Sync to Controller0] Activate
/localhost/Sensor0.rtc in execution context 0 (Required)
{5} [Order 4/After ConfigSample0's action] Activate
/localhost/ConsoleIn0.rtc in execution context 0 (Required)

The number in braces at the beginning of each line is the action ID. These are also displayed during execution and allow easy identification of individual actions.

Following this there may be a value in square brackets. This indicates any pre-conditions on the action being executed:

Order

pre-conditions are simple sequencing. When no other conditions are present, actions will be executed in order of their sequence number.

Wait

pre-conditions indicate that the specified time must pass before the action will be executed.

Sync

pre-conditions prevent the action executing until the specified component has reached the target state. A timeout can be set on this occurring, to account for errors.

After

pre-conditions are similar to Sync pre-conditions. The difference is that they wait for the specified action to be performed on the other component first; in other words, the action will be executed after the other component's action, but before confirmation that it has reached the target state.

The remainder of the line is a description of the action to perform.

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.

Examples

$ rtstart sys.rtsys

Start the RT-System specified in the file sys.rtsys.

$ rtstart sys.rtsys --dry-run

Display the actions that will be performed to start the system.

See Also

rtcheck (1), rtresurrect (1), rtstop (1)