JMRI: Dispatcher - Activate New Train Help
Author: Dave Duchamp
Keywords: JMRI help Dispatcher New Train

# JMRI Dispatcher: Activate New Train

## Introduction

The Activate New Train window supports the creation of a new Active Train. To create an Active Train, the dispatcher uses this window to assign a Transit, assign a train, and specify a starting Block (Train location at start) and an end Block (Train location when transit of the layout is complete). Options for the new Active Train are also set using this window.

Transits are selected from the Transits defined in the Transit Table. Dispatcher will list all Transits that are not currently in Active Trains.

Trains, that is the Lead locomotive, may come from any one of three sources:

- Trains from Roster - Dispatcher will list all trains in the JMRI Roster that are not currently in Active Trains. The default TrainName will the Roster Entry's Title and maybe edited by the User.
- Trains from Trains - Dispatcher will list all trains available from Operations that are not already in any Dispatcher Active Trains. The TrainName and DCC address of the locomotive may be edited by the User.
- Trains from User Entry - Dispatcher will replace the train selection box in the Activate New Train window with two entry fields allowing the user to enter a Train name and a loco Address.

A fourth option, Set Later is used when setting up and saving routing and control information that will be saved for later use.

Dispatcher's train default source is set by selecting one of the above in the Options window accessed from Dispatcher's Options menu.

Active Trains must start from a Block in the selected Transit, or from a Block connected to a Block in the selected Transit. Active Trains must stop in a Block within the selected Transit. Transits have a direction, so for a starting Block outside the Transit to be a valid starting Block, entry to the Transit from the starting Block must result in travel in the Transit's defined direction. This window only allows selection of valid starting and stopping Blocks. Initially the first occupied block is selected for you in the combo box.
Note: If an expected Block is not in the starting Block selection box, it may be because of this requirement.

## Saving and Retrieving Active Train Information

since 2.5.2

To facilitate easy set up of Active Trains that are used more than once, Dispatcher provides for saving and loading train information from disk.

To save your train information to disk, click the Save Train Info... button after all selections and options have been set up but before clicking the Create button. This will bring up a small window allowing you to name the saved train information file. The name you enter will be normalized automatically with any non-alphanumeric characters replaced, and a .xml suffix added if needed. Train information files are saved as .xml files in the dispatcher folder in the user's preferences area on disk.

To load previously saved train information, click the Load Train Info... button immediately after the Activate New Train window is displayed. This will bring up a small window allowing you to select the train information file to load from all the train information files in the dispatcher folder. When a train information file is loaded all items in the Activate New Train window are set according to the saved train information if possible. If an item cannot be set, for example if the specified Transit is in use, a warning is displayed and a default selection is made. After loading, you may change any option or selection and again save your new train information, before clicking the Create button.

Use Save As Defaults to have the form load as it is set now when creating a new train.

If the transit assigned to a train info file is changed, such as adding or removing sections, the train info file will need to be updated. This can done by loading and then saving the affected train info file.

To permanently remove an unneeded Train Info file from the dispatcher folder in your user preferences area, click the Delete... button, then select the train information file to be deleted.

## Using the Activate New Train Window

To create a new Active Train, use the following procedure:

A train name in the Train: field. Any short name that identifies the train may be used, provided the name is not being used by another Active Train.

The DCC Address must be a number in the range 1 - 9999.
Note: If the train will not be run automatically, the dcc address need not be accurate. This window is displayed if Trains from User Entry is selected as Dispatcher's train source.

1. Click the New Train... button in the Dispatcher window, or the Create New Train menu item from the dispatcher menu in a Layout Editor Panel, to bring up the window shown below.

2. If you want to use saved Train information, click Load Train Info... See above for more on loading Train information.

3. If you are not using the default Trains From source, select the desired source.

   For Roster, shown above, you need to select the Roster Entry, which will become the default Train Name that can then be edited.

   For Operations you need to select the Train, enter the train name and edit or enter the DCC address.

   For User Entry you need to enter the train name and DCC Address.

   For Set Later you need to enter the train name.

