Action Setup

Index

Table column headers

ID: The unique action IDDescription: This is a free text to describe the action more clearly.Type: The type abbreviation (see table below). The type is set in the tab Definition.

Double click

A double click will open the XmlScript Editor if the selected action is a XmlScript.

New

Add a new action to the list.
Changing the ID
The ID and description of an action can be changed by selecting the line in the list then writing the required text in the input fields. It is advisable to use self-explanatory IDs.

Copy

Copy the selected action. This is of help if defining similar actions of the same kind.

Delete

Delete the selected action.

Documentation

Opens the default WEB browser with all actions in a printable format.

Test

Unconditional test of the selected action.Not all variables are set as which is the case in automatic mode.

Definition

Type & ID

With these two fields the object that should perform the action is defined.
The Type can be selected from the drop-down list (see the table below).
The ID of an existing object in the Type category can be selected from the dropdown list, otherwise it is left empty.

For the type Locomotive and type Function the IDs of existing locomotives will be available for selection.

The ID field for type Locomotive and type Function can be left empty if the following objects are used to trigger the action:

Sensor 1)

Route

Switch

Schedule

In this case the Action Control of these objects will automatically handover the ID of the locomotive that triggers the action to the action itself.
This makes it possible to define actions for locomotives and locomotive functions that apply to any particular locomotive that at that moment is on that route/sensor1)/switch/schedule, without having to define a new action for each locomotive.
For example: The light can be switched on (function F0) when starting a particular route or a whistle can be sounded before entering a tunnel.
It is also possible to trigger such an action conditionally by using the action conditions.1) A sensor provides the locomotive ID only if it is assigned to a block.

Sub-ID

Command

The command to be performed by the object in the Type field is selected here. Only the commands that can be performed by the selected Type are available for selection (see table below)

Triple dot button (...)

Can be used to select the path to an external program or script for the type External. (See note on External below.)

Double quote

Optional if the Rocrail server runs under Windows to add a surrounding quotation:

""c:\programs\test\speak.exe" "Hello World""

Without this option the command would be like this:

"c:\programs\test\speak.exe" "Hello World"

Asynchroon

The external program, external script or XmlScript will be executed asynchrone to prevent blocking of the calling object.
In some cases it is desired to wait until the external process has been ended. (For example: WebCam)

Blanks in the program path are not supported.
If its not avoidable, use a batch file with quotes " for path/file.
Parameter take on in batch file with %1 %2 …
In case of an XmlScript the parameter field can be used to call just one function.

The 'lock' commands are for manually setting routes protected by locking it and all switches. (Software CTC)
The lockid is optional and must be used also for unlock if set. The action ID is used if left empty.
The set command does not color the route in the clients.

"on/off" is for switching the automode.
"resetfx" sets the selected function group 0…7 to OFF for all locos. (only ONE parameter allowed: 0 = f0-f4, 1 = f5-f8 …)
"time" in format 00:00 Only available with 60 second action timer.

go: tour, schedule, location or block ID (A variable can also be used instead of a fixed name.)
velocity¹: percentage of current set velocity¹
velocity2: speed of secondary decoder
carcount: number of cars or reset to 0
consist: locoID[,locoID]…
binstate: output number
x-go: comma separated list of loco addresses or ID's hard coded or with variables.
pomwrite: cv,value
Vvar: user automobile velocity

Leave the parameter field empty to reset a consist.
If no loco is found and the parameter field contains a #variable a loco will be searched by address. This option disable further parameters.
In case a destination is set at the GO action: Read this!

Function

fn

Locomotive
Car
Operator³

on, off, flip

function number (just the number, like 1, not f1 for function 1) or the function text (Description) (Case sensitive).
A function csv list like "1,2,3". If the list starts with a question mark, "?1,2,3", it will pick randomly one function. (Do not include the quots in the action definition.)

Only one active timed function is supported. Multiple will show unpredictable results. Flip will turn on the function when it was off and vice versa. Flip does noet support timed functions.

Sets the minimal occupation in this locality.
go and schedule will start random a loco.

parameter: minocc number or 0/1 for fifo de/activation

Weather

weather

Weather

setweather, weathertheme

Activates the selected weather(theme) ID.

At "setweather" the parameter may be used to set the sunrise,noon,sunset time in minutes. For example: "360,720,1080[,relative/absolute]" (06:00,12:00,18:00)

Light

light

-

flip, enable, disable

Enable a light from LightControl

Clock

clock

-

set

divider,hour,minute

The time can only be set if the divider > 1.

¹ When velocity or percent is negative the execution of the action will not only set the locomotive speed, but also change direction. Please note that only a negative value changes direction, it is not the case that negative means backwards and positive forwards.
² Hint: To debug not working external program calls; In the trace lines containing the executed command look like this OAction 0501 executing [espeak -vde eins]
³ Function commands are send to all wagons in the operator train.

Notes:

Type External:

If this type is used to execute an external program or script the path of the program (including parameters) or script is written in the command field. The path should exist on the server computer, so if you use the TrippleDot (…) button on another computer than the one the Rocrail server is running on it will probably not match.
Alternatively a program can be started in its own process running a Unix system. (myprog.sh &)
XMLScript files must be set without path, see XMLScript Path.

Playback

A record file, *.txt, can also be selected as external command to play back.
See: Command Recorder
Extra parameters are ignored.

XML Script

A XML script file, *.xml, can also be selected as external command to run.
See: XML Scripting
Extra parameters are ignored.

Explanation of the parameters:
“C:\sound\Aarau1_Irina.mp3” - the Sounddatei (here a “mp3”) which shall be played.
”–play-and-exit” - the program VLC is started, the sound played back and the program closed.
”–qt-start-minimized” - no display of a window.
”–qt-notification=0” - Windows plays back no other sound.

The action can be triggered by a block or a feedback.

Duration

The duration of the action in 100ms units; 10 = 1s. Time unlimited in case of zero.
Only used for function commands.

Timer

Number of ms to wait before executing this action after the action has been triggered.

This can be used, for example, to sound a whistle before a tunnel without having to install a separate sensor. The action can be triggered with the last (distant) sensor and be performed after the timed delay just before the tunnel.

An action control can be used to trigger several actions at the same time but are then performed with different time delays one after another.

Activation time

Use

If the action is to be triggered at a particular time Use should be checked and the required time should be entered.
The time refers to the Rocrail clock and not to the real time. There maybe situations in which it is useful to have the Rocrail clock run faster than the real clock, for example to implement a 24h day/night control.
If the Action timer 60 sec. option in the Rocrail server configuration is set, the seconds value is also evaluated.

Every

This action will be executed every hour + minutes after it has been enabled by an action control with state "on".
It can be disabled by an action control with state "off".
The Use must be checked to activate the every timer.
The Random option must be disabled.
The shortest execution interval is one minute.

Random

This action will be executed at a random interval.
The random activation time is relative between 1 minute and the activation time specified. The resolution is in scale minutes.
The Use must be checked to activate the random timer.
The Every option does not have any usage if Random is set.

Activated

Pre activation option; No event needed to be evaluated in case of activation time.

Usage

This tab lists all other objects, "ID (type)", using the selected action on the index tab.
A double click on an object in the list will open the Action Control dialog.

Interface

The address of the sound player device/port.
If the sound command is straight or turnout a switch command is generated.2)
If the sound command is play an action command is generated which is supported by: