JMRI: SignalingModeling railroad signaling on a layout can be done many different ways, ranging from "stoplights" to complete emulation of a particular prototype's signaling logic.
Elmer McKay has provided a very nice discussion of how to get started with signals on your layout.
JMRI provides several different things that can help with this:
- The JMRI "Signal Head Table" tool lets you control the appearance of individual signal heads 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.
- JMRI scripting provides a comprehensive programming capability for controlling signals exactly as you'd like.
- 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 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
capabilities within the JMRI project.
Although it's too early to talk
in detail, the idea is to provide ways of driving
prototypical signaling based on aspects and appearances
along with CTC dispatching and interlocking,
without requiring the user to write any scripting or Java code.
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 Head 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
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, also used to refer to an entire signal made up of one or more heads.
- 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 Head Table The list of signal heads in JMRI. Signal heads must first be added into the Signal Head Table before they may be included in a SSL entry or Logix.
- Triple Output Head A signal head that has each aspect of the signal directly driven from an individual output line. The individual output lines are controlled by JMRI Turnout logic, and are controlled via the Turnout Table. Each aspect change requires that three turnout commands be sent.
- Double Output Head 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 lines are controlled by JMRI Turnout logic, and are controlled via the Turnout Table. 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.
- Single Output Head A signal head that uses just one output line to indicate upto 3 appearances (including flashing). The appearances available to configure are Dark, Red, Yellow, Green and Lunar. The output lines are controlled by JMRI Turnout logic, and are controlled via the Turnout Table. The output coding is such that With the turnout thrown (on) controls one appearance and turnout closed (off) controls the other. Flashing allows for a third appearance, which will flash between the two appearances configured.
- 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 TableAll the signal heads that JMRI knows about can be referenced using the "Signal Head 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 head when it's created, and can't be changed.
- If you're interested in having your signal heads carry "human readable" names, you can click in the User Name column and change that information to whatever you want.
- As the signal head 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. (Some signal heads can also do lunar and flashing lunar) 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 head, click on the Add New Signal Head button. It will prompt you for the signal head 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 signal heads
on your panels, please see the
Panels help page
and the web 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 signaling 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
Much of basic ABS signaling can be boiled down to "a signal head 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 head. Using the panel, you enter information on:
- Signal Head Named The signal hread 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 head 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 head will be set to red whenever the turnout is set against this track.
- Protects Signal The next signal head that the train will reach; this signal head will be set yellow if the next signal head is red.
- With Flashing Yellow If the checkbox is checked, the signal head will be set flashing yellow (JMRI will alternate between dark and yellow) if the next protected signal head is yellow, thereby giving four-block signaling.
- Limited Speed If the checkbox is checked, this signal head 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 head or the next protected signal head.
- Approach Lighting Sensor The sensor that controls the lighting of this signal head. Only the actual hardware signal head will go dark. Panel indicators will show the normal signal appearance. Leave this entry blank to always show lit.
- Facing Point Turnout The signal head is located on the single track line, facing a choice of two or more tracks in the direction of travel.
- Trailing Point Turnout The signal head is 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 Signal Heads" 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
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 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 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 Head 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.
is also available.
Signal Support in 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 classesJMRI 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.
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.
For more information on signalingThere are a lot of excellent sources of information on prototype signaling.
- John Armstrong's book "The Railroad: What It Is, What It Does"
- Dr. Bruce Chubb's C/MRI User Manual rev 3.0 has signaling information in chapter 12. See particularly 12-11 on page 12-27.