JMRI: CTC

CTC is a very complex system. An understanding of the goals of CTC and how it functions is very helpful. While this tool will describe various CTC features, it is not a CTC course. There are many books written on the subject, for example Dr. Bruce Chubb's CTC manuals. Other materials (too numerous to list) exist on the Internet as well, such as Mike Burgett's web site (since shut down, but may be active in the future again).

Important: A requirement of CTC is that a fully functional ABS (Automatic Block Signaling) signaling system exist already in your system. As you may already know, CTC is just a layer on top of ABS.

Overview

The CTC system consists of three main components. The first one is the CTCEditor which is used to define the CTC system. The second component is CTCMain, which is a run time component which executes the rules created by the editor. These components are started by using the PanelPro Tools menu and/or including them as actions defined in Preferences >> Start Up.

The last component is the layout configuration in JMRI. This includes turnout definitions, occupancy sensors, blocks and signals. The signals can be defined as signal heads with SSL or signal masts using signal mast logic. The signaling implementation needs to properly implement ABS signaling before adding CTC. This includes proper block boundaries.

CTCEditor

To start the CTCEditor, on the main PanelPro screen select Tools/CTC, then press "Open CTC Configuration Editor".

The CTCEditor is used to define the CTC components and the rules that will be used by the run time component. The resulting data is stored in an XML file: CTCSystem.xml. This file is located at the user files location in the ctc directory.

As an option to support creation of the GUI portion of the CTC machine, an external Panel Editor panel file can be created by pressing a single button. This facilitates the design of the full GUI CTC panel. This feature also creates a 2nd minimal panel xml file that contains all of the CTC specific internal sensors.

CTCMain

CTCMain is the run time component that provides all of the logic to implement a CTC machine. It responds to layout and panel inputs and takes appropriate actions based on the definitions provided by the CTCEditor. It eliminates the need to create Logix or scripts.

Defining a CTC System

Use the following table of contents to jump to various topics. For new CTC implementations, the topics should be reviewed/done in order.

  1. CTCEditor
    1. Menus
      1. File menu
        1. New
        2. Save
        3. Exit without saving
      2. Edit menu
        1. Find and Replace...
        2. Fix Error(s)...
      3. Configure menu
        1. Debugging
        2. Defaults
        3. Fleeting
        4. Patterns
        5. GUI Design
    2. O.S. Sections List
    3. Edit Buttons
      1. Code button
      2. Signal direction indicators
      3. Signal direction lever
      4. Switch direction indicators
      5. Switch direction lever
      6. Call On
      7. Traffic locking
      8. Turnout locking
      9. Indication locking
  2. Files
  3. CTCMain
  4. Definitions

CTCEditor

The CTCEditor consists of a menu bar, a section containing a list of the defined OS sections with related buttons and a group of 9 buttons at the bottom. With the exception of the Code button, the remaining buttons can be enabled to activate the selected CTC feature.

When the editor is started, it loads the current CTCSystem.xml file. When the editor is stopped by using the window close button, the CTCSystem.xml file is updated. See the file menu for other options.

Editor Menus

File menu

The New menu item deletes the current configuration in the editor. If the editor is then closed (which does an automatic save), the CTCSystem.xml file will be empty.

The Save menu item writes the current editor configuration to the CTCSystem.xml file. The CTCEditor program is not closed.

The Exit without saving menu item after asking for confirmation that you really want to do this, discards any changes and closes the CTCEditor.

Edit menu

Find and Replace...

This invokes a powerful editor. It doesn't have many features, but the important point is that it will search everything in the system for references to things that may be changing. For example, when changing "IS8:LDGL" -> "IS8:XYZZY", the program will list all of these references, and if approved will change all of them, so that there are no "dangling references" to something that no longer exists. In this manner, it is a "refactor / replace" function (for programmers who understand these terms).

Only data "destined" for JMRI is scanned. None of the data maintained by this program for its own internal use (such as Patterns, Defaults, etc.), is scanned.

Searching

Enter in the text to search for, along with "Case sensitive" checkbox and Exact / Contains radio buttons.

Once the Search button is pressed, the results are shown on the right. This shows where the search string was found in the system, and the context it is used in. No items are selected. Press Select all to select all rows. That button now says Deselect all (it flip/flops from one to the other). The standard single selection, multiple selection and range selection options are available. A count of the items selected appears next to the Replace button. Only the selected items will be replaced.

Replacing

At least one item has to be selected before the Replace button will be enabled. The radio buttons above it allows the replace process to be modified.

Replace completely: The entire line no matter where the search string is found is replaced by the "Replace with: " text. This is not a common choice.

Replace searched for value only: This is the typical choice and the default. The search text is replaced with the replacement text.

Rescan with below and substitute with above: The purpose of this is to use the first search function to locate lines with other data in them, then re-scan each of the lines selected with the new search pattern, and substitute the "Replace with:" value there. This sub-search is case sensitive.

