Serge NOEL
311 lines
18 KiB
Plaintext
311 lines
18 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<!-- Copyright Bob Jacobsen 2008 -->
|
|
|
|
<title>JMRI: Defining Your Own Signaling System</title><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI: Defining Your Own Signaling System</h1>
|
|
|
|
<p>This page describes how to define a new signaling system to JMRI.</p>
|
|
|
|
<p>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 <a href="https://www.jmri.org/xml/signals/">xml/signals</a>
|
|
directory.</p>
|
|
|
|
<h2>Creating a New Signaling System</h2>
|
|
|
|
<p>First, you need to manually create new directories to hold the new signal system. Custom
|
|
signal systems are placed in the <strong>users file location</strong>. The path to the custom
|
|
signal system is <strong>resources/signals/<system name></strong>.</p>
|
|
|
|
<p>If the new system is intended to be included in the JMRI distribution, the path is
|
|
<strong>xml/signals</strong> in the JMRI install location. Be aware that a JMRI update can result in the loss
|
|
of the changes.</p>
|
|
|
|
<p>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.<br>
|
|
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.</p>
|
|
<p>Then, provide these files:</p>
|
|
|
|
<ul>
|
|
<li>index.shtml - Free-form description of the signal system</li>
|
|
|
|
<li>aspects.xml - Define the complete set of available aspects</li>
|
|
|
|
<li>appearance-*.xml - One file for each type of SignalMast, defining how to display each
|
|
aspect. Take a look at some existing signal systems to see typical naming conventions.</li>
|
|
</ul>
|
|
|
|
<h3>Create a new index.shtml file</h3>
|
|
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.
|
|
<p>If you're capturing a prototypical system, record what you know about it: The railroad,
|
|
region/district, year, where you found the information, etc.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.
|
|
|
|
<h3>Create a new aspects.xml file</h3>
|
|
The <code><name></code> 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.
|
|
<p>The <code><aspects></code> element in this file lists <em>all</em> 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.</p>
|
|
|
|
<p>Most of the file is blocks that look like this:</p>
|
|
|
|
<pre>
|
|
<aspect>
|
|
<name></name>
|
|
<title></title>
|
|
<indication></indication>
|
|
<description></description>
|
|
<reference></reference>
|
|
<comment></comment>
|
|
<imagelink></imagelink>
|
|
<speed></speed>
|
|
<speed2></speed2>
|
|
<route></route>
|
|
<dccAspect></dccAspect>
|
|
</aspect>
|
|
</pre>You have to fill in the <code><name></code> element. The others are optional, but the
|
|
order of all elements is mandatory to successfully pass the XML validation. The
|
|
<code><title></code> and <code><indication></code> elements may only be included once.
|
|
The <code><description></code>, <code><reference></code> and
|
|
<code><comment></code> elements can be included as many times as you'd like.
|
|
<p>The <code><imagelink></code> 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 <a href="#appearances">appearance files</a>, they'll also be
|
|
displayed here. Individual images is a better solution, but it's also more work.</p>
|
|
|
|
<p>The <code><speed></code> element, if present, should either be a numerical value or
|
|
a string value that has been defined in the signalSpeeds.xml file. The
|
|
<code><speed></code> 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.<br>
|
|
An optional <code><speed2></code> 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
|
|
<code><speed></code>, but in the Approach Diverging aspect it will typically be
|
|
less.<br>
|
|
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 <a href=
|
|
"https://sourceforge.net/p/jmri/mailman/jmri-developers/?viewmonth=201106&viewday=22">in
|
|
the JMRI Developers list</a>).</p>
|
|
|
|
<p>The <code><route></code> 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 <code><route></code> 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.</p>
|
|
|
|
<p>The <code><dccAspect></code> 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.</p>
|
|
|
|
<p>The <code><delay></code> 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.<br>
|
|
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.</p>
|
|
|
|
<p>Below the <code><aspect></code> blocks, there's a block that names all the valid
|
|
appearance files, e.g.:</p>
|
|
|
|
<pre>
|
|
<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>
|
|
</pre>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.
|
|
<h3 id="appearances">Create appearance-*.xml files</h3>
|
|
For each kind of signal on the layout (single head searchlight, double searchlight, dwarf,
|
|
semaphore, etc.) you need to create a dedicated appearance file.
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The value of the <code><aspecttable></code> element should be the user name for the
|
|
overall system, as defined in the aspects.xml file's <code><name></code> element.</p>
|
|
|
|
<p>The <code><name></code> 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 <code><reference></code> and <code><description></code>
|
|
elements to provide information to future users of this signal system. You can see how this
|
|
is displayed in a <a href=
|
|
"https://www.jmri.org/xml/signals/AAR-1946/appearance-SL-1-high-pbs.xml">sample file</a>.</p>
|
|
|
|
<p>Next is the <code><appearances></code> element, which contains a series of
|
|
<code><appearance></code> 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.</p>
|
|
|
|
<p>Each Aspect that the signal can show needs to be described with a block like this:</p>
|
|
|
|
<pre>
|
|
<appearance>
|
|
<aspectname>Clear</aspectname>
|
|
<show>green</show>
|
|
<show>red</show>
|
|
<reference></reference>
|
|
<delay></delay>
|
|
<imagelink></imagelink>
|
|
</appearance>
|
|
</pre>The <code><aspectname></code> needs to be at the start, followed by zero or more <code>
|
|
<show></code> elements.
|
|
<p>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".</p>
|
|
|
|
<p>You can have as many <code><reference></code> elements as you'd like, they're for
|
|
user-readable documentation.</p>
|
|
|
|
<p>The imagelink element, if present, should point to an image file (of type .gif, .png or
|
|
.jpg) showing what this Appearance looks like.<br>
|
|
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.</p>
|
|
|
|
<h4>Specific Appearances</h4>
|
|
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:<br>
|
|
<strong>danger</strong> 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.<br>
|
|
<strong>permissive</strong> (Call-On) this appearance is displayed if the block ahead is
|
|
occupied, but another train is allowed to enter it.<br>
|
|
<strong>held</strong> 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.<br>
|
|
<strong>dark</strong> is used to provide an alternative image on the panel to indicate that
|
|
the signal is not lit.<br>
|
|
Each specific aspect can be given an alternative image to use other than that given in the
|
|
main appearance definition.<br>
|
|
This information can be entered after the appearance information in the following form:
|
|
|
|
<pre>
|
|
<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>
|
|
</pre>Only one aspect can be defined for each specific appearance. For each specific appearance
|
|
entered, the corresponding <code><aspect></code> entry must be a valid
|
|
<code><aspectname></code> that occurs in the appearance definitions for the mast.
|
|
<h4>Aspect Mapping</h4>
|
|
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.
|
|
<p>The value of the <code><advancedAspect></code> can be any that is defined in the
|
|
Aspect table of our signaling system's aspects.xml file.<br>
|
|
The value of <code><ourAspect></code> must be one that is defined and supported by this
|
|
appearance file (so it can be displayed on this signal mast type).</p>
|
|
|
|
<p>All of the mappings are contained within the <code><aspectMappings></code> tags,
|
|
each in their own <code><aspectMapping></code> tag e.g.</p>
|
|
|
|
<pre>
|
|
<aspectMappings>
|
|
<aspectMapping>
|
|
<advancedAspect>Approach</advancedAspect>
|
|
<ourAspect>Clear</ourAspect>
|
|
</aspectMapping>
|
|
<aspectMapping>
|
|
<advancedAspect>Stop</advancedAspect>
|
|
<ourAspect>Approach</ourAspect>
|
|
<ourAspect>Diverging Approach</ourAspect>
|
|
</aspectMapping>
|
|
</aspectMappings>
|
|
</pre>
|
|
<h3>Check Your Work</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3>Amendments to an existing Signaling System</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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
|
|
<strong>resource</strong> directory located in the user preference area called <strong>signals</strong>, 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.</p>
|
|
|
|
<p>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!</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
</div>
|
|
<!-- close #mBody -->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|