Serge NOEL
435 lines
22 KiB
Plaintext
435 lines
22 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: DecoderPro User Guide - Creating A Custom Decoder File</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: DecoderPro User Guide</h1>
|
|
|
|
<h2>Creating A Custom Decoder File</h2>
|
|
|
|
<p>This page provides information on how the decoder definition files for the DecoderPro
|
|
Symbolic Programmer work and how to create a new one.</p>
|
|
|
|
<p>In this user guide, we walk you through the process of creating a file to describe a new
|
|
decoder. You might benefit from reading the other sections of the DecoderPro user guide to
|
|
get background information, especially the <a href="IntroXML.shtml">XML introduction</a> and
|
|
the section on <a href="../../doc/Technical/ProfileFileStructure.shtml">Configuration Files contents</a>.</p>
|
|
|
|
<p>The easiest way to create a configuration file is to modify an existing one. In this
|
|
section, we walk you through doing this.</p>
|
|
|
|
<dl>
|
|
<dt class="left">Make a copy of a similar file.</dt>
|
|
|
|
<dd class="first">
|
|
<p>Although you can call this new file anything you like, it will work best if you use
|
|
the same convention as the provided files. That's <code>"manufacturer name"_"decoder
|
|
family".xml</code>, for example: <code>Digitrax_1x2.xml</code> and
|
|
<code>Atlas_DualMode.xml</code></p>
|
|
|
|
<p>For the provided files, we use the same capitalization, etc, that the decoder
|
|
manufacturer uses in their documentation.</p>
|
|
|
|
<p>This new file should go in the <code>decoders</code> subdirectory in the
|
|
<code>JMRI</code> User Files Location so that the program can find it.
|
|
You may have to create this directory if it hasn't already been created.
|
|
You can select "File Locations"
|
|
from the JMRI Help menu to find (and open) the User Files Location. (See the <a href=
|
|
"../../doc/Technical/ProfileFileStructure.shtml"><em>configuration files page</em></a>
|
|
for further details about how to find that directory and its contents)</p>
|
|
|
|
<p>If you're modifying a decoder definition, it is best to start with the most recent
|
|
version, which can always be found here on the JMRI website at <a href=
|
|
"https://www.jmri.org/xml/decoders/">https://www.jmri.org/xml/decoders/</a>. That way, it won't
|
|
be hard to merge your changes with ones that might have come before. Please don't do any
|
|
more reformatting than you have to. If you change the tech stuff in the top 5 or 10
|
|
lines, or reformat the contents, it gets very hard to tell what's changed and what has
|
|
not.</p>
|
|
|
|
<p>After adding your new decoder definition, do not forget to recreate the <b>Decoder Index</b>,
|
|
see below for futher instructions</p>
|
|
|
|
</dd>
|
|
|
|
<dt class="left">Edit the new file</dt>
|
|
|
|
<dd>
|
|
<p>Open the new file with your favorite text editor.</p>
|
|
</dd>
|
|
|
|
<dt class="left">File contents: XML Header</dt>
|
|
|
|
<dd>
|
|
<p>You'll see something like this at the top of the file (the examples are from the
|
|
<a href="https://github.com/JMRI/JMRI/blob/master/xml/decoders/0NMRA.xml">0NMRA.xml</a> file):</p>
|
|
|
|
<p class="example"><?xml version="1.0" encoding="utf-8"?><br>
|
|
<?xml-stylesheet type="text/xsl" href="../XSLT/decoder.xsl"?><br>
|
|
<!-- Copyright (C) JMRI 2001, 2005, 2007, 2-009, 2010 All rights reserved --><br>
|
|
...<br>
|
|
<decoder-config xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:noNamespaceSchemaLocation="http://jmri.org/xml/schema/decoder.xsd"><br></p>
|
|
|
|
<p>Don't mess with these lines; they describe the format of the file.</p>
|
|
</dd>
|
|
|
|
<dt class="left">File contents: Author</dt>
|
|
|
|
<dd>
|
|
<p>The next element describes the author and version of this decoder file:</p>
|
|
|
|
<p class="example"><version author="jake@physics.berkeley.edu"<br>
|
|
version="1" lastUpdated="20011201"/></p>
|
|
|
|
<p>These attributes are only read by people, not the program, so their exact format isn't
|
|
critical. But we encourage you to insert your email address in files you create or
|
|
change, so that if anybody has any questions they can find you. The version and
|
|
lastUpdated attributes provide a way of telling different versions of a decoder
|
|
definition apart, so we'd also like you to update those. For a new file, set the version
|
|
back to "1", and if you're modifying an existing file, increment the version attribute to
|
|
the next number.</p>
|
|
</dd>
|
|
|
|
<dt class="left">File contents: Decoder Family and Model</dt>
|
|
|
|
<dd>
|
|
The next lines identify the "family" of decoders that this file describes:
|
|
<p class="example"><decoder><br>
|
|
<family name="Digitrax 1x2" mfg="Digitrax"<br>
|
|
lowVersionID="240" highVersionID="242"<br>
|
|
comment="Digitrax DH142, etc" ><br>
|
|
<model model="DH142" numOuts="4" numFns="2"/><br>
|
|
<model model="DN142" numOuts="4" numFns="2"/><br>
|
|
<model model="DH083" numOuts="5" numFns="2"/><br>
|
|
</family></p>
|
|
|
|
<p>The spacing is not important, but it is useful to indent the file like this to make it
|
|
more readable. XML uses "elements" and "attributes" to carry information. The
|
|
<model> things are elements; attributes like numOuts are set to specific values
|
|
within elements. In the 2nd through 4th lines above</p>
|
|
|
|
<p class="example"><family name="Digitrax 1x2" mfg="Digitrax"<br>
|
|
lowVersionID="240" highVersionID="242"<br>
|
|
comment="Digitrax DH142, etc" ></p>
|
|
|
|
<p>the element is 'family', with attributes 'name', 'mfg', 'lowVersionID',
|
|
'highVersionID', and 'comment'. An attribute is given a value with an equals sign and a
|
|
value in quotes (the quotes are required). The order of the attributes is not important,
|
|
and you can break them across lines if that makes the file easier to read. Note that all
|
|
of the attributes must be inside the angle brackets, and after the name of the
|
|
element.</p>
|
|
|
|
<p>In this element, change the attributes to match your new decoder:</p>
|
|
|
|
<ul>
|
|
<li><dfn>name</dfn> - the name of the decoder family. It's best if you use the same
|
|
name here as you used in the filename.</li>
|
|
|
|
<li><dfn>mfg</dfn> - the manufacturer of the decoder. It's best if you use the same
|
|
manufacturer name here as you used in the filename.</li>
|
|
|
|
<li>
|
|
<dfn>lowVersionID</dfn>, <dfn>highVersionID</dfn> - The manufacturer can load a
|
|
version number into CV 7 of a decoder. Not all manufacturers do this, but if one is
|
|
available the programmer can check if this file is being used with the expected
|
|
decoder type. If only one specific value is valid, define the both lowVersionID and
|
|
highVersionID with the same value, e.g.
|
|
<code>lowVersionID="123" highVersionID="123"</code>
|
|
If the decoder type can have any one of a range of numbers, for example because the
|
|
manufacturer has made some updates, define both attributes to cover the range:
|
|
<code>lowVersionID="21" highVersionID="42"</code>
|
|
If you don't know the version number, don't define either of these attributes; just
|
|
leave them off. lowVersionID defaults to 0, highVersionID defaults to 255, so
|
|
together the defaults mean "any value".
|
|
</li>
|
|
|
|
<li><dfn>comment</dfn> - this is optional. You might want to include your name, or
|
|
other info about the changes in the file.</li>
|
|
</ul>
|
|
|
|
<p>The following lines:</p>
|
|
|
|
<p class="example"><model model="DH142" numOuts="4" numFns="2"/><br>
|
|
<model model="DN142" numOuts="4" numFns="2"/><br>
|
|
<model model="DH083" numOuts="5" numFns="2"/></p>
|
|
allow you to list a number of different decoder models that can use this file. For a
|
|
single decoder, remove all but one of the "model" elements, and give it the model name of
|
|
the decoder. The numOuts and numFns are described later, but for now you can just delete
|
|
them, leaving something like:
|
|
<p class="example"><model model="DH142" /></p>
|
|
The model element can also contain lowVersionID and/or highVersionID attributes, which
|
|
apply to just that model. If one doesn't appear, the value from the family element (or
|
|
its default) will be used.
|
|
<p>It is important to note that <em>the 'family'+'model' combination must be unique</em>.
|
|
This is the <em>only</em> information that can be used to match a decoder definition to
|
|
an existing roster entry.</p>
|
|
|
|
<ul>
|
|
<li>There can be multiple instances of model 'x' but they must reside in different
|
|
families.</li>
|
|
|
|
<li>There can be multiple definitions of family 'y' (in different decoder files) but
|
|
model 'x' can only appear within one of these.</li>
|
|
|
|
<li>The 'family'+'model' uniqueness restriction applies irrespective of
|
|
manufacturer.</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt class="left">File contents: Programming Modes</dt>
|
|
|
|
<dd>
|
|
<p>The next element defines what programming modes the decoder can understand:</p>
|
|
|
|
<p class="example"><programming direct="byteOnly" paged="yes"<br>
|
|
register="yes" ops="yes"></programming></p>
|
|
|
|
<p>Paged, register and ops can be set to either "yes" or "no". Direct can be set to "no",
|
|
"bitOnly", "byteOnly", or "yes". The programmer uses this information to select the
|
|
programming mode to use when working with a decoder.</p>
|
|
</dd>
|
|
|
|
<dd id="variable">
|
|
</dd>
|
|
|
|
<dt class="left">File contents: Variable names</dt>
|
|
|
|
<dd>
|
|
<p>The next part of the file consists of a set of 'variable' elements defining specific
|
|
variables, nested inside a 'variables' (note the extra "s") element. An example:</p>
|
|
<pre>
|
|
<variables>
|
|
<variable CV="1" item="Primary Address" default="03">
|
|
<decVal min="1" max="127"/>
|
|
<label>Short Address</label>
|
|
<comment>NMRA standard form</comment>
|
|
<tooltip>Digitrax systems only address 1-99</tooltip>
|
|
</variable>
|
|
(followed by more <variable> entries)
|
|
(Insert new ones at the end)
|
|
</variables></pre>
|
|
|
|
<p>Each variable represents one thing to configure. They can represent a single CV, e.g.
|
|
address, or a few bits that can be configured to control a particular function. If some
|
|
of these aren't appropriate to your decoder, you can just remove them. Make sure you
|
|
remove the entire element from the <code><variable></code> up to and including the matching
|
|
<code></variable></code>. You can also rearrange them if you'd prefer a different order.</p>
|
|
|
|
<p>The attributes include:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<dfn>item</dfn> - The 'standard' name for this variable. See the <a href=
|
|
"Programmer.shtml#id">discussion on the programmer definition page</a> for more
|
|
information on this. Generally, look at the Comprehensive programmer to find
|
|
something similar, and use the "name" attribute of that.
|
|
</li>
|
|
|
|
<li><dfn>CV</dfn> - Which CV contains the configuration information for this
|
|
variable.</li>
|
|
|
|
<li>
|
|
<dfn>mask</dfn> - A pattern to control which part in the CV contains the variable.<br>
|
|
JMRI supports 2 types:
|
|
|
|
<p>A string like <code>XXXVVVXX</code> where each "V" is a bit that's included, and "X"
|
|
is a bit that's not to be included. It's best to have eight characters, as that makes it clearer
|
|
what's going on. If the variable is a full byte, the mask attribute can be omitted.<br>
|
|
Example:
|
|
<p class="example"><variable item="Dim Lamp 3" CV="13" mask="XXVVXXXX"><br>
|
|
...<br>
|
|
</variable></p>
|
|
<p>Generally, the V characters should be a contiguous block of bits as specified in
|
|
the manufacturer's documentation for the decoder. In certain rare cases, the layout
|
|
of the decoder might require a different pattern like <code>XXVVXXVV</code>, but in
|
|
those cases please check the operation of the resulting decoder definition carefully
|
|
to make sure it does what you want.</p>
|
|
|
|
<p>A second mask pattern, Radix, is useful in cases where instead of bits, digits you enter
|
|
make up a pattern such as 1234C where "1234" is a turnout address and "C" is some other variable.
|
|
A Radix mask can handle CVs that are coded in bases other than binary: Ones that store their parts
|
|
as decimal digits (as our example), or even base 3 or 5. That's a bit more technical, it's rarely
|
|
needed, but if you do need it refer to the <a href="CreateDecoderAdvanced.shtml#mask">Advanced
|
|
Decoder</a> help page or the <a href=
|
|
"https://www.jmri.org/JavaDoc/doc/jmri/jmrit/symbolicprog/VariableValue.html">javadoc</a> for
|
|
more details. The <a href="https://github.com/JMRI/JMRI/blob/master/xml/decoders/Uhlenbrock_63410.xml">Uhlenbrock_63410</a> definition
|
|
provides an example on CV1.
|
|
</li>
|
|
|
|
<li><dfn>default</dfn> - The default value for this variable. This is used for a new
|
|
decoder, or when you want to set the decoder back to its defaults.</li>
|
|
</ul>
|
|
|
|
<p>(There are a few more, which we'll leave for the advanced section below)</p>
|
|
|
|
<p>The "label" included element provides a human-comfortable name for this variable. This
|
|
is generally what the decoder manufacturer calls this item, even if other manufacturers
|
|
or the NMRA use a different name for similar things. It is optional, in which case the
|
|
"item" value will be used to label it when it's presented to the user.</p>
|
|
|
|
<p>The "comment" element let you provide additional information to future developers.
|
|
This information is visible when editing the definition, but isn't provided to somebody
|
|
who's just using DecoderPro.</p>
|
|
|
|
<p>The "tooltip" element let you provide additional information to the user when the user
|
|
hovers their cursor over the variable on the screen.</p>
|
|
</dd>
|
|
|
|
<dt class="left">File contents: Creating new Variable definitions</dt>
|
|
|
|
<dd>
|
|
<p>You can also define new variables. A good starting point is to copy a similar
|
|
definition, change its item name to a new value, and then edit its contents.</p>
|
|
|
|
<p>To define how the new variable is displayed and edited, you add elements within the
|
|
'variable' element. There are several possible forms:</p>
|
|
|
|
<ul>
|
|
<li>For a decimal value, you include a <code><decVal></code> element like the
|
|
example above. The two optional attributes are 'min' and 'max', which define the range of acceptable
|
|
values. If you omit them, values from 0 to 255 are allowed.
|
|
If 'min' is present and less than zero, the value will be stored
|
|
as a twos-complement number which allows negative values. If not,
|
|
the number will be stored as an unsigned number.</li>
|
|
|
|
<li>If you'd rather enter and display values in hexadecimal, use a <code><hexVal></code> element.
|
|
It's otherwise the same as the <code><decVal></code> element we've already discussed.</li>
|
|
|
|
<li>
|
|
<p>If your decoder supports a long address, you can add a <code><longAddressVal></code>
|
|
element. It's perhaps easiest to copy this from another file, or from this example:</p>
|
|
|
|
<p class="example"><variable item="Long Address" CV="17"><br>
|
|
<longAddressVal/><br>
|
|
</variable></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If your decoder supports it, you can enter a <code><speedTableVal></code> element for
|
|
the speed table. Optional attributes are: "entries", "min", "max" and "mfx" (when true enables
|
|
the Märklin mfx® style speed table). Example:</p>
|
|
|
|
<p class="example"><variable item="Speed Table" CV="67"><br>
|
|
<speedTableVal/><br>
|
|
</variable></p>
|
|
</li>
|
|
|
|
<li>Some decoder options are best represented by "choose one option". These are
|
|
represented by the <code><enumVal></code> element. Example:
|
|
<p class="example"><variable item="F6 during DC operation" CV="13"
|
|
mask="XXVXXXXX"><br>
|
|
<enumVal><br>
|
|
<enumChoice choice="Off"/><br>
|
|
<enumChoice choice="On"/><br>
|
|
</enumVal><br>
|
|
</variable></p>
|
|
|
|
<p>Each enumChoice element describes one possibility. There can be as many of these
|
|
as desired. For a one bit choice, you use two enumChoice elements as in the example.
|
|
For a 4 bit choice, like the FX codes in a Digitrax decoder, you can use up to 16
|
|
choices. They are displayed in the order they are entered in the file, and are also
|
|
numbered in that order. If the first is chosen, "0" is entered in the CV bits;
|
|
choosing the second stores "1"; etc.</p>
|
|
|
|
<p>If you need to specify a specific value for an enum option, add a "value"
|
|
attribute:</p>
|
|
|
|
<p class="example"><enumChoice choice="Blue" value="32"/></p>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt class="left">Including fragment files</dt>
|
|
|
|
<dd>
|
|
<p>Decoder definitions can include "fragment files" which provide common definitions of
|
|
some CVs. This has the advantage that they're already created and tested, and often
|
|
include tooltip text, translations and other nice features. See the existing decoder
|
|
definitions for <a href="https://www.jmri.org/xml/decoders/nmra/">examples</a>. Some key
|
|
ones:</p>
|
|
|
|
<ul>
|
|
<li>CV1, the primary or short address, CV17 and 18, the extended or long address, and
|
|
the corresponding CV29 bits can be handled by one of these, depending on what the
|
|
decode supports:
|
|
<ul>
|
|
<li>xml/decoders/nmra/shortAddressOnly.xml</li>
|
|
|
|
<li>xml/decoders/nmra/shortAndLongAddress.xml</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>CV19, the consist address and direction, can be handled by one of these:
|
|
<ul>
|
|
<li>xml/decoders/nmra/consistAddr.xml</li>
|
|
|
|
<li>xml/decoders/nmra/consistAddrDirection.xml</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>The CV16/CV15 decoder lock feature can be handled by the
|
|
xml/decoders/nmra/decoderLockId16.xml fragment file. Note that only CV16 is included;
|
|
CV15 should not be included in the definition to prevent it from being changed after
|
|
decoder installation.</li>
|
|
</ul>
|
|
|
|
<p>You can also use fragment files to include (hence simplify) <a href=
|
|
"https://www.jmri.org/xml/decoders/parts/">common sets of enum choices</a>.</p>
|
|
<p>Note that you should use the full format for an include statement so that JMRI can find it:
|
|
<p class="example"><xi:include href="http://jmri.org/xml/decoders/nmra/shortAndLongAddress.xml"/>
|
|
</p>
|
|
|
|
|
|
</dd>
|
|
|
|
<dt class="left">Checking for syntax errors</dt>
|
|
|
|
<dd>
|
|
<p>At this point, you've created a new configuration file!</p>
|
|
|
|
<p>You can check it for syntax by selecting the "Validate XML file" item from the "Debug"
|
|
menu. It opens a file selection dialog; select your file and click "open". If all is
|
|
well, you'll get a dialog box that says "OK". If not, you'll get a completely
|
|
incomprehensible error message. About the only useful part of that message is the line
|
|
number; open an editor to that line and try to see what's wrong with the syntax.</p>
|
|
</dd>
|
|
|
|
<dt class="left">Add the file to the index</dt>
|
|
|
|
<dd>
|
|
<p>All that's left is to enter your new file in the index. This index is used to speed
|
|
the startup of the program, when the list of available decoders is constructed.</p>
|
|
|
|
<p>Select the "Recreate decoder index" item from the DecoderPro "Actions" menu or the
|
|
PanelPro "Debug" menu.</p>
|
|
|
|
<p>Restart JMRI to see the new changes take effect</p>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Congratulations! You're done. Next, open the programmer application and try it.</p>
|
|
|
|
<p>For more advanced information on the content of the files, please see the <a href=
|
|
"CreateDecoderAdvanced.shtml">Advanced Decoder Definitions</a> page.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|