JMRI is...

Adding signals to your layout with JMRI.

JMRI provides powerful tools for working with your layout.

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

For now, you need to manually create a new directory under the "xml/signals" directory to 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 defintion. Think ahead a little bit: Will there be varients of this definiton 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 decription 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>
    </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.

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>
      <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.

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.

Signaling