JMRI: Signaling

Modeling railroad signaling on a layout can be done many different ways, ranging from "stoplights" to complete emulation of a particular prototype's signaling logic.

JMRI provides several different things that can help with this:

The JMRI "Signal Table" tool lets you control the appearance of individual signals on your layout. This can be useful for debugging, for example.
The JMRI "Simple Signal Logic" tool can provide simple versions of block and interlocking signaling.
The JMRI "Logix" tools are basic logical building blocks for controlling parts of the layout. They can be used to configure custom signaling logic by filling out forms, without writing any code.
The JMRI Automation classes makes it easy to code your own signal logic into the program. This is how Nick Kulp's Cornwall Railroad was signalled.
JMRI scripting provides a comprehensive programming capability.
JMRI provides a complete toolkit to make it easy to do any kind of automation on your layout by writing a new program of your own.

There's more information on each of these below. As you move down that list, the task becomes more and more technical, but you have more freedom to model exactly what you want.

In addition, there are people working on more advanced signaling logic within the JMRI project. Although it's too early to talk in detail, the idea is to provide ways of driving semi-prototypical signaling logic, including CTC dispatching and interlocking, without requiring the user to write any Java code. The jmriusers discussion group will have more info on this as it becomes available.

The documentation below describes Signaling with JMRI, and discusses how to set up the basic signal situations. The documentation is divided into sections; click below for easy access to a listed section. If you prefer to try before reading much, read Introduction to SSL, then click Getting Started and follow those instructions. Return here to read about what you did.

Basic Vocabulary
The Signal Table
Introduction to Simple Signal Logic Tools
Getting Started with Simple Signal Logic
Introduction to Logix Use
Available Logix State Variables
Available Logix Actions
The Automation Classes

Vocabulary

Some basic signal terms:

Signal Arm or Signal Head Each individual signal unit.
Aspect The speed or route indication given by one or more signal heads or arms.
Marker A signal head or arm that does not change color or position.
Light The individual lamp in a signal. A light may indicate multiple aspects if it changes color like in a searchlight signal, or it may take multiple lights to indicate a single aspect, for example in position light signals.
Mast The pole that mounts one or more signal arms that (usually) control each individual track.
Distant Signal The signal you are controlling shows the same or more restrictive aspect as the next signal in the direction and route of travel.

Some JMRI specific SSL and Signal terms:

Signal Table The list of signals in JMRI. Signals must first be added into the Signal Table before they may be included in a SSL entry or Logix.
Triple Turnout A signal head that has each aspect of the signal directly driven from an individual output (called a turnout) line. Each aspect change requires that three turnout commands be sent.
Double Turnout A signal head that uses just two output lines to indicate 4 signal aspects. Usually these aspects will be Clear, Approach, Stop, and Dark. The output coding is such that one turnout thrown (on) controls the stop and the other thrown (on) controls the clear. Both outputs thrown (on) controls the approach, and both closed (off) are dark. Each aspect change requires that two turnout commands be sent.
SE8c A signal head controlled by a single turnout command per aspect change. One turnout command changes between stop and clear, and the second turnout command changes between approach and dark.
Virtual Virtual signals are JMRI internal signals with no actual hardware attached. Before the advent of Logix, Virtual Signals were required to solve more complex operations than can be done with with a single SSL alone.
Protected Sensor The next block sensor/s following the signal you are controlling in the direction and route of travel. The "protection" is to prevent a train from entering an occupied block without warning.
Protected Signal The next signal after the one you are controlling in the direction and route of travel. The "protection" is to prevent a train from approaching a stop signal without sufficient warning to allow it to be stopped short of reaching the "protected" signal.
System Name The internal JMRI representation for the actual hardware being used to control the signal. This will vary depending on your hardware, and must match your system.

Signal Table

All the signals that JMRI knows about can be referenced using the "Signal Table" tool in the Tools menu of most JMRI programs. There are five columns in the table:

