What are Actions?
Actions are tasks that can be initiated automatically as a train, running in automatic mode, traverses the layout following a Transit. One or more Actions may be requested for each Section in a Transit. If a Section is in a Transit multiple times, different Actions may be specified for each occurrence of the Section. Actions only apply to trains run automatically under Dispatcher by a virtual engineer. If running trains in automatic mode is of interest read on. If your trains will only be run manually with a human engineer, Actions aren't used.
Actions are in addition to the standard actions that happen automatically when a train runs in automatic mode. Standard actions are things like following signals and using stop sensors, that are specified with each Section. Standard actions occur automatically whenever a Section is traversed in automatic mode. Other standard actions include automatically requesting allocation of Sections, and automatically changing locomotive speed according to signal restrictions.
Actions are tied to Sections, but are specified at the Transit level to provide maximum user flexibility. A Section is a piece of physical track, that may, for example, be used by passenger trains, through freight trains, or locals. Each of these uses may need different Actions in a specific Section. For example, a passenger train may make a station stop in a particular Section, whereas a through freight train may go straight through. Placing Actions in Transits allows Active Trains traveling the same path through the layout to have different Actions.
Requesting an Action
An Action is requested by specifying what
action to be performed and when that action is
to be performed. Any when event may be combined
with any what action, providing a wide variety
of Special Actions. An Action is initiated when the train
enters the Section with the Action request. To decide when to
perform the Action after the Section is entered, the program
looks at the when event.
Currently available when events are:
- On Section Entry - When the automatic train enters the current Section.
- On Section Exit - When the automatic train exits the current Section. This means when the last detectable car leaves the Section, and the Section is unoccupied.
- On Block Entry - When the automatic train enters a specified Block in the Section. For Sections with only one Block, this is equivalent to On Section Entry.
- On Block Exit - When the automatic train exits a specified Block in the Section. This means when the last detectable car leaves the specified Block, and the Block is unoccupied. For Sections with only one Block, this is equivalent to On Section Exit.
- On Train Stop - When the automatic train stops. This may be used, for example, for stopping the bell in a sound decoder or initiating other actions when the train stops at a station.
- On Train Start - When the automatic trains starts up after having been stopped. This may be used, for example, to initiate actions when a train starts up after a station stop.
- On Sensor ACTiVE - When the specified Sensor moves to the active state. The specified Sensor may be either internal or hardware, and must be in the Sensor Table. This might be used, for example, with a hardware Sensor connected to a fascia push button to trigger an action. It could also be used to trigger actions using hardware position sensors on the layout. With internal sensors it can provide a link to Logix.
- On Sensor INACTIVE - When the specified Sensor moves to the inactive state. This is the same as above, but with the opposite sensor state. Use the one that best fits your hardware or Logix.
An optional delay, specified in milliseconds, is available for each when event. No delay is the default. If an optional delay time is not entered (or a delay time of zero is entered), the action will be performed immediately after the when event occurs. If a delay time is specified, the program will wait for the specified time after the when event occurs before performing the action.
Currently available what actions are:
- Pause Train - Stop the train for a specified number of fast clock minutes. This item may be used to request a station stop.
- Set Maximum Speed - Set the maximum speed to a specified percentage of the maximum hardware speed. When a train is run in automatic mode, the program will never exceed the maximum speed. For example, this item may be used to force an automatic train to run slower through a town. Setting maximum speed does not affect the current speed of the train if it is less than the specified maximum speed.
- Set Train Speed - Set the current train speed to the target percentage. The throttle will send the new speed to the locomotive immediately. How long it takes the train to reach the new speed after that depends upon the locomotive decoder. The new speed may be either lower or higher than the previous value, but will not be allowed to exceed the maximum speed.
- Ramp Train Speed - Set the current train speed to the target percentage by ramping to the target value using the default ramp rate of the automatically running train. If the default ramp rate of the train is RAMP_NONE, this action is equivalent to Set Train Speed. The new speed may be either lower or higher than the previous value, but will not be allowed to exceed the maximum speed.
- Go to Manual Mode - Drop out of automatic mode to allow a human engineer to perform work with a manual throttle. This action supports the scenario where a train might be run automatically to a work site, where a human operator takes over to perform work, after which automatic running is continued. The train will remain in manual mode until directed by the dispatcher to resume automatic operation. An optional Done Sensor allows an operator remote from the dispatcher to notify the dispatcher that work has been completed and automatic running can be resumed. When the Done Sensor goes active, the status of the train is changed from WORKING to READY. For more information on this action, see Dispatcher. Note: When the train is in manual mode, the computer does not have a throttle for the train available, so delayed actions that happen then and require a throttle are ignored.
- Set Locomotive Light - Sets the locomotive light either On or Off as selected.
- Start Bell - Start bell ringing on a sound decoder. This item will turn throttle function 1 on.
- Stop Bell - Stop bell ringing on a sound decoder. This item will turn throttle function 1 off.
- Sound Horn - Sound the horn (whistle) of a sound decoder for a specified time. This item is equivalent to holding down throttle function 2 for the specified time.
- Pattern Sound Horn - Sound the horn (whistle) in a manner specified by a user-entered pattern. The pattern consists of short and long blasts, specified as "s" and "l" in the pattern. For example a pattern of "lsl" specifies long-short-long. The user sets the duration of the short and long blasts. The short blast duration is used as the wait time between blasts. Actual times realized will depend on the sound decoder and how busy the computer is. The horn/whistle is assumed to be throttle function 2.
- Set Decoder Function - Sets the specified decoder function either On or Off as selected. This works for both sound decoders and decoders without sound.
- Set Sensor ACTIVE - Set a specified Sensor active. The specified Sensor must be in the Sensor Table. If the specified Sensor is already in the active state, it is first toggled to the inactive state, then set active. This action may be used, for example, with an internal sensor to trigger a Logix, set a Route, or to set a Light. It offers access to a wide variety of actions not included here, such as running scripts or playing sounds.
- Set Sensor INACTIVE - Set a specified Sensor inactive. The specified Sensor must be in the Sensor Table. If the specified Sensor is already in the inactive state, it is first toggled to the active state, then set inactive. This is equivalent to the action above, except with a different target Sensor state.
- Hold Signal - Set a specified SignalHead or SignalMast to HELD. The specified SignalHead or SignalMast must already exist in JMRI.
- Release Signal - Set a specified SignalHead or SignalMast to NOT HELD. The specified SignalHead or SignalMast must already exist in JMRI.
The View Actions Window
The View Actions window displays Actions that are currently set, and provides for adding, editing, or deleting Actions. The View Actions window (example below) is displayed for a specific Section in a Transit by pressing the View/Add/Edit Actions button on that Section's row in the Add/Edit Transit window.
For all Actions that have been created, the when event and the what action are described in the When and Action Requested columns. To add a new Action, click Add New Action to bring up the Add/Edit Action window. To edit an existing Action, click the Edit button in its row. To delete an existing Action, click the Delete button in its row. The order of the Actions is not important.
When the Actions are completely defined, click the Done button.