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 JMRI install xml/signals directory.
First, you need to manually create new directories to hold the new signal system. Custom signal systems are placed in the users file location. The path to the custom signal system is resources/signals/<system name>.
If the new system is intended to be included in the JMRI distribution, the path is xml/signals in the JMRI install location. Be aware that a JMRI update can result in the loss of the changes.
By convention, the name of this directory (e.g. "basic" or
"AAR-1946") provides the system name for your signal definition. Any Signal Masts you create
that use your new signal system definition will include the signaling system's system name in
their own (mast's) system name, so it's inconvenient to change the system name of the signal
system. 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 easier
to create modified versions.
Note: do not use any special characters like ampersands (&) or spaces in names for files
and directories. JMRI runs on lots of computers, and filenames with spaces or special
characters can cause problems for other people if you ever contribute your files back to JMRI
for distribution.
Then, provide these files:
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.
At a minimum, the index.shtml contains a link to the aspects.xml file and each appearance xml file. This is used to display formatted pages for each xml file. Use the index.xml for the Basic signal system as a model.
If the new signal system is going to be contributed to JMRI, the xml/signals/index.shtml file needs to be updated with a link to the new signal system index.shtml file.
<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 so that the user can associate
them if needed.
The <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> <dccAspect></dccAspect> </aspect>You have to fill in the
<name>
element. The others are optional, but the
order of all elements is mandatory to successfully pass the XML validation. The
<title>
and <indication>
elements may 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 an image file
(.gif, .png or .jpg) showing what the family of Appearances looks like. If you provide
individual images in the appearance files, 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 mast
displaying this Aspect at. The Signal Mast Logic uses this speed to help determine which
aspect should be displayed where there are multiple possible aspects.
An optional <speed2>
element contains the speed (value) the train should -
or may - reach upon arriving at the next signal. For a Clear aspect it would be identical to
<speed>
, but in the Approach Diverging aspect it will typically be
less.
Both of the speed entries refer to the protected block as it was when the train first arrived
at the signal, because of course it will have changed to 'stop' once the train has entered
the next block (more on speeds in
the JMRI Developers list).
The <route>
element, if present, should simply be entered 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 Signal Mast Logic logic uses
this element to help determine which aspect should be displayed where there are multiple
possible Aspects.
The <dccAspect>
element, if present, is the default DCC signal
accessory decoder ID for that aspect. These values are then used to populate the aspect IDs
when a DCC or LNCP signal driver is used. The values can be over-written by the user when
creating or editing a particular Signal Mast.
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 next section), so the program can locate all of them and display them to the user.
Take a look at some existing signal systems to see typical naming conventions. Note: do not use any special characters like ampersands (&) or spaces in names for files and directories. JMRI runs on lots of computers, and filenames with spaces or special characters can cause problems for other people if you ever contribute your files back to JMRI for distribution.
The top of the file is some boiler-plate that you can copy from an existing system, then modify with your own author and revision history information.
The value of the <aspecttable>
element should be the user name for the
overall system, as defined in the aspects.xml file's <name>
element.
The <name>
element is the user name for this particular type of signal
mast. If should be pretty descriptive of the mast, and related in some obvious way to the
filename. Use the <reference>
and <description>
elements to provide information to future users of this signal system. You can see how this
is displayed in a sample file.
Next is the <appearances>
element, which contains a series of
<appearance>
elements that define how the individual Aspects appear on
this type of signal mast. Not every Aspect needs to be defined in every file, as not every
type of signal mast 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 Signal Heads that make up the signal properly to display this Aspect. There can be zero or more of these, containing "red", "flashred", "yellow", "flashyellow", "green", "flashgreen", "lunar", "flashlunar" 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 an image file (of type .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, and the image link should then be prefixed with
"preference:" followed by the remainder of the path. As long as you work locally, use
preference:resources/etc paths. If all aspects of your new signal definition are working on
your panel/layout and you plan to submit your new signal system as a patch to JMRI, use full
URL paths like https://www.jmri.org/resources/icons/etc in the XML files so that they'll work
with both the local JMRI program and for people viewing them on the JMRI website.
<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>
entry must be a valid
<aspectname>
that occurs in the appearance definitions for the mast.
The value of the <advancedAspect>
can be any that is defined in the
Aspect table of our signaling system's aspects.xml file.
The value of <ourAspect>
must be one that is defined and supported by this
appearance file (so it can be displayed on this signal mast type).
All of the mappings are contained within the <aspectMappings>
tags,
each in their own <aspectMapping>
tag e.g.
<aspectMappings> <aspectMapping> <advancedAspect>Approach</advancedAspect> <ourAspect>Clear</ourAspect> </aspectMapping> <aspectMapping> <advancedAspect>Stop</advancedAspect> <ourAspect>Approach</ourAspect> <ourAspect>Diverging Approach</ourAspect> </aspectMapping> </aspectMappings>
You can use the "Validate XML File" tools under the JMRI "Debug" window to check your files. (Note that you have to be connected to the internet to do this, as the files refer to some checking resources that live on the JMRI website.) First, it checks the basic format: Are all the < and > characters in the right place? Etc. Then it makes sure that the right elements are in the right places, checks some of the contents, etc.
There are a number of signaling definitions already provided within JMRI which are located in the JMRI install "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 signaling 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!