The system name is assigned to the signal when it's created, and can't be changed.
If you're interested in having your signals carry "human readable" names, you can click in the User Name column and change that information to whatever you want.
As the signal changes, for whatever reason, the current appearance will show in the State column of the table. You can also click on the appearance button to cycle through the avilable appearances: red, yellow, green, flashing red, flashing yellow, flashing green, and dark. The system hardware will follow these changes.
The check box in the Lit column lets you see whether the signal head on the layout is lit (checked) or stays dark (unchecked). This may also be controlled automatically with the SSL "approach" lighting option or from Logix. Note: This only affects the actual layout hardware, not any panel indications nor signal state logic.
The check box in the Held column shows the "held" property of the signal, and allows you to change it. This property may be used by CTC machine logic or Logix to say "Don't change this signal head from red, even if it would be safe to do so, because I want to hold a train here".

To define a new signal, click on the Add New Signal button. It will prompt you for the signal type (controlled by turnout outputs; SE8c; etc), and whatever setup information is needed for your choice.

This information is saved with the configuration in an XML file, along with control panel setup, Logix, Routes, and similar stuff. For more information on creating and displaying panels, including how to show signals on your panels, please see the Panels pages and the pages on the Cornwall Railroad control panel.

Introduction to Simple Signal Logic

Simple Signal Logic (SSL) is a JMRI tool to enable the rapid setup of basic ABS style signaling. The SSL user interface is designed to be user friendly to all users with basic familiarity with JMRI. SSL provides a means for setting up basic signals in an intuitive manner, without the user having to be familiar with all of the logic necessary to account for the different aspects. For more complex operations beyond the capability of SSL refer to the section on Logix.

Much of basic ABS signaling can be boiled down to "a signal goes red when a train can't safely enter the block it protects; it goes yellow when the block following the protected block can't be entered". Although that's a simplication, it can serve as a powerful starting point for understanding signaling logic.

The Simple Signal Logic tool allows you to configure JMRI to use this basic ABS type of logic to set the appearance of a signal. Using the panel, you enter information on:

Signal Named The signal being driven.
Protects Sensor/s Which sensors (occupancy detectors) cover the block immediately past the signal. When any of these sensors show "active" the signal will be set to red.
Red When Turnout If the block contains a turnout, configure the turnout name and use the selection button to choose whether you're entering the closed or thrown leg. The signal will be set to red whenever the turnout is set against this track.
Protects Signal The next signal that the train will reach; this signal will be set yellow if the next signal is red.
With Flashing Yellow If the checkbox is checked, the signal will be set flashing yellow (JMRI will alternate between dark and yellow) if the next protected signal is yellow, thereby giving four-block signaling.
Limited Speed If the checkbox is checked, this signal will be set to yellow as the least restrictive aspect.
Is Distant Signal If the checkbox is checked, this signal will be set to the most restrictive aspect of this signal or the next protected signal.
Approach Lighting Sensor The sensor that controls the lighting of this signal. Only the actual hardware signal will go dark. Panel indicators will show the normal signal aspect. Leave this entry blank to always show lit.
Facing Point Turnout The signal located on the single track line, facing a choice of two or more tracks in the direction of travel.
Trailing Point Turnout The signals located on the double track line, facing a single track in the direction of travel.

The case of a facing point turnout which leads to two different "Protected Signals" is also covered although the above figure doesn't show it. If a single signal head is used to control both branches, then choose "On Facing-Point Turnout". If a different head will control each route, then simply choose "Main" or "Diverging" leg of turnout, as required for each one.

Pause your mouse over any entry or item in the SSL creation window for a brief "tooltip" help reminder.

It's clear that this won't cover complicated interlockings nor will it cover the speed-signaling seen on some prototypes. For those situations use a combination of Logix and Routes. Logix cover the conditions, and Routes control the actions to be taken.

However, when combined with the logic capabilities of JMRI Routes and Logix units, SSL can be used to create a CTC panel, as Bob Bucklew shows on his web site.

Getting Started with Simple Signal Logic

Follow the following steps to create a signal and become familiar with how the SSL user interface works.