Note: Depending on the nature of the change, it is possible that new sensors are required. For example, changing IS2:CB to IS2:CodeBtn results in a new code button sensor. If the panel xml file already refers to the old sensor name, it will have to be modified.

Warning: At present, there is no "Undo".

Fix Error(s)...

If an attempt is made to save the editor data and the ***ERROR*** indicator appears anywhere in the Columns listing, the save, including the automatic save during program exit, will not occur. A dialog will suggest doing this menu item. Please read carefully the information in this menu item.

Configure menu

Debugging

The defaults here are good enough, but may modified if desired.

CTC system reload sensor: This sensor, when triggered (set to active) will cause the entire CTC system to reload. This makes it possible to make CTCEditor changes and then test them immediately without having to restart JMRI each time. See "Running the CTC system under JMRI" for more information on this.

CTC debug traffic locking rules triggered display sensor: When active, the number of the Traffic Locking rule that was true is logged when a code button is pressed. It is logged as an INFO message to the System Console. In order to see the System Console within JMRI select Help >> System console... It's the "Green Screen".

Defaults

Signal System Type: Select either Signal Heads or Signal Masts.

Turnout locks enabled at startup and Seconds until all lockable turnouts locked: The default is checked and the CTC system will lock all of the turnouts automatically at startup. Some layouts require locks to be unlocked at CTC system startup for other external (to CTC) initialization requirements. You can then have your dispatcher manually lock all of the locked turnouts before the layout starts operation. Or, you can set the "Seconds until all lockable turnouts locked" to a value >0 (in seconds), and the CTC system will do this automatically after that time period. Note: each time JMRI is started, it takes a variable amount of time to complete, so this value may have to be set a bit higher than the quickest time, in order to give the system a chance to stabilize before locking the turnouts. Or you can invoke the following lines (however you want) in a Jython script file in order to have this done automatically by your script(s) after your special external initialization requirements are done:

        import jmri
        ctcMain = jmri.InstanceManager.getNullableDefault(jmri.jmrit.ctc.CTCMain)
        if ctcMain is not None: ctcMain.externalLockTurnout()
        

Time values (for Signal and Switch directions): These are values that are given to each CTC O.S. section as default values when the CTC O.S. section is created. The timing values edit boxes are standard CTC values, refer to Definitions for more information on each.

No code button delay in milliseconds: This is the default for newly created O.S. Sections. Individual O.S. sections can be changed if needed. Background: Normal CTC panels always had a code button for every O.S. section which means a value of zero is appropriate. Certain tower situations did not have a code button(s) present when some or all or the O.S. Section(s) were local to the tower. In this case, the tower operator changing either the switch direction and/or signal direction levers was enough to transmit the request to the field. On the prototype, there was a built in delay so that the tower operator could change both the switch and signal levers before the code was transmitted to the local O.S. section. That delay is simulated with this value. Having a larger value will increase this delay, and a large enough value will allow the tower operator to change both the switch and signal lever before the codes are transmitted to the field. A reasonable value in this case might be 5000 (5 seconds). Some towers had virtually no delay, so enter a value such as 10 milliseconds.

Fleeting

Fleeting toggle sensor: The sensor used to enable/disable fleeting.

Fleeting enabled at start: Default is to not enable fleeting during startup.

Patterns

Since there will probably be 100's if not 1,000's of JMRI internal sensor objects (Prefix "IS:") that need to be created to support all of the on-screen objects of a typical CTC installation, it is important that you realize how this program works with these "patterns"". By using them, you do not have to spend dozens of hours to enter all of this in manually, or make a mistake and have the JMRI runtime system complain of problem(s) - back and forth, make a change, run JMRI, find another problem, etc. Using patterns prevents this.

Patterns are used for all of the internal sensors created by this system. When an O.S. section is created, there are two numbers that are associated with that O.S. section: a switch number (always odd) and the corresponding signal number (always even and always one more than the switch number).

The pattern format is IS#:XXX. The "#" character in the edit boxes are substituted automatically when the CTC O.S. section is first created. The respective switch / signal areas use the respective switch # / signal # given for the O.S. Section. If more than one "#" appears, every "#" will get the corresponding substituted number. In this way you do not have to do all of the manual typing or selecting associated with creating all of these sensor strings.

Patterns usage by this program and its advantages over other methods

Every time an O.S. section is created, the program will apply a set of patterns provided by the user: a default set of patterns is automatically generated by the program at startup which the user can override at will. This will be explained in more detail later. In order to see these default patterns, start the program and choose "Configure / Patterns"".

Changing anything on this screen has no effect on existing information in the system. It is only used when a new O.S. section (via Add button) is created. However, you may selectively re-apply this pattern to the whole system or individual pieces of the system. Here's how:

