JMRI® is...

DecoderPro®

Advanced

By the community of JMRI.org:

Tools

JMRI tools for working with your layout:

Layout Automation

Use JMRI to automate parts of your layout and operations:

Supported hardware

JMRI supports a wide range of devices, DCC systems, command stations, networks, and protocols.

JMRI Setup and Installation

JMRI environments...

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

JMRI: DecoderPro User Guide

Function Mapping in Programmer Files

The "fnmapping" element provides a convenient way to display the CV bits used to map functions and outputs in a decoder.

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.

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:

A function name. This could be "FL" or "Fn" or "Fnn", where n or nn is a decimal number in the range 0-28.
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.
An optional "(f)" or "(r)" suffix to the function name.
The exact string " controls output ". Note the single spaces before and after!
An output's decimal number.
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.

After finding all the matching variables in the configuration file, the fnmapping element creates a rectangular grid to display them.

In the context of a fnmapping element, variables have several useful attributes and elements:

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.
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)
minFn - similar to minOut, but working on the number of functions that the decoder will respond to. This is generally not as useful.
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.

Several attributes and elements (e.g. "tooltip" & "label") on a fnmapping variable are ignored and should not be added to a definition file:

Several attributes and elements of the "model" element of the decoder file also affect affect the Function Map display:

numOuts - the number of physical outputs (wires) on the decoder.
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.
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 Javadoc page.
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 Javadoc page.

Mapping Example

These examples are taken from the Digitrax_01x3.xml decoder definition file.

The block of definitions for function zero in the forward direction look like this:

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

Note that the "minOut" attribute ensure that only outputs actually defined as present are displayed.

The similar block of definitions for function two configure a different CV, but are otherwise quite similar:

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

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.

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:

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

Fixed Mapping Example

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:

        <!-- 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" />

This will be displayed in the same way as other mappings, except that the individual checkboxes will be inactive (grayed out).

Thanks and congratulations to all who contributed! Contact us via the JMRI users Groups.io group.

Copyright © 1997 - 2024 JMRI Community. JMRI®, DecoderPro®, PanelPro™, DispatcherPro™, OperationsPro™, SignalPro™, SoundPro™, TrainPro™, Logix™, LogixNG™ and associated logos are our trademarks. Additional information on copyright, trademarks and licenses is linked here.

View the