WarrantsA Warrant is a collection of information sufficient to run an automated train. It will set the turnouts for a specified route and drive the train over the route. When running, using block occupancy detection and signal configuration, it will make a best effort to control speed according to signal aspects and occupancy and other track conditions ahead. A JMRI Warrant is suggestive of what a warrant does on a prototype railroad, but there is no intention to replicate any particular railroad's mode of operation. It is simply the idea of giving an automated train trackage rights to move from point A to point B.
Warrants depend on having an accurate description of the layout in terms of OBlocks, Portals and OPaths. These elements are created by entering data into the Occupancy Block Tables or by using the graphical interface of the Circuit Builder. Initially neither of these subsystems are visible in Control Panel editor.
It is important that the scale of your layout is known so that the warrant can compute the distances required when encountering signals. Go the Warrants panel of Preferences to set the layout scale. There are other parameters related to warrants there, that you may wish to change later, but the defaults are generally sufficient without change. See Warrant Preferences for information about configuration.
How To Get Started
- Definitions of OBlocks, Portals and OPaths are found at The Occupancy Block Tables.
- Opening the Occupancy Block Tables is done by either the Tools->Tables->Occupancy Blocks menu item from the menus in the main PanelPro window, or by the Add Items->Occupancy Blocks menu item from the menus of Control Panel Editor. How to create OBlock, Portals and OPaths is described in Creating and Editing OBlocks, Portals and OPaths.
- OBlocks, Portals and Paths can be created using the Circuit Builder tool found in the Control Panel Editor. Initially, the Circuit Builder can be opened using the Open Circuit Builder menu item under the Warrants menu. Instructions for use are found in The Circuit Builder.
What is Circuit BuilderCircuit Builder is an interactive tool that creates OBlocks, Portals and Paths graphically. It is necessary to have a track diagram of your layout expressed with track icons (track segments and turnout icons) in a Control Panel Editor panel. OBlocks are created by clicking on the track icons. The Circuit Builder can convert the track segments and turnout icons of your layout into Indicator Track and Indicator Turnout icons. These icons display the status of the OBlock they represent by color, i.e. whether the track circuit of the OBlock is occupied or unoccupied, whether a warrant has allocated it or whether a train under warrant currently is proceeding over the circuit. Details are found at The Circuit Builder,
Compatibility With Layout EditorOBlocks, Portals and Paths can be used with Layout Editor. Compatibility is achieved by using the same occupancy detection sensors for LayoutBlocks as for OBlocks. If there is no corresponding Control Panel layout diagram, Circuit Builder cannot be used. The Occupancy Block Tables will have to be used to define the OBlocks, Portals and Paths.
More About Getting StartedIn order to create a Warrant you must first have created two or more OBlocks. These blocks don't have to be fully defined, but their existence indicates that you are interested in using Warrants, that is, you have a block to start a train and a block to stop it. When two or more OBlocks exist Control Panel Editor will change the items under the Warrants menu to be the following menu items. The Warrant menu items are:
- Warrant List: - Opens a table of warrants from which you can control warrant routes and dispatch trains. See The Warrants List.
- Edit Warrant...: - Shows the list of existing warrants. Selecting one will open a Warrant Editing Window. The operations of this frame are discussed in Creating and Editing Warrants.
- Create New Warrant: - After providing system and user names this opens a blank Warrant Editing Window to create a new warrant. The operations of this frame are discussed in Creating and Editing Warrants.
- Train Trackers: - Opens window where the identity of trains can be displayed as they move from one occupancy block to another.
- Create NXWarrant - Opens a window to create an eNtry/eXit warrant. this is discussed in About NXWarrants.
- Open Session Log - Opens a window to name a file that records the warrant and train tracking status messages.
Warrants without Occupancy DetectionIt is possible to create and run warrants without block detection. OBlocks can be defined and they do not necessarily have to have detection sensors. Such blocks are called "Dark Blocks". Dark blocks, Portals and the paths within the block can be defined for a layout diagram. A Warrant can be recorded and be able to be played back, including having its route set. However, be advised for such trains there is no protection for having it collide with other trains or throwing switches under other trains. It will proceed only according to the elapsed times and throttle settings that were recorded.
The Importance of Block Path LengthsA Warrant detects a position of its train when it enters a block having occupancy detection. All other positional information must be calculated. For this, the speed of the train and the length of the path it is on must be known. Please see Parameters Needed for Ramping below if you intend to use NXWarrants and employ gradual changes of speed.
Creating a WarrantThere are three types of warrants;
- A recorded script Warrant, where throttle commands are recorded from a throttle you use to drive a train over preselected route. The warrant then replicates all the commands when played back. To create a recorded script warrant, select the menu item Create New Warrant from the Warrants menu.
- An NXwarrant, that is, an eNtry/eXit warrant. These warrants are created by selecting a start position and an end position and having the warrant generate the commands to drive the train from start to end. To create an NXwarrant select the menu item Create NXWarrant from the Warrants menu.
In either case, first a route must be chosen on which to run the train. The Creating Routes section below describes how this is done.
Elements of a WarrantA warrant consists of two parts; The route over which a train will run and the commands it will receive when running over the route. For a Warrant, you drive the train over the route you selected and the commands you used are recorded for playback later. For an NXWarrant, commands are generated automatically for the route you have selected.
Creating RoutesA warrant route is a series of block paths linked together so a train may travel over it. A warrant route is created by first choosing an origin block, a starting path and a portal to exit the originating block. Then, a destination block is chosen and a path on which to end the route. Optionally, you may also chose a Via block, that is, a block that route must include and a Avoid block, that is, a block the the route must not include. Blocks are chosen by typing in the block name or dragging it from a displayed OBlock table. Blocks can also be chosen by clicking on track icons that represent these OBlocks. To use this feature your panel must have your layout depicted by Indicator Track Icons placed there by Circuit builder or by you manually. Successive clicks cycle the choices through the four block fields.
A computer algorithm determines all the intermediate blocks, portals and paths to make the route. If more than one route meets the criterion, you are presented with a list to review and select the route you want. Note that the Portal and Paths need to be chosen for the route also. If no route is found, a dialog is offered where you can examine the routes that were attempted with the current Block, Portal and Path selections. Creating and Editing Warrants has more information about creating routes.
Scripting the Train ActionThe second part of a Warrant are the throttle commands to control the train as it traverses the route. These commands are recorded automatically by running a train over the route in "Learn Mode" or are generated automatically as an "NXWarrant". The script commands contain the elapsed time between commands. Playback will duplicate this timing. However when a warrant is run with a different engine or a different consist, or even the same train depending whether the motor is hot or cold, this timing may not be replicated exactly. Because of this the command script is synchronized upon entering each detection OBlock. So, if the train is slow in reaching the next block, the commands for the next block will be delayed until the train enters the block. Conversely, if the train reaches the next block ahead of time, any remaining commands in the block just left will issued with no elapsed time so that the train can catch up to the script.
Warrant scripts are recorded or generated with a "Clear", aspect throughout the route even through blocks with restricted speeds. These speeds in the script are the "Normal" speeds. However, after creation when running, track conditions may not be "Clear", due to a signal's speed restriction, a block's speed restriction, occupancy by a rouge train or even intevention by you to halt the train. Warrants are able to deal with these restrictions and will modify their Normal" speeds as needed to comply with the restrictions. The section "Warrants and Speed Restrictions" below explains this relationship.
Recording ScriptsThis is done by putting a screen throttle into Learn Mode that records all the throttle commands you make when driving the train over the route. This script can then be replayed to drive the train automatically. All possible throttle functions can be recorded and played back.
With LocoNet you may steal the address and manual LocoNet throttle. For other command systems, a WiFi throttle may take the same address as the screen throttle and be used to record a walk around script.
Generated ScriptsFor NXWarrants the script is generated by the warrant itself. It ramps the train up to a specified speed and ramps it down at the destination. It obeys all the traffic occupancy and signals as do the recorded warrants. See About NXWarrants for how to run them.
Customizing the ScriptA warrant script can be edited to modify the recorded commands. Additional non-throttle events can be added to the script such as triggering or responding to external sensors. Creating and Editing Warrants. has more information about creating and customizing scripts.
Warrants and Speed RestrictionsA train running under a warrant must be aware of track conditions ahead. Signals may indicate reduced speed or permission to return to normal speed. Blocks may impose yard limit speed restrictions. Rogue trains may show up unexpectedly in the route. In our imagination, we can presume their detection means our warrant "engineer" sees a fusse. For each of these cases the warrant must look ahead, detect the need for a speed change and schedule the right time to do it - all the while making the change smoothly and completing it in prototypical fashion.
Configuring Speed RestrictionsFor a warrant to detect a signaled speed change the signal must be configured in the Occupancy Block Tables. The Signal Table there configures the entrance Portal to the OBlock that the signal protects. The warrant then uses the signal system configured for the signal to detect the aspect speed.
Likewise, block speeds are configured in the Occupancy Block Tables. A column in the OBlock Table allows you to choose an aspect speed that the warrant will enforce.
When a occupancy sensor is activated ahead of the train on its route, the warrant will take note of it and make any necessary speed change.
Finally, you can instruct the warrant to ramp down to a stop or issue an emergency stop. Also, you can ramp up from a stop and resume the former speed.
When a warrant ramps down a speed change due to a signal, block or rouge occupancy condition, That speed change remains in effect until the condition is removed. At that time the speed is ramped up to the previous "normal" speed. The precedence order is: rouge occupancy, signal aspect, block speed.
A Note About RampsWhen JMRI needs to intervene and enforce a speed change that was not recorded, several calculations must be made. Two pieces of information are vital.
- Distance from the train to the situation requiring the speed change. For this the lengths of the paths of the route must be known.
- Speed of the train. For this a correlation of the throttle settings to the actual speed of the train on the layout must be known.
Parameters Needed for RampingTo compute how far to look ahead and the time when to modify speed the following must be known.
Block Lengths are needed for distances. There
is a length column in the OBlock Table. There is also
a column to open its path tables. Each path table has
a length column as well. Likewise the OBlock and OPath
windows in Circuit Builder have text fields to enter
lengths. Inches or centimeters may be used.
When no block length is specified a rather large value is assumed. It is highly recommended that block lengths be specified. Your wild guess is better than the default. If the paths within a block vary widely, path lengths should be set. Otherwise, path lengths are inherited from the block length.
- Layout Scale is needed for distances when speed is expressed as Mph or Km/h. This is set from a drop down box at the Edit->Preferences->Warrants menu of the main PanelPro window
Track Speed is more difficult to obtain reproducibly.
A first approximation is the "Throttle Setting/Speed Factor"
value at Edit->Preferences->Warrants.
When used this factor is a linear multiplier to relate throttle setting to track speed. Note this is a global value so all of the locomotives in your fleet may not operate optimally with the same factor. However, it could be satisfactory for your tastes.
- For more precision a Speed Profile can be made for each locomotive. While somewhat laborious to do, it does provide values to make more accurate calculations. The Speed Profiler is found at Roster->Speed Profiling.
- A first approximation is the "Throttle Setting/Speed Factor" value at Edit->Preferences->Warrants.
- Ramp Step throttle Increment This value is a ratio of full throttle. Seven or eight speed steps of a 128 step throttle is an appropriate increment for a locomotive with modest momentum. A value of 0.03 to 0.06 is recommended.
- Ramp Step time Depending how you have configured momentum on your locomotives, adjust this value so the speed change is completed within this period of time. Typically 300 to 1000 milliseconds would be appropriate.
Getting Speed Profiles for Your TrainsConverting a throttle setting to achieve a given track speed is dependent on the engine and its decoder. The decoder's speed curve to deliver voltage to the motor, and the motor's rpm response under load with that voltage is rarely linear. Likewise, whether the motor is driving the train forward or reverse often results in different track speeds.
A Speed Profile can be made for an engine that will provide the necessary factors to set throttle settings that will result in more accurate track speeds. These profiles are maintained in the Roster and there is a tool that will create them at Roster->Speed Profiling. Alternatively, Speed Profile factors for a selected set of throttle settings for the motive power used in a warrant can be determined by using the NXWarrant Compute Throttle Factor checkbox.
NXWarrants have a feature whereby running the train over a block of known length will compute a speed profile throttle factor for the train. Frequently, calibrating a slow, medium and fast throttle setting for both forward and reverse will be sufficient. See About NXWarrants.
Aspect Speed Map and its InterpretationSpeeds are named in the aspects.xml files that signal masts use in the Signal Mast System. These speed names are also used in the Blocks tables. To control train speed, values must be assigned to these speed names. The Aspect Speed Map found at >Edit->Preferences->Warrants provides a value for each named speed. It is up to the user to assign a value to the name and a meaning to the value. On the preferences warrant panel there are four radio buttons to assign meaning to the values entered into the Speed Map Table.
In defining the four choices, to help explain them we'll
use a few examples and compare them as the warrants approach
a signal whose entrance speed name is "Medium". In the
examples, the throttle setting for "Normal" is the recorded
throttle setting when approaching the signal.
Warrant#1 is recorded with Engine A and it achieves a scale speed of 60 mph (or 96 kmph) at a throttle setting of 0.8 (102 speed steps). This was the "Normal" speed recorded by the warrant approaching the signal.
We will also assume engines B and C use Warrant#1. Engine B only reaches a scale speed 50 mph at an 0.8 throttle setting and Engine C attains a scale speed 70 mph at an 0.8 throttle setting is also used in the warrant.
Warrant#2 is recorded with engine C and the "Normal" throttle setting approaching the signal was 0.68 which would be about 60 mph.
Warrant#3 is a slow freight recorded with engine C and the "Normal" throttle setting approaching the signal was 0.36, which would be about 31.5 mph.
We have the situation where the warrants are looking ahead to a signal showing an aspect of "Medium" speed. The prototype railroad using this signal defines medium speed as 30 mph. We will also assume we have set the Aspect speed name value to be the best guess we can make to duplicate prototypical speed at layout scale.
Percent of Normal - The value is a percentage of
the recorded ("Normal") speed. Speed names are
restrictive, therefore this value should be less than
Best guess for the table value of "Medium" is 50.
Warrant#1 will reduce the setting to 0.40 and this could be a perfect scale 30 mph for Engine A and Engine B is likely to reduce speed to 25 mph, but engine C will likely pass the signal at 35 mph.
Warrant#2 will reduce the setting to 0.34 and this could be a perfect scale 30 mph for Engine C. Engine A is likely to pass the signal at 25.5 mph and Engine B at about 21 mph.
Warrant#3 will reduce the setting to 0.18 and this is likely to give Engine C a speed of 16 mph passing the signal. The speeds of Engines A and B will be even slower.
In all case the recorded speed is reduced by half. That is, speed is always changed
Percent of Full Throttle - The value is an
absolute throttle setting expressed as a percentage of
full throttle, i.e. a number between 0 and 100.
A best guess for the table value for "Medium" is 40.
Warrant#1 will make the setting 0.40 and so Engine A most likely will pass the signal at 30 mph. Engine B is likely to reduce speed to 25 mph, but engine C will likely pass the signal at 35 mph.
Warrant#2 will make the setting 0.40 and so Engines A, B and C will pass the signal at the same speeds as above.
Warrant#3 will not change the setting since it is already less than 0.40 so Engine C's speed will be unchanged at 31.5 mph. Engine A most likely will pass the signal at 27 mph and Engine B at 22.5 mph.
This interpretation puts an upper limit on the throttle setting, but not the scale track speed.
Miles per hour - The value is the scale miles per
The table value for "Medium" should be 30.
For Warrant#1 and Warrant#2, using each engine's throttle factor Engines A. B, and C all will likely pass the signal at 30 mph.
Warrant#3 will modify Engine C's speed to 30 mph. It will not modify the speeds of Engines A and B. Engine A most likely will pass the signal at 27 mph and Engine B at 22.5 mph.
Given that a sufficient Speed Profile has been made, Prototypical signal speeds can be done without speed matching.
Kilometers per Hour - The value is the scale
kilometers per hour.
The table value for "Medium" should be 48.
The results are the same as the Mph case. This is simply using the metric system units.
The Signal Head Appearance TableIf signal heads are used on the layout, their appearances can be mapped to the speed names of signal masts in this table on the warrant preferences panel.
One use of this is to use virtual signal heads to dynamically influence the behavior of warrants. The appearance of these signals can be set either by panel icons or Logix. Since there are 8 possible signal head appearances additional speed names can be created so a unique speed can be made for each appearance.
Editing the Speed Map TableRows can be added or deleted. The default speed map has the names "Fifty" and "Sixty". These names only appear in signal mast systems for UP-2008 and BNSF-1996, so they can safely be deleted if you do use these signal systems. You only need but must have all the speed names that appear in the signal system you have configured for your layout.
If you add a new speed name for a signal head appearance, then add a row for that name in the Signal Map Table.
Block speed NamesA speed name can be set for each block by selecting a name from the Speed Notch column of the OBlock Table. One use of this feature could be to enforce a yard limit speed. Unlike signal speed names, block speed names are bi-directional. To return a warrant's speed to normal when leaving a yard limit, the speed names of the OBlocks on either side of the yard block should set to "Normal". Use care when combining this feature with signals to avoid providing conflicting speed change messages.
To unset an OBlock speed name choose the blank setting from the Speed Limit column. As with the absence of a signal, when there is no speed name the warrant continues at its current speed.
Using the Warrant ListThe Warrant List menu item opens the Warrant Table. Each row is a warrant that has been created and saved or is a running NXWarrant. The Warrant Table reports the current status of each warrant in the list and can issue commands to Halt, Resume or Abort. Warrant routes can be allocated, i.e. reserved for that warrant, the turnouts for route can be set and when the warrant is run, its status is shown and controlled using the columns in the table. See The Warrant List for information about the table.
Tracking TrainsAny train running on the layout can be tracked. The layout must be represented with Indicator Track Icons to track trains. The fourth Warrants menu item opens the Tracker Table. Pressing the New Tracker button in this window opens a dialog to enter a train name and the OBlock it occupies. Pressing the done button creates a row in the Tracking Table. The row shows the train name and the block it currently occupies and the length of time it has occupied the block. As the train moves from block to block, this status is updated. The Indicator Track Icons can display the train name.
The location of the train can be set by typing, by dragging block name from the picklist, or by clicking on a Indicator Track Icon in the panel.
Tracking can also be done for a train by dragging and dropping a Loco Icon onto the OBlock the train occupies. This is the most simple way of tracking in that both the names and location are done with a single drag and drop.
Using Warrants in LogixSeveral of the operations that can be done from the Warrant List and Warrant Editing frame can be done with Logix Conditionals. You may design and implement a dispatcher's panel using the Warrant state variables and actions found in Logix.
Warrant State VariablesWhen a warrant has been allocated or is in effect, the following state variables can be tested in a Logix conditional.
- Route Free: - True when all blocks in the warrant route are not allocated to anyone and are not occupied. False otherwise.
- Route Set: - True when all blocks in the warrant route are allocated and the turnouts set for this warrant. False otherwise.
- Route Allocated: - True when all blocks in the warrant route are allocated to this warrant. False otherwise.
- Route Occupied: - True when none of the blocks in the warrant route, other than the origin block, are occupied. (Assumes the train of this warrant is occupying the origin block). False otherwise.
- Train Running: - True when the train specified in the warrant is running either in Learn Mode or Auto Run Mode. False otherwise.
- Allocate Warrant Route: - Allocates the route to this warrant.
- Deallocate Warrant: - Deallocates the route of this warrant (only). This will not deallocate the route of a different warrant.
- Set Route Turnouts: - Sets the signals and turnouts for the route as far along the route that it can until it reaches an occupied block or a block allocated to another warrant.
- Auto Run Train: - Issue the throttle commands to the train in the warrant. This should only be done when the train occupies the Origin block.
- Set Train Id: - Set the engine consist to be used in the warrant from a trainId in the Engine Roster. Alternatively, the DCC address can be used to identify the engine.
- Set Train Name: - Set the name of the train to display in the loco marker indicating the current position of the train when running.
- Control Train: - Send a control command (Halt, Resume or Abort) to a running train under warrant.