JMRI® is...

DecoderPro®

Advanced

Applications

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

Donate to JMRI 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:

  1. 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.
  2. An optional "(f)" or "(r)" suffix to the function name.
  3. The exact string " controls output ". Note the single spaces before and after!
  4. An output's decimal number.
  5. 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:

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:

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