Reapplying patterns to existing information: Once you've changed this screen, you may want the new pattern to be selectively applied. There are two choices: 1.) Reapply pattern to selected item (a single O.S. section) or 2.) Reapply pattern to selected item (a single O.S. section) specific sub-system. To do 1, get to the main screen, and select a single O.S. section. The "Reapply patterns to selected item" button will be enabled. When you press this button, a confirmation dialog will appear. Pressing "Yes" will then take the new pattern specified and completely apply it to all of the O.S. Sections sub-systems. To do 2, get to the main screen, and select a single O.S. section. Then at the bottom of the screen, press the "Edit" button for the sub-system you want to modify. NOTE: Some sub-systems are not affected by this, so what follows may not appear. You will then see a button at the bottom of the sub-system selected with "Reapply patterns - this form ONLY!". Pressing that will immediately show you the results of the new pattern in the edit boxes of that screen.

GUI Design

GUI Design - automatic creation of the JMRI GUI screen: An additional feature of this program is to be able to automatically create a "standard" USS CTC panel from the parameters specified elsewhere in this program. This screen configures those available options. See "Files created for support...." for more information and procedures for loading them into the JMRI system. Everything is put in pre-determined locations on the screen. It is an easy procedure in JMRI's Panel Editor (or other) to reposition those items. Caveat emptor: If you do change the locations of these items, JMRI does not modify the files created by this program. It is not designed to keep track of which file contains which modifications. Only if you save the panel to completely different panel name will those changes be saved. You should completely design the CTC panel using this program before saving to another name in JMRI, and then begin the final changes to that panel from within JMRI.

Extra blank columns after last defined column to create: Normally, if this is 0, this program creates after the last CTC O.S. Section column specified a "right edge of CTC machine panel". If you want additional blank column(s) between your last CTC O.S. Sections column # and the right edge, enter that number here.

Type of CTC panel: Presently only USS is available at this time (10/31/2018). More may be available in the future.

Vertical size: JMRI provides blank panel items in each of the sizes listed. Choose one.

Signals on panel All O.S. Section signals - All of the signals specified in the Signal Direction Indicators sub-system are created on the screen for you. This is not a prototype practice, but will help in your development of SSL (Simple Signal Logic) and CTC design. You can see the state of the signals in the field with this. Signal heads or Signal masts will be created per your specification. Green/off only (Future feature) - Not available at this time. The prototype in certain installations have a single green indicator indicating all signal(s) at that location are displaying stop (red) (green indicator off) or permissive of some form (one or more signals at that location non-stop (non-red)).

Builder Plate Check this if you want the builder plate on the machine face.

Turnouts on panel Normally you want to generate turnouts on the CTC track board, which is the default "Generate checked". If you don"t want this feature, uncheck this.

Fleeting toggle switch (only if fleeting configured) Create the toggle switch on the panel if checked.

Analog clock and clock on toggle Create an analog clock on the panel, along with above it a toggle switch to turn it on / off.

Reload CTC system button Create a button on the screen to perform this.

CTC Debug on toggle Ditto.

Create variety of track pieces (future feature): A variety of track pieces are created on the screen, so that it is easier to "copy / paste" all of these objects as the designer desires.

O.S. Occupancy sensor blinks red when unknown or inconsistent Normally, JMRI will display an "X" or "?" on a sensor when its state is unknown or inconsistent. By checking this checkbox, the program will substitute a blinking indicator for these to draw better attention to them. I personally use these for optical sensors on my layout because of the number of sensors on my layout causes LocoNet to loose messages at system startup.

OS Section List

The Prototype CTC machine and this program

A prototype CTC machine is organized by columns (my term). A single CTC machine column can be blank, or contain an O.S. section and all of the associated controls. I begin the numbering of my CTC machine columns with 1. This column number has no relation or correlation at all to the Switch or Signal numbers of a normal O.S. section. You can create as many columns as you like on the computer screen(s).

OS Sections

A non-blank column always has an O.S. section with a code button associated with it. An O.S. section always has an odd switch number and an even signal number, where the signal number is always one more than the switch number. Each O.S. section as it is created does not have to be 2 more than the prior switch number entry. Example: 1, 3, 7, 15, 17.... They do not have to be in ascending sequence, their order has no impact on the program. However, it is strongly suggested per prototype practice that they are in ascending sequence. You may re-order them on the main screen using up/down buttons in case you entered them out of order, which is described in another section.

"JMRI Validation" and "Check everything with JMRI" (grayed out at start)

Prerequisite: A new system displays "JMRI Validation: Disabled", and also the button "Check everything with JMRI" is grayed out (disabled). This is normal for a new system.

Once both of the sensors defined in Configure/Debugging are contained in the panel file and that panel file is loaded, then "JMRI Validation: Enabled" will be displayed and the button "Check everything with JMRI" is available for pressing.

The purpose of pressing "Check everything with JMRI":

Pressing this will then present you with a dialog asking if you want to see all of the errors listed on a separate screen. It will then go thru every JMRI object that is backed by a real device (sensor, signals, etc) defined in the CTC system and verify that a definition exists for it within JMRI already. This is just a sanity check, and normally you should not encounter any errors. If you do, then define the missing object(s) in JMRI.