Select Turnout Table in the Tools menu.
Check to be sure that the output lines (turnouts) that will control your signal are in the table. If not, click the Add button at the bottom of the Turnout Table.
In the Add New Turnout window that appears, enter a system name, (E.g. LT1) and "test" for user name, then click OK. Note: System names must start with CT, IT, LT, NT, XT, etc. and be followed by the actual hardware number of the turnout.
Clicking on the correct Closed/Thrown entries in the Turnout Table should now cause your signal to change.
Next select Signal Table in the Tools menu.
In the Signal Table window that appears, click Add to begin defining a new signal head.
In the Add New Signal window that appears choose the correct signal type to match your hardware. The required item boxes will appear.
Enter a system name. For example LH152. Note: System names must start with CH, IH, LH, NH, XH, etc. and be followed by the number of this head.
Next enter one or more turnout numbers that will control this signal. Note: In the case of SE8c style signals just enter the first turnout number of each pair. The second is automatically known.
Click OK to enter this head into the Signal Table.
Enter all the signal heads that you will be using for this test.
Now select Simple Signal Logic in the Tools menu.
Fill in the various entries to match your signals requirements as previously shown in the SSL section.
Click Apply to make this entry active.
Be sure to save your work.

You have just created an SSL entry to control a signal head. It's as simple as that. It took you more time to read this tutorial than to create the SSL entry.

A worked-out example is also available.

Signal Support in Logix

A JMRI Logix provides logic and control capabilities for JMRI objects, including signals. A user defines "Conditional" logic and the "Actions" that take place depending on the state of the logic. The following sub-sections talk about how Logix can examine and control signals.

Available Signal State Variables in Logix

State variables related to signals that are currently available for use in Logix Conditionals are listed below, along with information on each. State variables must always evaluate to either true or false. The condition resulting in true is given for each. If the condition is not met, the state variable evaluates to false. When a Logix is active, the states of entities (sensor, turnout, signal red, etc.) specified in state variables in its Conditionals are monitored. A calculation of all Conditionals in the Logix is triggered when any monitored state changes as noted below (if not obvious). Note: Not all possible Logix conditionals are listed here.

Signal Red: Evaluates to true if the appearance of the specified signal head is red. Calculation is triggered when the appearance change to or from red.
Signal Yellow: Evaluates to true if the appearance of the specified signal head is yellow. Calculation is triggered when the appearance change to or from yellow.
Signal Green: Evaluates to true if the appearance of the specified signal head is green. Calculation is triggered when the appearance change to or from green.
Signal Dark: Evaluates to true if the appearance of the specified signal head is dark. Calculation is triggered when the appearance change to or from dark.
Signal Flashing Red: Evaluates to true if the appearance of the specified signal head is flashing red. Calculation is triggered when the appearance change to or from flashing red.
Signal Flashing Yellow: Evaluates to true if the appearance of the specified signal head is flashing yellow. Calculation is triggered when the appearance change to or from flashing yellow.
Signal Flashing Green: Evaluates to true if the appearance of the specified signal head is flashing green. Calculation is triggered when the appearance change to or from flashing green.
Signal Lit: Evaluates to true if the specified signal head is lit.
Signal Held: Evaluates to true if the specified signal head is being held.

Available Signal Actions in Logix

Actions related to signals that are currently available for use in Logix Conditionals are listed below along with information on each. Note: Not all possible Logix actions are included here.

Set Signal Appearance: Sets the specified signal head to the chosen appearance. Specify the signal head to set by entering its system name or user name. Specify the appearance to set by choosing from the popup menu.
Set Signal Held: Sets the specified signal head to hold. Specify the signal head to hold by entering its system name or user name.
Clear Signal Held: Clears the hold on the specified signal head. Specify the signal head by entering its system name or user name.
Set Signal Dark: Sets the specified signal head to not lit. Specify the signal head by entering its system name or user name.
Set Signal Lit: Sets the specified signal head to lit. Specify the signal head by entering its system name or user name.
Play Sound File: Plays the specified sound file. (for example CTC relay clicks)
Run Script: Starts the specified script.

Automation classes

JMRI provides classes to help you write Java code to control your layout. The most powerful of these are aimed at general automation; see the automation web page. The "Siglet" class and it's kin are meant to make it easy to write signal logic; a varient of these was used for the Cornwall Railroad.

Although these require writing code, instead of just filling out a GUI form, the program handles all of the details of reading status changes from the layout, writing desired aspect changes back to the layout, and even the details of "which outputs do I have to set to get signal Apple Siding East to show yellow?". You can concentrate on just the signal logic in the code you write.

Toolkit

The entire JMRI toolkit is available for use if you really want to do something in detail. JMRI provides control of most DCC and C/MRI systems, with useful tools for manipulating turnouts, sensors, signals, locomotives, etc as well as powerful tools for working on the user screen.