4. Select a Transit type.

   Predefined

     Predefined transits are the standard transits built from predefined Sections. These support all of the features including transit section actions.

     1. Select a Transit from the Transit selection box. The selected Transit specifies the route the Active Train will follow while running on the layout. Transits are displayed and new Transits are created using the Transit Table accessed from the Tables submenu of the JMRI Tools menu. This Transit selection box will allow selection of any Transit in the Transit Table that is not in use by an Active Train.

     2. If the starting location of the Active Train is a Block within the selected Transit, check the Train in selected Transit box. If the starting location of the Active Train is outside the selected Transit, (in a Block connected to a Block within the selected Transit) uncheck this box. Checking and unchecking this box results in different selections in the Starting Location of Train: select box.

     3. Select a Starting Location of Train: from the select box. This select box lists all Blocks consistent with the check box above and the selected Transit. To identify each Block uniquely, the Block identifier consists of the Block display name followed by the sequence number of a Section in the Transit definition. If the train is located in the Transit, this sequence number identifies the Section where the train is located. If the train is located in a connected Block, the sequence number identifies the Section that will be entered when the train enters the Transit. If the train spans two blocks, select the Block where the engine is located.

     4. Select a Destination Location of Train: from the select box. This select box lists all Blocks consistent with the selected Transit that can be reached from the selected starting location by travel in the direction of the Transit. The Block identifier in the select box consists of the Block display name. If a Section is in the Transit more than once, the sequence number of the destination Section is appended to the Block identifier to identify the destination Block uniquely.

   Ad Hocsince 5.11.2

     An Ad Hoc transit is created dynamically between 2 blocks. These are always run using "No Signals". Ad hoc transits are removed at train termination. If they are not removed for any reason they will not be stored. Currently the route must be clear from end to end and any flaws in the routing table will cause grief. Avoid having the train stop in them.

     1. The Starting Location of Train: contains a list of occupied blocks. Select one of the blocks to become the starting block.

     2. The Via list contains the neighbor blocks for the starting block. The direction of the transit depends on which neighbor is selected.

     3. The Destination Location of Train: list contains the potential destinations that can be reached based on the starting and via selections. Pick one as the destination.

     The temporary transits and sections are added to the transit and sections tables The user names start with #. It is possible to save the configuration as a train info file.

5. Train Detection Options since 5.7.5

   This settings effects the ability of auto trains to stop. See autotrains for details

   - Entire Train The entire train can be detected, no unoccupied blocks between head and tail of the train. Sections and blocks within sections can be reused a soon as they become unoccupied.
   - Head and Tail The head and tail are both detected but parts in between may not be detected. Sections will only be reused after the tail has passed.
   - Head Only Only the head of the train can be detected. The same as Head and Tail with the addition that section or any part of the section may not be reused if occupied.

   See also Train Length for more AutoTrain stopping information.

6. Allocation Options since 4.9.5
   - As Far As Pos (Allocate As Far As Possible) - Select to allow Dispatcher, when using Auto Allocation, to allocate as far ahead of the Train as allowed by other circumstances such as an occupied Block. Allocation is of course also limited by the Destination Location of Train selection.
   - To Safe Secs (Allocate to Safe Sections) - Choose this option if you have different trains going through a single Block in both directions.
     Define Transits and mark as Safe the Sections that form passing places for opposing traffic. If there are Alternative Sections in the Transit, mark those as Safe as well.
     Note: If you notice that, upon assignment, Turnouts are being set that were already set, you need to select "Trust Known State of Turnouts" in the Dispatcher Options.
   - Number of Sections - When using Auto Allocation, Dispatcher will allocate ahead of the current location of the Train no more than the entered number of Sections set in the Spinner.
     Because a value of 1 in the current version is known to cause unexpected results, be advised to set it to 2 or higher.