Action buttons (to the right of the "Presently defined CTC O.S. sections:")

These buttons are dynamically enabled or disabled based upon the selected item. Button "Add" is always available.

Add

Allows you to add another column.

After pressing, configure the two values as needed.

Regarding the check box "GUI Generated before": If checked, then this column has already been generated once before. In case you want it to be generated again when you press "Write .xml files for JMRI GUI support", clear the check box.

Delete

Allows you to delete a column if there are no references to it.

If you notice in the column that you are deleting that there are items in parenthesis's, you will be prevented from deleting that column with an error message. Only when the parenthesis's disappear will you be allowed to delete the column.

The general format is #/# indicating which switch and signal column entry is referencing this entry, followed by the following letter possibilities: "TrL:" Traffic Locking rule references this. If there is an 'L' appended, it indicates left traffic rules, otherwise right traffic rules. "Sw:" Switch Slaved references this.

Edit Buttons (at the bottom of the screen)

Code button

This provides the major information for a single O.S. section.

Code button sensor: Required. Enter the sensor associated with this code button. This name is automatically generated by the patterns system.

Primary O.S. section occupied sensor: Required. So long as this sensor is active (indicating that the O.S. section is occupied), then the following cannot be changed: signals, turnout change, lock/unlock turnout and call on. This should be the main occupancy sensor.

Secondary O.S. section occupied sensor: Optional. Typically this is entered when a crossover is in an O.S. section and you have two sensors, one for each parallel track. This is the non-primary route, for instance the other side's track sensor. When active, it prevents turnout change and lock/unlock turnout only.

Switch slaved to O.S. section #: Optional. Use this to slave another O.S. section with just a turnout in it to this O.S. section. Used primarily when one track goes to 3 or more other tracks via multiple turnouts.

No code button delay in milliseconds: Required. If there is no code button (i.e. a tower operation), then put in the delay between when either the turnout or traffic direction switches are changed and when the action actually occurs.

Signal direction indicators

Defines all of the information required for displaying the signal direction indicators on the CTC panel, and which signal(s) in the field control them.

Left, Normal and Right indicator sensors: Normal and one or both of Left and Right required. The three indicators on the panel. These names are automatically generated by the patterns system. If this is a unidirectional O.S. section, then leave either the Left or Right sensor blank (not both!).

Coding and response time milliseconds: and Time locking interval milliseconds: Required. Values are defaulted from the defaults screen. Change as you see fit to make each section unique if you want.

Left to right and Right to left traffic signal lists: Here you specify each of the signal masts or individual signal heads associated in each direction with this O.S. section. There must be at least one entry in each, unless it is a uni-directional O.S. section.

Signal direction lever

Defines all of the sensors required for the JMRI object MultiSensor in order to select a signal direction.

Left, Normal and Right lever sensors: Normal and one or both of Left and Right required. This defines the three sensors associated with the 3 corresponding positions of the MultiSensor. These names are automatically generated by the patterns system. If this is a unidirectional O.S. section, then leave either the Left or Right sensor blank (not both!). The missing entry should match the corresponding missing entry in the Signal Direction Indicators for this O.S. section.

Switch direction indicators

Defines all of the information for displaying the switch direction indicators on the CTC panel, and which switch in the field controls them.

Normal and Reverse indicator sensors: Required. The two indicators on the panel. These names are automatically generated by the patterns system.

Actual turnout: Required. The turnout who's information is being displayed.

Coding and response time milliseconds: Required. Values are defaulted from the defaults screen. Change as you see fit to make each section unique if you want.

Feedback different: JMRI does not support backwards feedback values, i.e. turnout is commanded to CLOSED, turnout reports THROWN. Check this if your device's feedback is opposite from the commanded value.

Optional GUI parameters: Ignore this if you are not generating GUI information. Otherwise select the type of turnout from the 3 radio buttons, Check "Left hand turnout" if so, and if "Crossover" is selected, then check "Other turnout also left handed" if so.

Switch direction lever

Defines the one sensor associated with the Sensor icon lever.

Lever sensor: Required. This name is automatically generated by the patterns system.

Call On

Defines all of the information for controlling (allowing) call on aspect(s) to be displayed in the field.

Toggle sensor: Required. This name is automatically generated by the patterns system. This associates the toggle switch on the panel with this Call On.

When you first enter this screen, there is nothing in the "Grouping list" area. Once you have entered new entries, you may individually select an entry by clicking on it, and then the "Edit Below" and "Delete" buttons become available, along with various field(s) below being enabled for changing. In order to get started, press "Add New" the first time here, and various fields below will be enabled based upon how you have configured you system for Signal Heads or Signal Masts in "Configure / Defaults". All fields will be described below, but may not be available based upon Signal Heads or Signal Masts selected:

