Skip to main content

JMRI is...

Signaling

Adding signals to your layout with JMRI.

Tools

JMRI provides powerful tools for working with your layout.

Layout Automation

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

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

First, you need to manually create a new directory in the JMRI system file directory under the "xml/signals" or in the user preferences directory "resources/signals" which will 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. 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:

Create a new index.shtml file

This file provides 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 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.

Create appearance-*.xml files

For each kind of signal on the layout (single head searchlight, double searchlight, dwarf, semaphore, etc.) you need to create a dedicated appearance file.

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 http://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 web site.

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 dependent upon the Signal Mast:
danger 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 provides (via the imagelink element) an alternative panel image to indicate that the "held" condition on the signal has been set. Higher-level logic can (optionally) use the aspect element to determine what to set the signal to when held has been set.
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 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> entry must be a valid <aspectname> that occurs in the appearance definitions for the mast.

Aspect Mapping

The Aspect Mapping is used to help determine the progression of signaling Aspects. The purpose of the map is to define which potential Aspects are valid depending upon what Aspect 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 Aspects 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 <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>

Check Your Work

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 web site.) 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.

Amendments to an existing Signaling System

There are a number of signaling 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 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!