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 three parts:

A function name. This could be "Fn" or "Fnn", where n or nn is a decimal number. Two special names for F0 are also recognized: "FL(f)" and "FL(r)"
The exact string " controls output ". Note the spaces!
A decimal output number.

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.

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 label="FL(f) controls output 1" CV="33" mask="XXXXXXXV" minOut="1" default="1"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 2" CV="33" mask="XXXXXXVX" minOut="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 3" CV="33" mask="XXXXXVXX" minOut="3"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 4" CV="33" mask="XXXXVXXX" minOut="4"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 5" CV="33" mask="XXXVXXXX" minOut="5"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 6" CV="33" mask="XXVXXXXX" minOut="6"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="FL(f) controls output 7" CV="33" mask="XVXXXXXX" minOut="7"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="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 label="F2 controls output 1" CV="36" mask="XXXXXXXV" minOut="1" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 2" CV="36" mask="XXXXXXVX" minOut="2" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 3" CV="36" mask="XXXXXVXX" minOut="3" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 4" CV="36" mask="XXXXVXXX" minOut="4" minFn="2" default="1"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 5" CV="36" mask="XXXVXXXX" minOut="5" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 6" CV="36" mask="XXVXXXXX" minOut="6" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F2 controls output 7" CV="36" mask="XVXXXXXX" minOut="7" minFn="2"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="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 label="F10 controls output 7" CV="44" mask="XXXXXXXV" minOut="7" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 8" CV="44" mask="XXXXXXVX" minOut="8" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 9" CV="44" mask="XXXXXVXX" minOut="9" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 10" CV="44" mask="XXXXVXXX" minOut="10" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 11" CV="44" mask="XXXVXXXX" minOut="11" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 12" CV="44" mask="XXVXXXXX" minOut="12" minFn="10" default="1"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="F10 controls output 13" CV="44" mask="XVXXXXXX" minOut="13" minFn="10"> <enumVal> 
			<enumChoice choice="No"/> <enumChoice choice="Yes"/> </enumVal> </variable>
		<variable label="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 label="FL(f) controls output 1" minOut="1" default="1" /> 
	<constant label="FL(r) controls output 2" minOut="2" default="1" /> 
	<constant label="F1 controls output 3" minOut="3" minFn="1" default="1" /> 
	<constant label="F2 controls output 4" minOut="4" minFn="2" default="1" /> 
	<constant label="F3 controls output 5" minOut="5" minFn="3" default="1" /> 
	<constant label="F4 controls output 6" minOut="6" minFn="4" default="1" /> 
	<constant label="F5 controls output 7" minOut="7" minFn="5" default="1" /> 
	<constant label="F6 controls output 8" minOut="8" minFn="6" default="1" /> 
	<constant label="F7 controls output 9" minOut="9" minFn="7" default="1" /> 
	<constant label="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).