Signal: Required. Choose from the signals defined in your system already. Then select in the drop down to the right of this field whether the signal faces Left or Right.

Aspect: Required. Choose from the available aspects in the drop down list. Do not choose flashing aspects for semaphores! The semaphore will act weird as it tries and fails to keep up with the stream of movements.

Called on sensor: Required. Choose from the sensors defined in your system already.

Block: Required. Choose from the blocks defined in your system already. You must manually check in JMRI the "Permissive" checkbox for this block in order for call on to work for this block, which is outside the scope of this editor.

--- Route --- Choose up to 6 switch direction indicators that when lit specify the route from the O.S. section to the called on block (Signal Masts) or sensor associated with the block (Signal Heads).

Traffic Locking

Defines all of the allowed non conflicting routes from the selected O.S. section in either direction from it. This is the beating heart of the CTC system. As such, it is the most complex part of CTC you will encounter. However, if you are methodical and after some experience, you should find that this section is fairly straight forward.

When you initially select Traffic Locking, the first screen that comes up will allow you to edit one of the directions from this O.S. section to other O.S. section(s). Note: Having no rules always allows that direction of travel no matter any other condition, and may be valid in certain situations such as traveling to staging where there is no O.S. section.

Select either Left or Right to proceed. On the next screen that appears, you will notice that the "Rules:" area is blank, and that "Add New" is only button enabled. Press "Add New" now, and notice how the bottom half of the screen is enabled for editing of this new rule.

Before we proceed to details on this rule, you will notice that "This rule ENABLED" is checked by default. You may enable / disable individual rules at your whim, you mostly disable ones so that the information is not lost, and you may in the future want to re-enable it.

Part of the design of your CTC system (which has nothing to do with this program) is determining where the interlocking limits are in complex trackwork situations, such as parallel (or 3 or more) tracks with multiple switches and crossovers. It is beyond the scope of this help in guiding you in designing interlocking plants. For instance, it depends on how you want simultaneous moves to occur within interlocking limits that may need to be considered.

Specifying a rule:

Under "--- ROUTE ---", you specify the O.S. section(s) traversed, and the switch alignment associated with each O.S. section for that route. Order of specified O.S. section(s) is irrelevant. For a simple route, such as a passing siding, there will only be one switch. A complex interlocking will normally have several switches. An O.S. section that contains a turnout will have at least two routes, a closed route and a thrown route.

Under "Occupancy sensors ... allowed." you specify the sensor(s) that will be locked for that route. For simple routes, the O.S. section occupancy sensor and the occupancy sensor for the destination block will be specified.

Under "--- Optional sensors... valid ---", specify any sensors that must be ACTIVE to allow this rule to be valid. You may (for instance) use JMRI Logix to create such a sensor for specific unusual situations. Important: These optional sensors are not allocated as part of the rule. They are just checked at the moment the dispatcher codes the O.S. section.

Final result: When the dispatcher codes this O.S. section, the Left or Right rule set is selected based on the position of the signal lever. A specific rule is then selected based on the turnout positions. If all of the occupancy sensors defined in the rule are inactive and not already allocated to another route, along with optional sensors if defined, then the occupancy sensors are allocated. The allocation for each occupancy sensor is removed after it becomes occupied and then unoccupied.

In complex interlocking situations: as a train traverses the rule's occupancy sensor(s) and transited occupancy sensor(s) are released, other rules that don't conflict with the remaining allocated occupancy sensors may be allowed before this train has fully transited this whole rule, and the dispatcher may select these routes (rules) safely.

Turnout locking

Background: On my layout for main line turnouts, I have a local push button for each DS-54 and DS-64 that locally requests the turnout to "flip" the other way. By locally, I mean no computer involvement. I originally designed it this way so that if the computer failed for any reason, the layout could still be operated without any computer system involvement. This is fail safe: No computer, "Mother may I" via phones to the Dispatcher with a magnet (or some such) board of the track plan for collision avoidance.

All of the main line turnouts on my layout use the other bit available of 2 available inputs for each turnout on the DS-54 or DS-64 for feedback. JMRI's parlance for this is "Mode = INDIRECT" in the Turnouts table.

How "Lock implementation: Greg's" works in this situation (the ONLY supported possibility at this time):

If the JMRI software monitored the LocoNet network for turnout commands, the switch could not be locked properly, because the local button generates no messages to LocoNet. However, with the feedback available (INDIRECT), what my software does is when it sees a feedback message that disagrees with the locked state of the turnout, it immediately send a countermand command to restore the turnout to its proper locked state that the dispatcher wants/controls. As a consequence, an operator when pushing the local push button while the dispatcher has the switch locked notices that the switch goes about 1/2 way, and then returns to its locked position. Repeated pushing of the switch just repeats this. The dispatcher will see the Switch indicators blink back and forth without input from the dispatcher, so they know someone is trying to wrongly change the switch. One could say that by the switch going 1/2 way, a train going over the switch would derail, and you'd be correct. But since my layout has the push buttons right next to the switch it controls, hopefully an operator won't attempt to purposely derail a train.

