JMRI is...

Adding signals to your layout with JMRI.

JMRI provides powerful tools for working with your layout.

JMRI can be used to automate parts of your layout, from simply controlling a crossing gate to running trains in the background.

JMRI: Signaling

This page introduces Signaling, lists the JMRI Signaling Tools and points to more advanced methods.

Modeling railroad signaling on a layout can be done in many different ways, ranging from simple "stoplights" to a complete emulation of a particular prototype's signaling rules. JMRI provides a combination of tools to implement Signaling. JMRI supports prototypical signaling based on signal Aspects and Appearances along with CTC dispatching and interlocking, without requiring the user to write any script or Java code.

Signaling Vocabulary
Prototype Railroad Signaling
JMRI Signaling Tools
Advanced Signaling

Signaling Vocabulary

Prototype Railroad Signaling terms:

Signal Head or Signal Arm Each individual signal unit on a lit or semaphore Signal Mast. It shows exactly one Appearance, generally a color (though not always, e.g. semaphores).
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.
Marker A Signal Head or Arm that does not change color or position.
Signal The object that conveys an Indication via a specific pattern of its visible parts. It can be as simple as a sign, saying "start CTC"; that conveys a particular indication and invokes a rule. Usually we're referring to lit or movable Signals, though, which can show more than one Indication. The Signal might have one light and use different colors to convey different Indications, or it needs more than one set of lights to display a wider range of Aspects to fit the location.
Signal Mast The pole that mounts one or more Signal Heads or Arms and (usually) controls one individual track. Also used to refer to an entire signal made up of one or more Signal Heads. Dwarf Signals are also considered Signal Masts.
Appearance One of a series of allowed options for a Signal Head or Signal Arm, e.g. Red, Green, Raised.
Aspect One of a series of allowed options for the visual pattern of a Signal Mast using one or more Signal Heads or Arms to convey a speed or route Indication. Different Signal Mast types can use different Aspects for a specific Indication, but a particular Signal Mast type always conveys a particular Indication via just one Aspect. For example, to convey "You can run at full speed" - an Indication (Rule 281, "Clear") - one signal might display a single green light, another might show a green over red, and a third might have an upward semaphore. Those are all different Aspects showing the same Indication. As all these different Aspects are assigned the same descriptive name, e.g. "Approach", when you think of these Aspects as "Approach on a triple searchlight signal" and "Approach on a single semaphore" and the difference is evident.
Indication On (most) western US railroads, "Indication" refers to the message that a Signal is sending. It generally has a name, like "Clear" or "Approach", but officially it's a railroad Rule (like 281 or 285) that the train must obey when governed by that Signal. So Indication is the meaning a signal conveys to the engineer, say the full instruction for a signal Aspect, e.g. "Proceed preparing to stop at next signal. Train exceeding medium speed must at once reduce to that speed." (for the "Approach" Aspect according to the AAR 1946 Rule Book).
Distant Signal The signal you are controlling is called a Distant Signal if it is programmed to show the same or a more restrictive Aspect as the next signal in the direction and route of travel.
Dark Territory Section of running track not controlled by signals. Dark Territory is governed by other methods like Timetable and Train Order (TT & TO) Operation, Direct Traffic Control or Track Warrants.

Different railroads have different Rules to operate rail traffic, using different terms. In their respective Rule Books, they use different Aspects for rules of the same name. And some will have different Appearances to make up those Aspects (e.g. semaphore vs. single lamps vs. color-position signals vs. position light signals vs. cab signals vs ...)
Picture on the right: a CSX Searchlight Signal Mast with 2 Signal Heads, showing a "red over red" Aspect, meaning the "Stop" Indication.

JMRI specific Signaling terms:

Virtual Virtual signals are JMRI internal signals with no actual hardware attached. Virtual Signals may represent theoretical Aspects at buffer stops or in staging that are used by prior signals.
Protected Sensor The next block occupancy 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.
Signaling System A set of icons, definition files and rules following either a prototype Rule Book or a simplified set of rules (see this list).
System Name The name of a JMRI object identifying either a virtual (Internal) or physical piece of hardware being used, e.g. an output on a decoder to control a signal. The System Name must follow certain Naming Rules to be correctly interpreted bij JMRI, and the name will vary depending on your hardware so it must match your DCC system.

Prototype Railroad Signaling

Across the world railroads have developed a wide range of signaling hardware such as Flags (not supported in JMRI), Semaphores, Position Light Signals and Color Light Signals. Different physical signals may show the same "Indication" using different combinations of lights, semaphore positions, and/or placards; these patterns of lights are called "Aspects". For example, the "Stop" Aspect will be a single red light on a signal mast with only one lamp, red over red lamps for a signal mast with two lamps, etc. To learn the rules of the railroad you model is part of the hobby but JMRI helps by providing more than 20 prototypical signaling systems from different countries to choose from. Still, it's up to the engineer to interpret the Signal Aspects displayed and adjust the throttle...

