The CATS 2.34 user guide is a PDF. It is included in the CATS release, but a link is included here.

1. Introduction

The Computer Automated Traffic System (CATS) is a versatile program for controlling a model railroad. It supports CTC, DTC, ABS, or APB disciplines over blocks of railroad. Because it is built on top of the JMRI model railroad interface, it can be used with different computer, DCC, and serial control systems.

CATS was originally written for Pat Lana’s N scale Cedar River and Iowa Central (Crandic) model railroad layout, but was generalized so that it can control turnouts and signals on most model railroads. Without the Crandic, this program would not exist. Without JMRI and the volunteers who have worked on it, this program would exist only for the Crandic.

CATS is the second program in a suite. It requires an XML description of the railroad, generated by the designer program, the first program in the suite. The designer is a graphics based program which allows the user to visualize the dispatcher panel presented by CATS and to associate DCC information with items on the layout (signals, turnouts, etc.). So, before CATS can do anything useful, it needs the XML description from designer.

The price paid for the versatility of CATS is that the user must also have the Java runtime environment (Sun’s jre), JMRI library, and jar files. So, you will need to download them before beginning. But this is a small price because the JMRI programs are useful in their own right for programming decoders, monitoring DCC, discovering sensor addresses, testing out things, and so on.

2. Setting Up

The Crandic RR uses seven files and all are placed in the same directory as the JMRI files

  • cats.bat is a command script to simplify running CATS under Windows.
  • cats.csh is a command script for running CATS under Linux or MacOS.
  • cats.jar is the dispatcher panel
  • compass.gif is a logo with arrows showing compass directions, for the Crandic
  • crandic.gif is a logo for the Crandic that appears on the main JMRI window
  • Crandic.xml is a description of the Crandic, controlled by CTC rules (if you try the Crandic dispatcher panel, be sure to set your JMRI connection preferences to Digitrax and Loconet Simulator)
  • designer.bat is a command script to simplify running the designer program under Windows XP.
  • designer.csh is a command script for running designer under Linux or MacOS.
  • designer.jar is the program used to describe the layout
  • Ops.xml is a layout file that shows how CATS and JMRI Operations exchange information. This uses the default contents of Operations. Be sure to set the JMRI preferences to Digitrax and Loconet simulator to run it. Also, be sure that Simple JMRI Server is enabled.
  • Shortcut to cats.bat is an example of a Windows shortcut for running cats from the desktop
  • Win7_designer.bat is a command script for running designer under Windows Vista or Windows 7.

The crandic.gif file should also be placed in the resources directory of the JMRI directory. If you do not want to run the Crandic, then only five files are needed, everything but the XML file and compass.gif. JMRI version 2 (or later) is needed to run CATS.

Under Windows, we made shortcuts to the .bat files and placed the shortcuts on the desktop.

CATS was created under Java 1.5.0_22. It should run under JRE 1.5 or 1.6

2.1 Starting CATS - Windows

The easiest way to launch CATS under Windows is to create a short cut to cats.bat and place the shortcut on your desktop. As explained in the troubleshooting section (8), it is also possible to bring up a command window, “cd” to the JMRI directory and just enter “cats”

2.2 Starting CATS - Macintosh

There are at least two ways to launch CATS on a Macintosh (OS X). One is to open a terminal window. In that window, navigate to where cats.csh is installed and execute it. Alternatively, you can download the Mac launcher and uncompress (unzip) it in the JMRI directory. This will create two icons. If you double click on the “CATS runtime” icon, you will launch CATS

2.3 Starting CATS – Linux

Since CATS requires graphics, you must install a windowing package (e.g. gnome or kde) on your computer. With the window manager running, you can open a terminal window. In that window, navigate to the JMRI directory, where you installed CATS. You can execute CATS from there (e,g, “./cats.csh”, “csh cats.csh”, etc). Your window manager may also allow you to create a shortcut that you can place on your desktop.

3 Getting Started