7. Check Reset when Done to set up the Active Train for continuous running. When checked, the train will restart based on the "Add Delay" value. When an Active Train has completed running through its Transit, it is immediately reset to run around its Transit again. Continuous running requires that the selected Transit be set up in a certain way--the first Section and the last Section must be the same. If the selected Transit is not capable of continuous running, the user is warned and Reset when Done remains unchecked.
   For more information on setting up a Transit for continuous running see the Transit Table help file.

8. Check Reverse at End to set up the Active Train for back and forth running. With Reverse at End selected, when an Active Train is has reached the end of its Transit, the Transit direction is reversed, and the Train backs up through the Transit to its starting point. For back and forth running, the Transit should have at least three Sections, one at each end and at least one in the middle, and the Active Train should fit into each of the end Sections. Continuous back and forth running is accomplished by also checking Reset when Done.

9. Enter a Priority for the Active Train relative to other Active Trains. Larger numbers are higher priority. The priority is used by the dispatcher and/or automated dispatching functions to arbitrate between Active Trains if multiple Active Trains are requesting the same resources.

10. Select a Train Type from the Train Type: popup menu. The selected train type is displayed in the Dispatcher window to aid in allocation decisions.

11. If the train is to start at a specified Fast Clock time, check the Delayed Start box, and enter the desired start time in the hour and minute fields of the Departure Time: entry. If the fast clock has not reached the specified Departure Time of an Active Train, the scheduled departure time is displayed in that Active Train's entry of the Active Train table in the Dispatcher window. If an Active Train is waiting for the fast clock, Dispatcher will refuse to allocate Sections to it, however, the dispatcher is given a chance to override this restriction. If an Active Train is being run automatically by the computer (see below), the Active Train will automatically start at the specified fast clock time. This option allows the dispatcher to set up a number of Active Trains which will start at various times during a session.

12. Check Load this Train at Startup to have Dispatcher automatically load this Train when Dispatcher starts. You must Save Train Info... for this flag to take effect on the next start.

13. Check Run Train Automatically to request that the Active Train be run automatically by the computer. If the Active Train is to be run manually by a human engineer, skip the next few steps; go directly to the third to last item of these instructions. Requesting Run Train Automatically will extend this window (see below) to display options that are only related to automatic running of trains.

    Note: Requirements for automatic running are not validated until creation of an Active Train is requested.
    More information about automatic running of Active Trains may be found in the Running Trains Automatically help page.

14. Train Detection above effects train stopping. If Entire Train is selected, which usually means that all cars in the train will have resistance wheels, trains can be stopped without using point sensors (Stopping Sensors in Sections) or without using stopping by Speed Profile. If an automatically running Active Train needs to stop in a Section, it will use a Stopping Sensor if one is present or the Speed Profile. If neither is configured, and if Entire Train is selected and the train will fit in the Section (see below), the train will stop when the previous Section becomes UNOCCUPIED. If Head and Tail, Head Only is specified or if the train will not fit, the train is stopped when it enters the Section.

15. In the Loco Speed Correction: field, enter a percentage (10 - 200%) to modify all train speed settings. If the locomotive runs normally, enter 100%. If the locomotive runs slower than normal, enter a factor between 100 and 200%. If the locomotive runs faster than normal, enter a factor less than 100%. This factor is designed to allow the user to compensate for differences between locomotives.
    The Correction factor is applied to all speed/throttle settings before they are adjusted for the Minimum Throttle and Maximum Throttle.
    The default is 100.

16. In the Maximum Throttle: field, enter a number (10 - 100%) to limit the maximum throttle for the Active Train. This does not scale the throttle setting across the entire range, it only limits the maximum value. To scale the throttle setting though the entire range use Loco Speed Correction.
    The Maximum Throttle entered here is the starting value for the Maximum Throttle it can be adjusted during a transit. see Actions in the Transit. Actions This can be used, for example, to slow an automatically running Active Train when it passes through a town on the layout.
    This must be at least 10 greater than the Minimum Throttle setting.
    If a Roster entry is used the default is the Maximum set there, else the Maximum is 100.