There are two main situations that need to be considered separately:

Turnout locks in an O.S. section:

This is the typical case, and requires nothing special be done. In the prototype, the O.S. section must be unoccupied in order for a turnout to be unlocked. Locking a turnout can always occur at any time. There are two situations to be considered:

  1. The turnout has local control but that is never granted by the dispatcher.
  2. The turnout has local control that can be granted to the crews in the field by the dispatcher.

1. is for all main line turnouts typically, that do not go to a siding that is switched by the crews. In this way the turnout is locked permanently, and the dispatcher cannot grant local control. In this case, press "Just" a locked turnout, and fields are cleared that are not needed, which are fields Dispatcher sensor lock toggle, Dispatcher sensor unlocked indicator. The field Actual turnout is required.

2. is for those turnouts that are normally locked by the dispatcher, but the local crews can ask for local control to do switching.

Configure the rest of the screen as needed.

Turnout locks in a non O.S. section (and how to create them):

Just create the section that contains the turnout as if it was an O.S. section. Use a switch number that is higher than the highest value you will use on the CTC machine, or for safety, use values starting with 1001. For the GUI column #, use the proper number to create both the code button and the lock/unlock toggle switch in the proper place.

However, do not check and features except the Turnout Locking check box for this fake O.S. section. This is how this is differentiated from the above true O.S. section lock.

When configuring the Code Button, you will be required to enter an occupancy sensor. Enter the occupancy sensor containing the turnout to be locked.

For this situation, the prototype required occupancy of that section to exist when unlock(s) of the turnout(s) are to occur. The purpose of this on the prototype is safety: so that the Dispatcher does not accidentally unlock an unoccupied block and leave it that way, thereby possibly causing a derailment sometime in the future, or for signals to not clear into this block

Feedbacks different check boxes:

Normally, the feedback value matches the commanded value. JMRI allows for both being backwards, and in order to fix that, you put a check the "Inverted" column in the Turnouts Table in JMRI. However, in case the feedback value is different than the commanded value, then you put a check in that column. The following table lists the possibilities:

Command: Feedback: JMRI Turnout inverted checked: CTCEditor feedbacks different checked:
Normal Normal No No
Reversed Reversed Yes No
Normal Reversed No Yes
Reversed Normal Yes Yes

Indication locking

Defines any additional locking of an O.S. section above and beyond what is normally expected by this system.

As indicated on the screen, specify the signal head(s) / signal mast(s) that when any are non-red, the O.S. section is considered indication locked. When an O.S. section is locked this way, the turnout and turnout lock/unlock functions are disabled so long as any of these are non-red.

Files

All files for the CTC system are stored in the "ctc" directory under the User Files Location. In order to access this directory, on the main JMRI screen, press "Help", then select "Locations". This will bring up a JMRI screen with all of the possible locations. Press "Open User Files Location". That will open up the file manager at that location. You should notice a "ctc" directory under it. Navigate to it. What follows is a discussion of the files located there.

CTCSystem.xml and all CTCSystem.xml?.bup files

CTCSystem.xml contains all of your information that you've entered for the CTC system. The "bup" files are prior versions made each time you save the CTCSystem.xml file.

ProgramProperties.xml and all ProgramProperties.xml.?.bup files

ProgramProperties.xml contains all of the configurable parameters of the CTC system. Primarily it contains the parameters specfied under all of the "Configure" options on the main CTCEditor screen. The "bup" files are prior versions of this file.

AwtWindowProperties.txt

This file contains location and size information for all CTCEditor dialogs, so that when you locate a dialog on the screen, the next time you either resize or relocate it, it will be opened at this same location and size. You can freely delete it at any time.

Optional files

All of the following files may or may not exist. Once the "Write .xml files for JMRI GUI support" is pressed on the main CTCEditor screen, they are created. They are created anew each time the "Write .xml files for JMRI GUI support" is pressed.

GUIObjects.xml

It contains all of the basic GUI JMRI objects necessary for creating a "raw" CTC panel in the Panel Editor. It can be loaded at any time by pressing (on the main JMRI screen) "Panels / Open Panels..." and specifying this location and filename to load.

InternalSensors.xml

It contains all of the sensors created by the CTCEditor. These sensors are required for proper operation of the CTC panel. It can be loaded at any time by pressing (on the main JMRI screen) "Panels / Open Panels..." and specifying this location and filename to load.

VirtualSignals.xml

Deprecated and obsolete. You may freely delete it.

CTC integration of sensors and a populated Panel Editor panel

There are two basic types of sensors needed by the CTC system: sensors that are backed by real objects on the layout and are not created by this system, and "soft" sensors that are created as needed by this program for objects on the CTC Panel Editor panel (indicators, levers, toggles, push buttons, etc.). These "soft" sensors definitions are created in the InternalSensors.xml file (mentioned above), which you can load via "Open Panel". You may load this file multiple times, there is no danger doing this.

