-
Notifications
You must be signed in to change notification settings - Fork 331
/
DefineNewAspects.shtml
384 lines (343 loc) · 17.4 KB
/
DefineNewAspects.shtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">
<!-- Copyright Bob Jacobsen 2008 -->
<title>JMRI: Defining Your Own Signaling System</title>
<!-- Style -->
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
<link rel="stylesheet" type="text/css" href="/css/default.css"
media="screen">
<link rel="stylesheet" type="text/css" href="/css/print.css"
media="print">
<link rel="icon" href="/images/jmri.ico" type="image/png">
<link rel="home" title="Home" href="/">
<!-- /Style -->
</head>
<body>
<!--#include virtual="/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Defining Your Own Signaling System</h1>This page
describes how to define a new signaling system to JMRI.
<p>We go through creating one from scratch, but it's often
easier to copy and modify one of the existing ones in the
<a href="https://jmri.org/xml/signals/">xml/signals</a>
directory.</p>
<h2>Creating a New Signaling System</h2>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.<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>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>
<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. <a name="appearances" id="appearances"></a>
<h3>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://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://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.</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>
<b>danger</b> 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>
<b>permissive</b> (Call-On) this appearance is displayed if
the block ahead is occupied, but another train is allowed to
enter it.<br>
<b>held</b> 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>
<b>dark</b> 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 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.</p>
<h3>Amendments to an existing Signaling System</h3>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.
<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 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.</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="/Footer.shtml" -->
</div>
</div>
</body>
</html>