JMRI: Defining Your Own Signaling System
This page describes how to define a new signaling system to JMRI.We go through creating one from scratch, but it's often easier to copy and modify one of the existing ones in the xml/signals directory.
Creating a New Signaling System
For now, you need to manually create a new directory the JMRI system file directory under the "xml/signals" or in the user preferences directory "resources/signals" (from 2.13.5) these will then hold your new signal definition. By convention, the name of this directory (e.g. "basic" or "AAR-1946") provides the system name for your signal definition. Think ahead a little bit: Will there be variants of this definition for different eras or different divisions? If so, include a year or location in the name, to make it easy to create modified versions.Then, provide these files:
- index.shtml - Free-form description of the signal system
- aspects.xml - Define the complete set of available aspects
- appearance-*.xml - One file for each type of SignalMast, defining how to display each aspect.
Create a new index.shtml file
This is only a description, but it's important to do it first so that you record the details of what you've done.If you're capturing a prototypical system, record what you know about it: The railroad, region/district, year, where you found the information, etc.
If you're making up your own system, describe it in some detail so that you can come back to it later on and remember what you had in mind.
Create a new aspects.xml file
The "name" element at the top of this file provides the user name for your signaling system, which features prominently in the user interface. It can be a little more verbose than the directory name, but should be similar enough that the user can associate them if needed.This "aspects" element in this file lists all the aspects that can appear in this signaling system. (Most model railroads only model one railroad, so there's only one system present, but it is possible to use more than one). You can come back and add more later if needed, but it's better to enter them all at the beginning because the names will be more consistent, etc.
Most of the file is blocks that look like this:
<aspect>
<name></name>
<title></title>
<indication></indication>
<description></description>
<reference></reference>
<comment></comment>
<imagelink></imagelink>
<speed></speed>
<speed2></speed2>
<route></route>
</aspect>
You have to fill in the name element, but the others are optional.
The title and indication elements can only be included once.
The description, reference and comment elements can be included
as many times as you'd like.
The imagelink element, if present, should point to a image file (.gif, .png or .jpg) showing what the family of appearances looks like. If you provide individual images in the appearance files (see below), they'll also be displayed here. Individual images is a better solution, but it's also more work.
The speed element, if present, should either be a numerical value or a string value that has been defined in the signalSpeeds.xml file. The speed element relates to the maximum speed a train can pass the aspect at. The signalmast logic uses this speed to help determine which aspect should be displayed where there are multiple possible aspects.
The route element, if present, should simple be entered in as 'Diverging', 'Normal' or 'Either'. If the element is omitted or left blank then it is taken as being 'Normal'. The route element indicates that this specific aspect is used when a turnout has been thrown in the path ahead. The signalmast logic uses this element to help determine which aspect should be displayed where there are multiple possible aspects.
The delay element, if present, allows a delay to be configured between changing the
aspects on each signal head where multiple heads are configured on a mast.
This is ideally used where in the prototype a manually operated signal (eg semaphore)
would have to be set by the signalman, therefore only one signal head (or Arm) would
be set at any one time.
Below the aspect blocks, there's a block that names all the valid appearance files, e.g.:
<appearancefiles>
<appearancefile href="appearance-SL-1-high-abs.xml"/>
<appearancefile href="appearance-SL-1-high-pbs.xml"/>
<appearancefile href="appearance-SL-1-low.xml"/>
</appearancefiles>
Create this part as you create the appearance files (see below),
to the program can locate all of them and display them to the user.
Create appearance-*.xml files
For each kind of signal on the layout (one searchlight, two searchlight, dwarf, semaphore, etc), you need to create an appearance file.Not every aspect needs to be defined in every file, as not every type of signal can show every aspect.
Each aspect that the signal can show needs to be described with a block like this:
<appearance>
<aspectname>Clear</aspectname>
<show>green</show>
<show>red</show>
<reference></reference>
<delay></delay>
<imagelink></imagelink>
</appearance>
The "aspectname" needs to be at the start, followed by zero or more
"show" elements.
The show element(s) will be used to set the signalheads that make up the signal properly to display this aspect. There can be zero or more of these, containing "red", "flash red", "yellow", "flash yellow", "green", "flash green", "lunar", "flash lunar" or "dark".
You can have as many "reference" elements as you'd like, they're for user-readable documentation.
The imagelink element, if present, should point to
a image file (.gif, .png or .jpg) showing what this appearance looks like.
If you are creating or using custom images then these should be placed in a
sub-directory within the user preference area, the image link should then
be prefixed with "preference:" followed by the remainder of the path.
Specific Appearances
There are four specific appearances that JMRI will and can refer to, as the appearance names are all user defined and can be in any language all are optional and dependant upon the signalmastdanger This is the most restrictive aspect that the signal mast can show. When the path ahead is not set or clear the signal mast logic will set the signal mast to this appearance.
permissive (Call-On) this appearance is displayed if the block ahead is occupied, but another train is allowed to enter it.
held is used to provide an alternative image on the panel to indicate that the signal has been held at Danger.
dark is used to provide an alternative image on the panel to indicate that the signal is not lit.
Each specific aspect can be given an alternative image to use other than that given in the main appearance definition.
This information can be entered at after the appearance information in the following form.
<specificappearances>
<danger>
<aspect>Danger</aspect>
</danger>
<permissive>
<aspect>Off</aspect>
</permissive>
<held>
<aspect>Danger</aspect>
<imagelink>held.gif</imagelink<
</held>
<dark>
<aspect>Not Lit</aspect>
<imagelink>notlit.gif</imagelink<
</dark>
</specificappearances>
Only one aspect can be defined for each specific appearance.
For each specific appearance entered, the corresponding Aspect Mapping
The aspect mapping is used to help determine the progression of signalling appearances. The purpose of the map is to define which potential appearances are valid depending upon what appearance is being displayed on the signal mast that is ahead of us. This mapping can be a simple one-to-one, E.g. Advanced signal mast is showing Approach, we should show Clear. Or a more complex one-to-many map where there could be multiple appearances that we could display, E.g. Advanced signal is showing Stop, but we could display either a Approach or Diverging Approach depending upon other conditions.
The value of the Advanced Aspect can be any that is defined in the Aspect table
for that signalling system.
The value of Our Aspect, must be one that is defined and supported by the
defined in the appearance file.
All of the mappings, are contained within the <aspectMappings> tags, within their own <aspectMapping> tag
<aspectMappings>
<aspectMapping>
<advancedAspect>Approach</advancedAspect>
<ourAspect>Clear</ourAspect>
</aspectMapping>
<aspectMapping>
<advancedAspect>Stop</advancedAspect>
<ourAspect>Approach</ourAspect>
<ourAspect>Diverging Approach</ourAspect>
</aspectMapping>
</aspectMappings>
Check Your Work
You can use the "Check XML File" and "Validate XML File" tools under the JMRI "Debug" window to check your files. The first checks the basic format: Are all the < and > characters in the right place? Etc. The second makes sure that the right elements are in the right places, and is a little more intensive.Amendments to an Existing Signaling System
There are a number of signalling definitions already provided within JMRI which are located in the "xml/signals" directory, some of these may generally meet your existing requirements however some might require changes to suit the hardware that you use, or there are local variation in operations, or simply that you do not have the facility to work to a fully prototypical set of signals.In this case it is possible to amend and create your own appearance files that will over-ride the JMRI provided ones. You will need to first create a sub-directory in the resource directory located in the user preference area called "signals", you will then need to create a sub-directory in there which has exactly the same name as the JMRI provided one. From there any appearance files you create or copy into will either be added to the mast list for that signalling system or overwrite the predefined JMRI signal mast.
The advantage of placing new and amended signal mast appearance files here is that when JMRI is updated, then these files will not get overwritten and lost!