CTC integration of panel objects created in the GUIObjects.xml file

Each time a new CTC column is defined, and the "Write .xml files for JMRI GUI support" button is pressed, only the NEW column(s) since the button was last pressed are written to the file.

If you select an existing O.S. section and press "Change Switch and Signal Etc. #'s:", the next screen contains a checkbox "GUI Generated before". As each entry is written to the GUIObjects.xml file, this checkbox is automatically checked. If you want, you may clear the checkbox and the next time GUIObjects.xml is generated, those O.S. section(s) will appear again in it, and the checkbox will be re-checked again.

Do not load the GUIObjects.xml file more than once, otherwise you will have many duplicate items on the screen.

Proper development cycle

Using the CTCEditor, first define all of your O.S. sections to the best of your knowledge, then create and then load the GUIObjects.xml panel in, and review the results. If you are not happy, then delete the panel, save the panel file, and re-iterate the process (i.e. CTCEditor, write files, etc.).

CTCMain

Remember: Before you start CTC runtime, you need to load the panel. Ideally: Before you start CTCEditor, you also should load the panel to get reference checking of your JMRI objects (turnouts, sensors, etc.).

Starting it up

After defining the CTC system using the CTCEditor, you'll need to start it up. On the main PanelPro screen, under Tools/CTC, you will see the selection "Run CTC Logic". This will start it up right now (on demand real time).

For ease of access during development: if you want to define button(s) on the main PanelPro screen to do this (or to also invoke the CTCEditor via another button), do the following: From the main PanelPro screen: "Edit/Preferences...", then press "Start Up", at the bottom you will see an "Add", press it and select "Add button to main window...", scroll to "Start CTC Runtime" and select it. For CTCEditor, do the same but instead scroll to "Open CTC Editor" and select it.

To start it up as part of the startup of JMRI: Edit/Preferences...", press Start Up, press Add, select "Perform Action", and select "Start CTC Runtime".

Global sensors and the icons associated with them

Debug (default: IS:DEBUGCTC), Reload (default: IS:RELOADCTC) and Fleeting (default: IS:FLEETING).

Debug and Reload can be accessed via CTCEditor Configure/Debugging. Fleeting can be accessed via CTCEditor Configure/Fleeting.

These are convenience functions, and can be removed at any time.

Debug

When this toggle switch is turned on (not off), it will dump out all of the presently locked routes in the system, and for each route will list the resource(s) still allocated to the route onto the JMRI System console screen.

While this toggle is on, each time a code button is pressed and a signal direction lever for that code button selects a direction of travel, the program will list out the single rule that was satisfied (if any). If none are listed, then none were satisfied. Note: Even if a rule is valid, the ABS system may not clear up a signal in the direction indicated, and the CTC system will re-lock that O.S. section.

Reload

When this button is pressed, the CTC system will reload the last saved CTCEditor session. Remember: When you make changes to the CTC system via the CTCEditor, save the results before pressing this button.

After this button is pressed, the CTC system will be completely re-initialized to it's starting position(s). Also, remember to look at the JMRI System console for any new errors.

You should remove this button after all debugging is completed, so that your dispatcher doesn't accidentally push it during a session.

Fleeting

Fleeting is a concept within "normal" CTC, and may not be useful. Most model (not prototype) dispatchers don't use it even if available, due to the "speed" of the layout's status changing.

Definitions

Running time
When a dispatcher had previously cleared a route thru an interlocking or O.S. Section, and it is still clear, and then the dispatcher now attempts to change their mind and bring signals to stop, the system will run time and lock the route and signals during that time. At the end of that time, the CTC system will release and then allow a new route and signal state to be established.

 

Why? Locomotive engineers always expect a yellow signal of some form before an absolute stop red signal at a Home signal of an O.S. section. This gives the engineer time to begin slowing the train upon approaching the yellow approach signal expecting a possible red signal at the next home signal.

 

If the dispatcher was allowed to immediately change a Green home signal to a Red signal it is possible that a locomotive engineer just passed that prior approach signal and saw Green, and now expects at worst to see Yellow at the home signal. In this situation, the train may be traveling too fast to stop in time at the Home signal's red signal, and actually overshoot it and enter the interlocking. By locking down the plant during this time, the route and signals already established may allow this overshooting train to enter the interlocking in a safe manner. The amount time associated with this "running time" depends on many factors in real life: Train speed on the segment of track, sighting distances, etc.

 

On a model railroad, due to such short distances and the fact that our models can "stop on a dime" relative to a real train, and the fact that we are running typically with fast clocks, you may want to limit this time to say (my default) 5 seconds. Otherwise a busy layout may come to a screeching halt. Some layouts use 30 seconds or 1 minute to "force" Dispatchers to think ahead and prevent this situation. Your choice.

 