Assuming a layout description exists and that it contains all three of the layout, typical trains and jobs, CATS is most easily started by running an operating system dependent command script (see previous section). The command script has all the magic incantations to Java.

  1. Simply launch cats.bat (Windows) or cats.csh (Macintosh OS X or Linux) to start up CATS1.
  2. Several windows will pop up. All but one are part of JMRI, so the JMRI tool set is available while running the dispatcher panel.
  3. The last window created is a blank dispatcher panel. Use the File -> Open menu item to navigate to the XML description file and open it.
    If you look at File again, you will see that Open is grayed out and Start Recording is an option. If you select Start Recording, then the current train locations and crew assignments (as well as subsequent train movements and crew assignments) are stored in a file you select. These actions are time stamped to allow the session to be recreated. Thus, the file provides a record of the operating session. It is not intended that the record be used for grading the operators, but for being used in conjunction with multiple records for adjusting train schedules. See section 6 for details of the record log. See item 12 for other ways to use the session log.
  4. Under the Appearance menu are controls for changing the appearance of the screen (and layout).
    With these items, you can change colors, line widths, character sizes, and other things. So, if you don’t like the color of an item, select it and you will be greeted with a color selector through which you can choose a different color. You will have to resize the screen to make changes in the grid size and automatic wrapping take affect. Note that these changes apply only to this run of CATS. Permanent changes are made with designer and recorded in the XML file.

For lack of a better place to put them, Appearance contains several other menu items. There is a menu item (Test Layout) for running tests on the layout. It has an item for testing all signals on the layout, either have them set to the appropriate aspect for a common indication or a common aspect. There is another test item for throwing all turnouts (useful for initializing a layout to a known state) and for closing all turnouts. This is useful for synchronizing the positions of feedback turnouts with what CATS thinks they are. There is a test item for setting all the turnout lock lights. Another test exists for setting all “automatic” switches to their straight route. The last should be done before beginning operations. Though it checks for block occupancy before throwing a turnout, some cars may not trip the detector and this would move the turnout under them.

After running tests, you can select Refresh Layout and CATS will attempt to set all signals, lock lights, and turnouts to the condition shown on the screen.

If the screen looks funny (for example, the mouse cursor is not a pointer), you can select Refresh Screen and have the screen redrawn. With a change in version 2.11, the cursor should always be a pointer, but if it is not, click on Refresh Screen.

The Appearance menu also contains some items for debugging and tuning the layout control. Under Trace Items a checkbox exists for printing on the Java console signal changes when sent to the layout and for printing when the number of locks on a decoder changes. It also has an option for tracing the communications with JMRI Operations.

Under Appearance->Adjustments, Occupancy Debounce controls a “debounce” value that can be selected for occupancy reports. CATS will hold the occupancy report until it has been stable for the number of seconds desired; thus, filtering out “phantom” reports. Another item (Refresh Delay) selects a delay introduced after every message sent to the layout when doing a layout refresh. This delay is intended to prevent CATS from overwhelming the layout with messages. The final delay (Loconet Governor) is on the number of milliseconds seconds between commands sent to the Loconet operation . This allows the recipient device time to process one command before the next is sent.

The Engine Labels checkbox is used for selecting what the train labels on the panel show. If checked, then they are the lead engine number. If not checked, it is the train’s symbol.

Train Tracker is a menu item for enabling or disabling automatic train tracking. When train tracking is enabled, CATS will attempt to move a label when an occupancy detection is received. Thus, train labels move around the layout without dispatcher intervention. Train labels do not move automatically from detected tracks into undetected tracks because undetected tracks do not report occupancy. Train Tracker is an option because it works well when the detectors behave themselves and do not generate false reports. If the detectors are not well behaved, then it is best to disable automatic tracking.

Tee Base changes the base of signal light icons. When checked, the bases are drawn as an inverted “tee”. When unchecked (the default), the bases are drawn as triangles. Changing this option takes affect immediately, but you will need to refresh the screen.