Much of basic Automatic Block Signaling (ABS) 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 simplification, it can serve as a good starting point for understanding signaling logic. More modern signaling systems are Absolute Permissive Block (APB) signaling used by many western US railroads and Centralized Traffic Control (CTC) remotely operated from large switchboards.

Standard CTC nomenclature

Union Switch & Signal Company (US&S)

Signals are identified by EVEN numbers with movement direction as depicted on the panel (R - right, L - left)
Switches are identified as ODD numbers

Example #1: Signals at a controlled switch with single track approaching from the left to two tracks moving to right - 2R (facing point), 2L (main route), 2LA (diverging route). 2LA would be shown as 2L on the panel to correspond with Signal Lever 2. Cardinal directions might also be used (N, S, E, W) at a diamond for the opposing route. Switches are N (normal) or R (reverse).
Example #2: Dennis Drury's CTC signals get even numbers with a directional modifier such as E 50 W or E 52 W. The intermediate block signals may be numbered based on milepost locations such as 322.2 and 322.3.

General Railroad Signal (GRS)

Signals get ODD numbers
Switches get EVEN numbers (as opposed to US&S!)
Same R - right, L - left scheme, though

Thanks to Jim Duncan, who adds: There are always exceptions! Any labeling must be consistent, easy to understand, and have absolutely no possibility of being confused with any other signal, switch or lever.

JMRI Signaling Tools

It is really straight forward to use Aspect Signaling, especially if suitable signal hardware is already configured in JMRI or you want to use Signal Masts with more than one Signal Head. Aspect Signaling in JMRI uses of a series of Aspect definition files that come with JMRI since version 2.9. In addition to tapping into one of the more than 20 prototypical Signaling Systems that come with JMRI, you can tweak one to suit your hardware and operations or define your own and share it as part of a next version of JMRI.
JMRI provides the following core Signaling Tools, available from the Tools > Tables > Signals > menu:

1. Signal Head objects represent the individual lights of a signal and can be created, changed, deleted and set to specific Appearances (colors) in the Signal Head Table. One or more Signal Heads usually are part of a Signal Mast. For signaling decoders that directly support multiple Aspects, it may not be necessary to create individual Signal Heads before creating Signal Mast objects.

2. Signal Mast objects represent an entire signal with one or more Signal Heads. Using Signal Mast objects allows you to display prototypical Aspects on signals. You specify what kind of Signaling System is to be used, the specific Signal Mast type e.g. "double searchlight" or "single head dwarf" and which Signal Heads or aspect aware signal hardware this Signal Mast is going to drive. When the Aspect of a Signal Mast is set to e.g. "Approach medium", JMRI handles the layout communication needed to make the signal on the layout display the right colors.
Signal Masts are configured through the Signal Mast Table. From the Signal Mast Table, you can create and edit Signal Masts and set individual Signal Masts to any Aspect that they're able to display by clicking in the "Aspect" column.
You can add a Signal Mast icon in the Panel Editor in the usual way. The Signal Mast icon will display the images from the Appearance definition for that particular Signal Mast type and Signal System.

3. Signal Groups are used to define a number of Signal Heads, where only one Signal Head can be illuminated at any given time, depending upon the Appearance (Status) of the associated Signal Mast and a set of conditions.
Signal Groups would be used where additional indicators are installed to support the main Signal Mast, such as Junction, Route or Speed displays. These indicators provide additional information to the driver (US: engineer) that is not given by the main Signal Mast. Such indicators are frequently seen in European and UK signalling.

4. The Signal Mast Logic tool allows the Signaling Logic to be built up as pairs of conditionals between Signal Masts on the layout. Each Signal Mast Logic will use the states of Blocks, Turnouts, Sensors and other Signal Masts to determine what Aspect a particular Signal Mast should be displaying.
If the layout has been drawn up using the Layout Editor and Signal Masts have been placed on the panel using the various tools, then it is possible for all the Signal Mast Logic to be dynamically built, with little user intervention. For panels created with Control Panel Editor some of this information is to be entered manually.

All the information in the Tables 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 help page.

What's next?

More information on Aspect Signaling and the available options in JMRI can be found on the Aspect Signaling help page.
Suzie Tall and Jim Duncan wrote Signaling Quickstart instructions.
Elmer McKay provided a general overview How to get started with signals on your layout.

Advanced Signaling

