User Tools

Site Tools


actions-en

Differences

This shows you the differences between two versions of the page.


Previous revision
actions-en [2024/01/20 17:34] (current) – [Notes:] rjversluis
Line 1: Line 1:
 +====== Action Setup ======
 +[[:english#objects|{{  :objects.png}}]][[:english|{{  :rocrail-logo-35.png}}]]
 +
 +[[:english|Content]] -> [[:english#objects|Objects]] ->   [[timed-actions-en|Actions]]
 +  * **Action Setup** | [[:actionctrl-en|Action Control]] | [[:actionctrl-en#system-actions|System Actions]] | [[:actioncond-en|Action Condition]] | [[:xmlscripting-en|XML Scripting]] | [[action-example-en|Example]]
 +
 + \\
 +
 +=====Index=====
 +{{:actions:actions-index-en.png}}
 +====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 __**[[:xmlscripting-en#edit_on_the_server|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=====
 +{{:actions:action-def-en.png}}
 +
 +==== 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 **<sup>1)</sup>**
 +  * 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/sensor**<sup>1)</sup>**/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.
 +
 +**<sup>1)</sup>** A sensor provides the locomotive ID only if it is assigned to a block with and also __**[[block-routes-en#sensor_without_event|without event]]**__.
 +\\
 +
 +==== Sub-ID ====
 +Only for use with __**[[:variable-en#action_sub-id|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:
 +<code>
 +""c:\programs\test\speak.exe" "Hello World""
 +</code>
 +Without this option the command would be like this: 
 +<code>
 +"c:\programs\test\speak.exe" "Hello World"
 +</code>
 +
 +===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: [[:text:text-webcam-server-en|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, active((The output active state is only virtual and can not be visualised with real I/O.)), 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, **[[#playback|record]]** or **[[#playback|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 __**[[:xmlscripting-en|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 **[[:rocrailini-automode-en#action_timer_60_sec|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: __**[[:automatic-en#running_to_a_defined_destination|Read this!]]**__ |
 +| Function   | fn | Locomotive\\ Car\\ Operator³ | on, off, flip | //function number (just the number, like 1, not f1 for function 1) or the __**[[loc-fun-en#description|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, __**[[variable-en#status_and_parameter_syntax|values]]**__, on, off | Dynamic text variables will be replaced with real values. Available built-in variables see here:  __**[[[:text-en#variables|Variables]]**__ | Variables: __**[[:variable-en#status_and_parameter_syntax|Syntax]]**__ |
 +| Sound | sound | - | play, straigh, turnout | Sound file name. | Set the sound player device in the interface tab. \\ (RocNet only!) |
 +| [[:variable-en|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 __**[[:rocrailini-gen-en#xmlscript_path|XMLScript Path]]**__.\\
 +
 +==Playback==
 +A record file, *.txt, can also be selected as external command to play back.\\
 +See: **[[rocview:cmdrecorder-en|Command Recorder]]**\\
 +Extra parameters are ignored.\\
 +
 +==XMLScript==
 +A XMLScript file, *.xml, can also be selected as external command to run.\\
 +See: **[[xmlscripting-en|XMLScripting]]**\\
 +Extra parameters are ignored.\\
 +
 +==VLC==
 +**Example: Sound playback with VLC**
 +
 +Install **[[https://www.videolan.org/vlc/|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 **[[:rocrailini-automode-en#action_timer_60_sec|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.\\
 +{{:actions:action-use-en.png}}\\
 +A double click on an object in the list will open the **[[:actionctrl-en|Action Control]]** dialog.\\
 +
 +\\
 +
 +=====Interface=====
 +The address of the sound player device/port.\\
 +{{:actions:action-int-en.png}}\\
 +If the sound command is straight or turnout a switch command is generated.((The given sound file name is ignored.))\\
 +If the sound command is play an action command is generated which is supported by:
 +  * RocNet
 +  * RocNetNode
 +  * Virtual
 +
 + \\
 +=====Report=====
 +{{:actions:actions-overview-en.png?800}}\\
 +A double click will open the selected object.\\
 +====Generate====
 +Generates a report of all used actions in all objects.\\