CATS Beta Release Notes

This document is a set of release notes for the first beta (test) version of CATS, leading to version 3. It contains discriptions of

  1. What is new from CATS 2.43.
  2. Requirments for running this test release.
  3. What is in this test release.
  4. How to download and unzip the contents.
  5. How to install the test release.
  6. Known bugs and issues.

Please read these notes before downloading and installing this CATS beta release.

This is a test release (beta) of CATS leading to version 3. Version 3 is a major rewrite of version 2 (the previous version) of CATS. It contains a lot of new and modified code; thus, is not as robust or error-free as version 2. This is being released as a test version so that it can be exercised and the bugs discovered and corrected. If your interest is in solid, well known behavior, then download and install CATS release package 2046. However, if you are willing to tolerate problems in an effort to uncover the causes and try the new features, then download and install the beta version.

What is New

Both the designer and CATS applications have been heavily modified, CATS more so than designer.


Most of the changes to designer involve adding check boxes, pop-ups, and entry fields for configuring the new features in CATS. However, there are several new features.
  1. Better suppport for JMRI device usernames. With the exception of Signal Heads, in version 2, JMRI system names (connection prefix + address) were required for defining JMRI devices to CATS. With this release, a user name + device type are sufficient to completely define a device. This change decouples CATS more from JMRI.
  2. Addition of an UNDEFINED speed for things like unbonded track and yards, to block route propagation.
  3. Creation and editing of buttons.
  4. Signal templates
  5. Device tables
  6. Track coloring by speed.
For details, on the changes and what they mean, refer to the designer user manual.

In general, the beta version of CATS can use older XML files; however, some things (particularly signal aspects protecting end of track) will look different. Version 2 of CATS protected end of track (no next signal) with an Approach (typically yellow aspect) indication. The beta version protects end of track with a Restricting (typically flashing red or lunar) indication. Furthermore, the indications on the signals in approach change from Clear, Advance Approach, and Stop to Clear, Advance Approach, Approach, and Stop. Signal templates are likely the area most affected by upgrading from version 2 to the beta, closely followed by adding restricting colors to Signal Head definitions.

Layout files created or modified by this version of designer are not backwards compatible. They cannot be used with version 2 of designer or CATS.


CATS had extensive rewrite, so has many undiscovered bugs. Here are some of the major changes.
  1. Change in end of track protection (see above).
  2. Read back of JMRI devices at startup or on demand.
  3. Simulated code line for a more prototypical experience.
  4. Ability to run time when a signal is knocked down.
  5. Call on (return to train).
  6. Route creation by specifying the entry and exit signals.
  7. Route stacking.


designer needs only Java 8, a jdom2 jar file, and a log4j2 jar file. It will run with Java 11.

The beta CATS will run with any of the following configurations:

  1. Java 8 plus JMRI 4.24 through JMRI 4.26
  2. Java 11 plus JMRI 4.24 through 4.26 or JMRI 5.0

Package Contents

The beta files are packaged as a zip file. It contains
  1. cats.jar beta application
  2. designer.jar beta application
  3. application launchers for both designer and CATS for Windows, MacOS, and Linux
  4. user manuals for designer and CATS in .doc and .pdf formats
  5. libraries for designer
  6. crandic.gif for CATS
  7. demonstration layout files for one of John Armstrong's layouts
  8. a folder of Operations files for the demonstration layouts
  9. image files to be used with shortcuts

Download and Contents Extraction

Begin by downloading the file. The exact keystrokes for donig this depend on your browser. Very important - remember where it was downloaded.

Looking ahead a little, the designer application can run anywhere that your operating system allows programs to run. The CATS applicaton needs several files to be placed with the JMRI application. Often it is easiest to create the folder for all but the CATS application before extracting the file. This is the time to decide where the beta files will live and move the file there.

The .zip format is a well known and popular scheme for combining multipls files into one and compressing the results. There are many program that understand how to extract the contents of a .zip file. Most operating systems provide at least one with the standard installation. So, barring using a specialty extractor (e.g. 7zip, Winzip, etc.), navaigate to the location of, right click on the file, and a menu should pop up, with an entry for "extract" or extract all". Select that entry. There could be more pop up as to where to extract all. People typically select "here", where resides.

After the extraction process completes, there should be two new folders (named lib and Operations) and 19 other files. The user documents contain information on installing the applications, as well.


This section discusses installing the applications.


The designer application can run from almost anywhere, as long as its two required libraries reside in a folder named lib, in the same folder as the designer launcher (designer.bat or designer.csh) and designer.jar.

Depending upon the operating system, it may be necessary to make the launcher executable before it will run. It should also be possible to create a desk top shortcut to the launcher at this time. If given the option, tell the shortcut to "start" here, the folder containing the launcher.

If you are upgrading, only the designer.jar file needs to be replaced in your old installation.


Three files must be copied from the extraction folder to the JMRI program folder. Typically the JMRI program folder resides in

The three files to copy from the extraction folder to the JMRI program folder are:

As with designer, it may be necessary to make the launcher executable. It is a also possible to create a desktop shortcut to the launcher; however, the shortcut should "start" in the JMRI folder.

If performing an upgrade, then only the cats.jar file need be replaced. One word of warning is in order. The CATS launcher under Windows collects all the library (.jar) files before telling Java to run. Renaming the old cats.jar may not be good enough to install the new one. The best procedure is to move the existing cats.jar out of the JMRI folder before putting the new one in.

Bugs and Issues

This final section lists known bugs and any work arounds. If a bug has been fixed, it will remain on the list, but italicized.


  1. changes to table entries (paricularly signals) may appear to have been dropped after accepting changes, but were actually accepted as determined by looking at the values through point and click or restarting designer.


  1. forcing occupancy of undetectde, ABS track does not change track color
  2. recognizing mouse clicks over signals needs to be more reliable
  3. something is not getting cleared under unidentified conditions, that prevents route creation. Need details on how to duplicate.
  4. the signal icon is not always colored correctly. Need details on how to duplicate.
  5. add buttons to tables
  6. setting initial refresh (JMRI device read back) on start up often (not always) locks up CATS/JMRI