Signal locking (route locking)
When a route is cleared thru an interlocking, no changes to the route or other signals may occur so long as a signal protecting the interlocking allows movement thru that interlocking.

 

Interlocking
An arrangement of signal apparatus that prevents conflicting movements through an arrangement of tracks such as junctions or crossings. The signaling appliances and tracks are sometimes collectively referred to as an interlocking plant. An interlocking is designed so that it is impossible to display a signal to proceed unless the route to be used is proven safe. An interlocking may consist of one or more O.S. Section(s).

 

Interlocking plant
See Interlocking. The terms are used interchangeably in this document.

 

Indication locking
Same as Signal locking

 

Code button
Button to press to being the process of throwing switches / setting signals by sending control codes to the field to effect those changes requested by the operator. This button may have no or partial effect if there are rule conflict(s) i.e. unsafe condition(s) associated with the requested change(s).

 

Call on
Used to allow "back to train" movements. Normally, CTC systems prevent signals being cleared into an occupied section of track. Example: When an engineer is attempting a run around move, and as the last part of the run around attempts to rejoin their train. The CTC system and trackside signals (the vital signal logic) will actively prevent that. Pressing (or toggling) the Call on feature while pressing the code button bypasses the safety checks of the Vital signal logic and CTC systems, and allows that signal to go to its most restrictive aspect. Now the engineer will get a non-red indication which allows them to rejoin their train.

 

Vital signal logic
The trackside "relay" logic (on the prototype) that actively prevents unsafe situations in the field. CTC can only force signals to Red (their most restrictive aspect). Other than that, CTC has absolutely no effect on this Vital Signal Logic (except in a Call on situation). CTC systems "sit on top of" the Vital signal logic trackside. CTC cannot clear a signal. CTC can only allow the vital signal logic to allow a signal to go "non-Red". Most of the time this vital signal logic is implemented by ABS or APB systems. In JMRI, this is known as "SSL" - Simple Signal Logic, and is ABS.

 

Fleeting
When enabled, will allow interlocking signals to automatically maintain an already established direction of traffic. Normally, all signals in an interlocking drop to red and remain there after train movement thru the interlocking.

 

Signal Direction Indicators
Summarizes the state of all the signals in the field associated with this O.S. Section. If the center red indicator is lit (indicating "signals normal"), all entrances into the O.S. Section are displaying stop. A green in either direction indicates signal(s) in the indicated direction are not displaying stop, and traffic may proceed in that direction. If all 3 indicators are unlit ("out of correspondence"), the signals are either running time, or the CTC system has sent commands to the signals in the field and is waiting for replies from those signals as to their status.

 

Signals Normal
The "normal" state of an O.S. section is "all stop", i.e. all home signals protecting entry in the O.S. Section are at Red.

 

Signal Direction Lever
Lever used to establish a direction of traffic thru an O.S. Section. Moving this lever has no effect on the signal in the field until the code button is pressed, and all rules are valid for allowing the change to occur.

 

It is not valid to attempt to change from one direction to the other. The CTC system instead will interpret this as a request for "Signals normal" (all stop) first, and then (after probably running time) with another code button press to change direction to the requested direction.

 

Switch Direction Indicators
Shows the current state of the turnout in the field. Green indicator is lit is for the normal route, and the yellow indicator is lit for the non-normal route. If both indicators are unlit ("out of correspondence"), the CTC system has sent a command to the turnout to change and is awaiting the acknowledgement of movement to the new position.

 

Switch Direction Lever
Lever used to change the position of the indicated turnout. Moving this lever has no effect on the switch in the field until the code button is pressed and all rules for allowing change in the switch orientation are valid.

 

Traffic Locking
The set of rules that prevent adjacent O.S. Sections (reached by a possible series of track switches, i.e. routes) from directing traffic in opposite directions into the common track between them.

 

Turnout Locking
When signals are cleared over a specific turnout, or the O.S. section controlling that turnout is occupied, that turnout is considered locked and its orientation cannot be changed.

 

Coding District
A grouping of signals, track switches etc. that have a single CTC "wire" to them. Unused in my system, so I will not elaborate on this further.

 

O.S. Section
A single control point on the CTC panel. Contains at minimum a code button, and other assorted features.

 

Home Signal(s)
All Signals that protect entry into an O.S. section from all possible directions and routes.

 

Coding and response time
A real CTC machine has a single wire set out to the field installation. This time delay simulates the delay between when a code button is pressed, and a response from the field occurs. During this time, all of the indicators for the changed items (switch, signal) are "Out of correspondence".

 

Out of correspondence
The state of display indicators (either switch or signal) whereby a command by the CTC operator has been initiated by pressing the code button, and the CTC system is awaiting response(s) from the field. Also may be present for a long time if "running time" as relates to a signal change. This is indicated on the panel by all indicators for the changed system (switch, signal) being out until the response is received.

 

Time locking
See "Running time" definition.