17. In the Minimum Throttle: field, enter a number (0 - 90%) to set the Minimum Throttle setting to be used by the Active Train. When starting from zero the first throttle setting applied will be at least this. When stopping the train using Ramping or a Speed Profile the last step before Zero will at least this value. Use this to deal with locos that have settings below this value that though they may work they do not work reliably.
    This must be at least 10 less than the Maximum Throttle setting.
    The default is zero.

18. Select a Ramp Rate. When a train running automatically needs to change speed, the computer can send the new speed to the locomotive immediately (RAMP_NONE), or it can Ramp the speed to its new value (change the speed gradually) bringing the train to the new speed over a period of time. The Ramp Rate to use depends upon the decoder in the locomotive and how the decoder is set up. Some decoders have features that can change speed gradually (this decoder option is named differently for different decoders). If the decoder is doing the desired job, select RAMP_NONE. If the loco is speed profiled then you may select Speed Profile which will cause speed changes to take place over the length of the section or block.
    Otherwise select one of the ramp rates offered.

19. Use Speed Profile - If a locomotive has a Speed Profile, the speed will be set using the Warrant Preferences settings and the speed profile. So if the speed calls for "restricted", it looks that up in the Warrant Preferences, gets the required speed & units and uses the Profile to set the Throttle percentage.

20. Stop By Speed Profile The loco will begin to stop when it enters the Section and -if the profile is accurate and the block lengths are accurate- stop at the far end.

21. Adjust Set the percentage of the final Block length to be used for stopping when stopping By Speed Profiles is set. Small values in small Blocks tend to cause the loco to just stop.

22. Check Loco has sound decoder. if the locomotive has a sound decoder. If this item is not checked, Actions that require a sound decoder, such as ringing the bell or sounding the horn will be skipped.

23. Check Run in reverse if the locomotive is to be run in reverse through the Transit. This should not be confused with the direction through the Transit, which is always FORWARD when the Active Train starts up. Checking this item is equivalent to using the reverse setting on a manual throttle.
    This option allows a locomotive to back up through the Transit. For example, a local moves out of a yard automatically in the forward direction to a siding, cars are switched manually, then the locomotive needs to back up automatically to the yard. This could be accomplished using two Active Trains, both running automatically. One would move the train from the yard to the siding with the locomotive moving forward, and the second one, using a different, but similar Transit would back from the siding to the yard, with the Active Train in reverse. This should also cover the situation where forward and reverse are backwards in the locomotive.

24. Maximum Train Length. Enter the maximum length the train can have while traversing the Transit. The length can be entered in Actual (measured with a ruler on the layout), inches or centimeters, or, scale (measured in real life), feet or meters.
    The default scale units as set in the Dispatcher Options accessed from Dispatcher's Options menu. The converse value is calculated and displayed to the right. You do not have to update the value if the layout scale or the base layout measurements are changed to or from metric.
    It is important to enter a reasonable value for the maximum length as it used during stopping or releasing sections HEADONLY. When stopping but NOT stopping by Speed Profile or Stopping Sensor, if the length of the train does not fit in a Block it is stopped immediately. Eise it is stopped as soon as the preceding Block goes UNOCCUPIED. Remember this uses debounce timings, which -if large- can result in the train over running the block if it only just fits.
    See also Train Detection

25. If you want to save your entered train information for later use, click Save Train Info... See above for more information on saving train information.

26. Click Create after all the above have been set to create and activate the new Active Train. The new Active Train will immediately appear in the Dispatcher window, and this window will be dismissed.

    - OR -

27. Click Cancel to exit this window without creating a new Active Train.

Back to Dispatcher help.