Interlocking Entry/Exit
Logix: basic logic for controlling parts of the layout
Scripting: customize JMRI including user interaction
Automation Classes
Toolkit for experienced users to do any kind of automation on a layout by writing a new program

Signaling with Logix

A JMRI Logix provides logic and control capabilities for JMRI objects, including Signal Heads and Masts. Logix can be used to configure custom signaling logic by filling out forms, without writing any code. A user defines "Conditional" logic and the "Actions" that take place depending on the state of the logic. The following sub-sections show how Logix can examine and control Signals.

Signal State Variables in Logix

State variables related to Signal Heads and Masts 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 Mast, 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. Note: Not all Logix conditionals are listed here.

Conditionals for Variable Type "Signal Head":

Signal Head Appearance Equals: Evaluates to True if the Appearance of the specified Signal Head equals the Appearance specified in the 'State' variable. Calculation is triggered when the Appearance of the Signal Head changes.
Signal Head Lit: Evaluates to True if the specified Signal Head is lit.
Signal Head Held: Evaluates to True if the specified Signal Head is being held.

Conditionals for Variable Type "Signal Mast":

Signal Mast Aspect Equals: Evaluates to True if the Aspect of the specified Signal Mast equals the Aspect specified in the 'State' variable. Calculation is triggered when the Aspect of the Signal Mast changes.
Signal Mast Lit: Evaluates to True if the specified Signal Mast is lit.
Signal Mast Held: Evaluates to True if the specified Signal Mast is being held.

Signal Actions in Logix

Actions related to Signals Heads and Masts currently available for use in Logix Conditionals are listed below along with information on each. Note: Not all Logix actions are included here.

Set Signal Head 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 that appears after you enter a Signal Head System Name (or drag it from one of the Pick Lists).
Set Signal Head Held: Sets the specified Signal Head to Hold. Specify the Signal Head to hold by entering its System Name or User Name.
Clear Signal Head Held: Clears the Hold on the specified Signal Head. Specify the Signal Head by entering its System Name or User Name.
Set Signal Head Dark: Sets the specified Signal Head to Not lit. Specify the Signal Head by entering its System Name or User Name.
Set Signal Head Lit: Sets the specified Signal Head to Lit. Specify the Signal Head by entering its System Name or User Name.
Set Signal Mast Aspect: Sets the specified Signal Mast to the chosen Aspect. Specify the Signal Mast to set by entering its System Name or User Name. Specify the Aspect to set by choosing from the popup menu.
Set Signal Mast Held: Sets the specified Signal Mast to hold. Specify the Signal Mast to hold by entering its System Name or User Name.
Clear Signal Mast Held: Clears the Hold on the specified Signal Mast. Specify the Signal Mast by entering its System Name or User Name.
Set Signal Mast Dark: Sets the specified Signal Mast to Not lit. Specify the Signal Mast by entering its System Name or User Name.
Clear Signal Mast Dark: Sets the specified Signal Mast to Lit. Specify the Signal Mast 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.

For more information see the Logix help pages.

Scripting

Just like other objects in JMRI you can set and read Signal Heads, Signal Masts and Signal Mast Logic via Scripts. Instead of defining our own language to accomplish this, JMRI Scripting uses the "Python" language that's commonly used in web development.
Several methods from the jmri_default.py file can be used to work with signaling. Methods that may be used in a Python script to interact with Signal Masts include: getAspect(), getSignalSystem(), getValidAspects() and setAspect(Stop). See these Examples.
To script a Signal Head the 'getSignalHead' method can be used. Then, 'setAppearance' is a method of the returned SignalHead object. Example:

signals.getSignalHead("IH1").setAppearance(YELLOW)

SigletExample.py
An example script for a JMRI "Siglet" in Python. It listens for changes to two Sensors and a Turnout, and then recalculates a Signal Head Appearance based on the values.

For more information see the JMRI Scripting help page.

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 and make it easy to code your own signal logic into the program; see the Automation page. The "Siglet" class and it's kin are meant to make it easy to write complex custom signal logic; a variant of these was used by Nick Kulp's for signaling automation on his Cornwall Railroad.

Although Automation Classes require writing code instead of just filling out a GUI form, JMRI 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 develop new tools, controlling every detail. Programming with the JMRI Toolkit 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.

Legacy tools

The JMRI Simple Signal Logic tool provided the first basic version of ABS and Interlocking signaling using single head Signal Masts. The Simple Signal Logic (SSL) Tool is still available in the Tools menu. However, to prevent logic conflicts and strange Signal Aspects, do not attempt to combine the use of the SSL Tool and the newer Signal Mast Logic tools for the same signals.

Signaling

Tools

Layout Automation