Table of Contents
Action Setup
Index
Table column headers
ID: The unique action ID
Description: This is a free text to describe the action more clearly. In case of no description this column will be used to Command::Parameter.
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 with and also without event.
Sub-ID
Only for use with Variables.
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)
Parameter
Some commands require an additional parameter (see table below).
Types, Commands & Parameters
| Type | Type abbr. | ID | Commands | Parameter | Description |
|---|---|---|---|---|---|
| Output | co | Output | on, off, flip, active1), value, lock, unlock | 0…65535 lockid (unlockid) | The value command is only supported in the SRCP and BiDiB library. |
| AccGroup | accgroup | AccGroup | on, off, flip | ||
| Sensor | fb | Sensor | on, off, flip, reset, setcounterval | New counter value; Relative if prefixed with a sign. The calculated counter value is reset to zero if its negative. | The sensor can be turned on, off or flipped. On reset the counter of the sensor will be set to 0. |
| External | ext | - | A script, program, record or XML Script name. | parameters given here will be appended to the program call² | 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. |
| Switch | sw | Switch | straight, turnout, left, right, flip, flipstatic, setstatic, resetstatic, lock, unlock | force lockid (unlockid) | |
| Route | st | Route | set, lockset, lock, unlock, open, closed, class | lockid (unlockid) | 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. |
| System | sys | - | stoplocs, stop, go, shutdown, resume, on, off, ebreak, resetfx, time, v0locos, initfield, vrestorelocos, vcurrentlocos | - | "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. |
| Signal | sg | Signal | red, yellow, green, white, aspect | Aspect number in the range of 0…31. | |
| Block | bk | Block | schedule, schedule_manual, tour, unlock, white, yellow, green, red, setloco, event, open, closed, acceptident, dispatch, go, reserve, class | schedule/tour ID, loco ID, sensor ID unlock loco ID or * schedule_manual: Start in half automatic mode | The color commands will set the main forward signal defined for this block. |
| Staging block | sb | Staging block | unlock, white, yellow, green, red, open, closed, exitopen, exitclosed, compress | unlock ID | The color commands will set the exit signal defined for this block. open/closed are for enter side. |
| Locomotive | lc | Locomotive | go, govirtual, stop, velocity, velocity2, percent dispatch, swap, blockside, carcount, min, mid, cruise, max, consist, assigntrain, releasetrain, binstate_on, binstate_off, class, x-go, pomwrite, Vvar, shuntingon, shuntingoff | go, govirtual: 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.) Prefix the list with a '!' to activate Shift.(Can not be used in combination with '?'.) | 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. |
| Turntable | tt | Turntable | 0…47, 180, on, off, lighton, lightoff | track number (0…47) or function (on/off) | |
| Fiddle Yard | seltab | Fiddle Yard | goto | track number | |
| Text | tx | Text | update, values, on, off | Dynamic text variables will be replaced with real values. Available built-in variables see here: Variables | Variables: Syntax |
| Sound | sound | - | play, straigh, turnout | Sound file name. | Set the sound player device in the interface tab. (RocNet only!) |
| Variable | var | Variable | text, value, add, subtract, min, max, random, start, stop | The new value. | - |
| Car | car | Car | empty, loaded, maintenance | The new car status. | - |
| Operator | operator | Operator | addcar, removecar, loadcar, emptycar, class | Adding, removing, loading or emptying cars. | A comma separated list of car IDs. |
| Locality | location | Locality | minocc, fifo, go, schedule, scheduletable | 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.
XMLScript
A XMLScript file, *.xml, can also be selected as external command to run.
See: XMLScripting
Extra parameters are ignored.
VLC
Example: Sound playback with VLC
Install VLC.
Define an action:
Type: “run ext. program”
Leave default “Double quote” and “Asynchrone” unchanged.
Command: “C:\Program Files (x86)\VideoLAN\VLC\vlc.exe” or the path where VLC is installed.
Parameter: “C:\sound\Aarau1_Irina.mp3 --play-and-exit --qt-start-minimized --qt-notification=0”.
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.
Further parameters:
--gain=x.xxx - playback volume, where x.xxx can be in the range 0.0 to 8.0.
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:
- RocNet
- RocNetNode
- Virtual
Report
A double click will open the selected object.
Generate
Generates a report of all used actions in all objects.