-
Notifications
You must be signed in to change notification settings - Fork 331
/
FnMapping.shtml
224 lines (195 loc) · 12.7 KB
/
FnMapping.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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.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: Function Mapping in Programmer Files</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" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: DecoderPro User Guide</h1>
<h2>Function Mapping in Programmer Files</h2>The "fnmapping"
element provides a convenient way to display the CV bits used
to map functions and outputs in a decoder.
<p>You can do a similar thing with lots of rows and columns
in the display, but it would be a lot more work, and the
display wouldn't be nicely tuned.</p>
<p>The fnmapping element works by looking for variables with
names like "F2 controls output 1". Specifically, it's looking
for a name that consists of four (or five) parts:</p>
<ol>
<li>A function name. This could be "FL" or "Fn" or "Fnn",
where n or nn is a decimal number in the range 0-28.<br>
Also supported are some special non-key states used by some
decoders to control outputs. These currently include
"STOP", "DRIVE", "FWD", "REV" and "Sn" or "Snn", where n or
nn is a decimal sensor number in the range 0-28.</li>
<li>An optional "(f)" or "(r)" suffix to the function
name.</li>
<li>The exact string " controls output ". Note the single
spaces before and after!</li>
<li>An output's decimal number.</li>
<li>An optional "(alt)" suffix to the output number (or
name). This allows for an alternate definition of an
output, such as for the Tsunami function group exchange
feature.</li>
</ol>
<p>After finding all the matching variables in the
configuration file, the fnmapping element creates a
rectangular grid to display them.</p>
<p>In the context of a fnmapping element, variables have
several useful attributes and elements:</p>
<ul>
<li>Default - this can be used to set the default values.
This is particularly useful for constant (readonly)
variables, as otherwise they don't have any useful
value.</li>
<li>minOut - sets the minimum number of outputs that the
decoder needs to have defined before this variable is
effective. Since different decoders in the same family
often have different numbers of outputs wires, this allows
a single configuration file to handle multiple decoders.
(See below for an example)</li>
<li>minFn - similar to minOut, but working on the number of
functions that the decoder will respond to. This is
generally not as useful.</li>
<li>constant - this is an element, not an attribute, that
lets you define a variable as having a constant value that
the user can't change. An example of using this to display
a fixed map is displayed below.</li>
</ul>
<p>Several attributes and elements (e.g. "tooltip" &
"label") on a fnmapping variable are ignored and
<strong><em>should not</em></strong> be added to a definition
file:</p>
<p>Several attributes and elements of the "model" element of
the decoder file also affect affect the Function Map
display:</p>
<ul>
<li>numOuts - the number of physical outputs (wires) on the
decoder.</li>
<li>numFns - this is a legacy attribute that limits the
total number of function mapping lines displayed. It is no
longer required as the JMRI code now automatically
suppresses unused lines.</li>
<li>output - the "name" and "label" attributes of the
"output" element can be used to modify what is displayed in
Function Map columns. For details see this <a href=
"/JavaDoc/doc/jmri/jmrit/symbolicprog/FnMapPanel.html"
target="_blank">Javadoc page</a>.</li>
<li>extFnsESU - when set, invokes the specialised
Function Map page required for later model ESU decoders.
The requirements and meaning of some fnmapping elements are
also changed. For details (and current valid settings for "extFnsESU") see this
<a href= "/JavaDoc/doc/jmri/jmrit/symbolicprog/FnMapPanelESU.html"
target="_blank">Javadoc page</a>.</li>
</ul>
<h2>Mapping Example</h2>These examples are taken from the
<a href=
"../../../../../xml/decoders/Digitrax_01x3.xml">Digitrax_01x3.xml</a>
decoder definition file.
<p>The block of definitions for function zero in the forward
direction look like this:</p>
<pre>
<variable item="FL(f) controls output 1" CV="33" mask="XXXXXXXV" minOut="1" default="1"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 2" CV="33" mask="XXXXXXVX" minOut="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 3" CV="33" mask="XXXXXVXX" minOut="3"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 4" CV="33" mask="XXXXVXXX" minOut="4"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 5" CV="33" mask="XXXVXXXX" minOut="5"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 6" CV="33" mask="XXVXXXXX" minOut="6"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 7" CV="33" mask="XVXXXXXX" minOut="7"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="FL(f) controls output 8" CV="33" mask="VXXXXXXX" minOut="8"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
</pre>Note that the "minOut" attribute ensure that only outputs
actually defined as present are displayed.
<p>The similar block of definitions for function two
configure a different CV, but are otherwise quite
similar:</p>
<pre>
<variable item="F2 controls output 1" CV="36" mask="XXXXXXXV" minOut="1" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 2" CV="36" mask="XXXXXXVX" minOut="2" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 3" CV="36" mask="XXXXXVXX" minOut="3" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 4" CV="36" mask="XXXXVXXX" minOut="4" minFn="2" default="1"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 5" CV="36" mask="XXXVXXXX" minOut="5" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 6" CV="36" mask="XXVXXXXX" minOut="6" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 7" CV="36" mask="XVXXXXXX" minOut="7" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F2 controls output 8" CV="36" mask="VXXXXXXX" minOut="8" minFn="2"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
</pre>The only new thing here is that the "minFn" attribute is
being used. This is useful when a family of decoders supports
different numbers of functions (not outputs!) in different decoder
models.
<p>As you go to higher function numbers, the NMRA mapping
between the bits in the CVs and the output numbers changes.
You can see that by looking at an example of how function ten
is mapped to outputs 7 through 14:</p>
<pre>
<variable item="F10 controls output 7" CV="44" mask="XXXXXXXV" minOut="7" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 8" CV="44" mask="XXXXXXVX" minOut="8" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 9" CV="44" mask="XXXXXVXX" minOut="9" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 10" CV="44" mask="XXXXVXXX" minOut="10" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 11" CV="44" mask="XXXVXXXX" minOut="11" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 12" CV="44" mask="XXVXXXXX" minOut="12" minFn="10" default="1"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 13" CV="44" mask="XVXXXXXX" minOut="13" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
<variable item="F10 controls output 14" CV="44" mask="VXXXXXXX" minOut="14" minFn="10"> <enumVal>
<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
</pre>
<h2>Fixed Mapping Example</h2>You might still want to include
the mapping values in a configuration file, even if the
decoder doesn't have a way to change them. This is an example
of a constant mapping:
<pre>
<!-- Define the fixed Function-Output mapping -->
<constant item="FL(f) controls output 1" minOut="1" default="1" />
<constant item="FL(r) controls output 2" minOut="2" default="1" />
<constant item="F1 controls output 3" minOut="3" minFn="1" default="1" />
<constant item="F2 controls output 4" minOut="4" minFn="2" default="1" />
<constant item="F3 controls output 5" minOut="5" minFn="3" default="1" />
<constant item="F4 controls output 6" minOut="6" minFn="4" default="1" />
<constant item="F5 controls output 7" minOut="7" minFn="5" default="1" />
<constant item="F6 controls output 8" minOut="8" minFn="6" default="1" />
<constant item="F7 controls output 9" minOut="9" minFn="7" default="1" />
<constant item="F8 controls output 10" minOut="10" minFn="8" default="1" />
</pre>This will be displayed in the same way as other mappings,
except that the individual checkboxes will be inactive (grayed
out). <!--#include virtual="/Footer" -->
</div><!-- closes #mainContent-->
</div><!-- closes #mBody-->
</body>
</html>