Controlling model signals in a prototypical manner
Protoypical signal systems present "Aspects" to the engineer to tell him how to run his train. The
"Stop" aspect, for example, is pretty simple: "Stop the train". The "Approach medium" aspect
indicates something more complicated: "Proceed approaching next signal at medium speed". Each
aspect has an associated "indication", which is usually codified in a railroad's Rule Book.
The picture to the right shows an example, Rule 282 from the 1946 AAR rule book (Aspect: Approach Medium).
A collection of plain instructions let you set up Signaling in 7 Quick Steps.
Aspect Signaling is supported in JMRI using three of the Signaling Tools:
Signal Masts are configured through
the Signal Mast
Table. You add new ones with the "Add..." button below the table, which takes you to
the "Add Signal
Mast" window. There you specify what kind of signaling system is to be used (see
the list below), the specific signal type eg. "double searchlight"
or "double head dwarf" and which Signal Heads this Mast is going to drive.
Signal Head objects in JMRI are not aware of their position on a mast and the Signaling System they are part of, so as individual objects they can't show Signal Aspects. Individually they can only be set to specific Appearances (colors), either from the Signal Head Table or via Logix.
In short, a set of files for the selected Signaling System contains the basic code to
determine which combinations are available in the Signal Mast
Logic tool.
In the xml/signals directory located in the JMRI program directory, there is a directory for
every Signaling System that has been defined, with one "aspects.xml" file which lists all of
the possible Aspects plus a number of "appearance..." files (i.e.
appearance-one-searchlight.xml), each of which describes the possible Aspects based
on one Signal Mast type. These essentially say "if the next signal has an 'x' aspect, then
the current one needs to show a 'y' aspect" (more
details).
The Signal Mast Logic table is then used to check which Signal Mast pairs are active in the
Signal Mast Logic and whether the Aspect should not be 'Stop'. This is done by
looking at Turnout positions (if applicable), Block occupancy and - possibly - Sensors. On
the Signal Masts tab you might even specify additional Signal Masts to watch, e.g. for an
Interlocking. For any Signal Mast, there can be 1 to n destination Signal Masts, one of which
is active based on the positions of Turnouts connecting the protected Blocks.
If everything is OK, then the appropriate "appearance..." file for this Signal Mast type will
be used by the Signal Mast Logic to assign a new Aspect based on the Aspect of the next
Signal Mast.
This covers the basic workings in a very high level overview. (Thanks to Dave Sand)
JMRI users have provided signaling systems for Basic, AAR-1946, BR-2003 and many more. The complete list is at https://www.jmri.org/xml/signals/.
To create your own Signaling System Definition follow these Instructions. If you do create a new definition for another prototype railroad or era, after testing please contribute it back to the JMRI project so we can distribute it with future releases of the project for others to use. Like Decoder Definitions in DecoderPro, the more Signal System Definitions we have, the more useful the program becomes, and the more people spend time to improve it. We all win that way!
Signal Masts can be both tested (in Conditionals) and set (in Actions) via Logix. When you're editing a Logix Conditional or Action, you have to type the Signal Mast name and hit enter/return so that the program can look up the available Aspects for that particular Signal Mast.
A program (in Java or Python) can get access to Aspect information in two ways. If the code has a reference to a specific Signal Mast "m", it can use
m.getValidAspects()to get the list of aspect names that this Signal Mast can display. The program can then access the Signal System definition with
SignalSystem sys = m.getSignalSystem()and then enquire about properties of the aspect:
sys.getProperty("Clear","speed");
where the first argument is the aspect name (use, for example, m.getAspect() to
obtain the current one on the mast) and the second is a specific property. Properties can be
defined programmatically via e.g. m.setProperty("Clear","speed","69"); or get loaded
automatically from elements in the aspect.xml file that
defines the specific signal system.
In addition to the global properties for an Aspect, there can also be local properties to a specific Signal Mast type. An example of this is the default icon image: The image for a two-head Signal Mast is different from that for a one-head Signal Mast, even if they both represent "Clear".
To get those:
m.getAppearanceMap().getProperty("Clear","imagelink");
In words, this is saying "Get the Appeance info for this Signal Mast, and then check the
imagelink property of the Clear aspect".
Alternatively, if you know the name of the Signal System in use, a program can access it directly via the InstanceManager:
SignalSystem sys = InstanceManager.getDefault(SignalSystemManager.class).getSystem("basic");
Back to the Signaling main help page.