JMRI: Simple Signal Logic Documentation

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
Introduction to SSL
SSL
Getting Started

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: A distant signal 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 Head Table: The list of signals in JMRI. Signals must first be added into the Signal Head Table before they may be included in a SSL entry or Logix.
Triple Output: 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 commands be sent.
Double Output: 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 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 Head Table

All the signals that JMRI knows about can be referenced using the "Signal Head Table" tool in the Tools menu of most JMRI programs. There are eight 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 table in the "State" column. You can also click on the appearance button to cycle through the available appearances: red, yellow, green, flashing red, flashing yellow, flashing green, and dark.
The "Comment" column is for your use to record any comment you may want to help keep track of your signal heads. It is for information only.
Click the "Delete" button in a specific row to delete the signal head. Remember to remove any signal head icons associated with this signal head and all references to this signal head. Use this button with caution!
The check box in the "Lit" column lets you control whether the signal head on the layout is lit (checked) or stays dark (unchecked).
The check box in the "Held" column shows the "held" property of the signal, and allows you to change it. This property is used by e.g. CTC machine logic 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".
Click the "Edit" button in a row to view or change optional information for a signal head. Notes: System name and type cannot be changed. Only one signal head may be edited at a time.

To define a new signal, click on the Add... button. It will prompt you for the signal type (Triple Output; Double Output; 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.

Introduction to SSL

SSL is a JMRI tool to enable the rapid setup of basic ABS style signaling. For more complex operations beyond the capability of SSL refer to the section on Logix. 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.

Simple Signal Logic

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. Enter either the user name or system name of the signal you'd like to control, and hit return or enter. The rest of the fields will be filled in with any control information that's already present.
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.

Getting Started

Follow the following steps to create a signal and become familiar with how the SSL user interface works. This example defines a "virtual" signal head that doesn't really exist on the layout, so it can work with any kind of layout hardware. See the page on signals for information on how to set up your real signals.

Select Signal Head Table in the Tools menu.
In the Signal Head Table window that appears, click Add to begin defining a new signal head.
In the Add New Signal window that appears choose the "Virtual Signal" type.
Enter a system name such as IH1000.
Click OK to enter this head into the Signal Head Table.
Enter all the signal heads that you will be using for this test, using different names. The actual name doesn't matter, they just have to be different.
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.