Configuration Variable

A Configuration Variable is a memory location in the decoder that controls the behaviour of the decoder. Think of it as a preferences file that saves the settings on a computer. Once set, the value will be retained unless the memory becomes corrupted.

Another term is Configuration Register which is used to describe Configuration Variable 29, which stores the settings for a number of basic decoder functions.

Just like any other computer, decoders must be programmed by the user to reach their full potential. While they come with basic "factory default" settings, most users will want to customize the decoder address, motor control, lights, sound, and other functions to meet their specific needs. You do so by editing the CVs, or Configuration Variables, in the decoder. Some CVs use values ranging from 0 to 255, others use their space in the decoder's memory as a bank of eight on/off switches. While this lets you do a lot with very little memory, it can get very complex for those of us that aren't on speaking terms with binary code.

There is Software available which simplifies the programming of decoders. Many people agree that JMRI is the best, free, open source software available - JMRI often rivals commercially available software.

Configuration Variables

Configuration variables or CVs are memory locations within a decoder. They are the means for controlling the performance of a DCC decoder. They can be used in a couple of different ways.

A CV can store raw data. It can do this as a binary number with a value between "00000000" (decimal 0) and "11111111" (decimal 255), as two binary numbers in high bits/low bits format "HHHHLLLL", or some variant of these. Data can also be spread across multiple CVs if the necessary maximum value exceeds decimal 255.

A CV can store information as a series of "bit switches", each bit controlling the state of a specific function, turning it on or off. For example, CV 29 works in this way.

A combination of the above. For example, CV 19 works in this way.

There are NMRA standards for the functions specific CVs are to control, but there is plenty of room left for manufacturers to add their own characteristic or proprietary functions, as well. The current NMRA standards for configuration variables cover only the NMRA specified CVs. See your specific decoder documentation for other capabilities beyond the basic capabilities. It is beyond the realm of this document to list the manufacturer-specific CVs for all available decoders.

Explanation of Binary number/Decimal conversion and BitSwitches

There are several ways to store data in CVs. The one that causes the most confusion for those who are not acquainted with the inner workings of a computer is the "bitswitch". This system is far simpler that it might appear. Consider the table below:

Most Significant Bit	Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0	Least Significant Bit
	128	64	32	16	8	4	2	1
	0	0	0	0	0	0	0	0

Think of the eight bits of the CV as a bank of eight simple on/off switches. Each switch is identified by the bold number above it. A value of "0" means the switch is OFF or in its default mode, a value of "1" turns it ON. A decimal number between 0 and 255 identifies a unique setting for every switch in the bank of 8. This allows you to turn on or off any possible combination of these 8 switches by entering the appropriate decimal number into the CV. These software switches are the digital equivalent of the DIP switches, selector switches, or the jumpers that were often found on computer hardware.

Here is an example of the best-known CV that uses this technique, CV29:

CV 29	Loco/Acc Decoder	Reserved	2/4 Digit Addressing	Speed Table	Advanced Decoder Ack.	Power Source Conversion	F0 Control	Loco Direction	Decimal Value
	Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
	128	64	32	16	8	4	2	1
	0 Off	0 Off	1 On	0 Off	0 Off	1 On	0 Off	0 Off	36

In the above example, 2 bits are on - bits 32 and 4. Add 32+4 and you get 36, the decimal value of the bitswitch settings shown. If you wanted to turn on the speed tables too, then you would add 16 to that value, for a decimal value of 52.

Some times you need to work in reverse-- you read the value of the CV from the decoder, then have to figure out what switches are on and which are off. It's simple, but tedious.
The binary equivalents of the switch positions (as shown in the table above) are 128 - 64 - 32 - 16 - 8 - 4 - 2 - 1.
Start with the value you read from the CV, in this case 52.
52 is less than 64, so there are no 128s or 64s in the CV (ie those switches are off).
52 is greater than 32, so there is a 32 in the CV; that switch is on.
Subtract 32 from 52 giving the remainder of 20.
20 is greater than 16, so there is a 16 in the CV; that switch is on.
Subtract 16 from 20 giving the remainder of 4.
4 is less than 8, so that switch is off.
4 = 4, so that switch is on.
Subtract 4 from 4 giving 0; all remaining switches (2 and 1) are off.
Switches 32, 16, and 4 are on, the rest are off.

Indexed CVs

NMRA Standards

The NMRA DCC Packet standard allows for more CVs than the 1-1024 limit specified. While many of those CVs are reserved, the standard anticipated the need for additional CVs beyond those specified in the standard.

NMRA Standard S9.2.2 defined the ranges 1-256 and 512-1024 as normal CVs. CVs between 257 to 511 are treated as Paged Index CVs, with the page numbers being stored in CVs 31 and 32, the index registers, or Master CV. This allows up to 65,536 additional pages in that range.

The NMRA Standard regarding Configuration Variables says:

Configuration Variable 31 Index High Byte
Configuration Variable 32 Index Low Byte

The Indexed Address is the address of the indexed CV page when the decoder is set up for indexed CV operation. CV#31 contains the most significant bits of the two byte address and may have any value between 00010000 and 11111111 inclusive. Values of 00000000 thru 00001111 are reserved by the NMRA for future use. (4096 indexed pages)

CV#32 contains the least significant bits of the index address and may contain any value. This gives a total of 61,440 indexed pages, each with 256 bytes of CV data available to manufacturers.

Note: If the decoder does not support a feature contained in this table, it shall not allow the corresponding bit to be set improperly (i.e. the bit should always contain its default value).

Manufacturer Notes

ESU was the first to correctly implement the Indexed CV in their decoders. Zimo soon followed.

SoundTraxx implemented a S9.2.2 style Indexed CVs method in the Econami and Tsunami 2 ranges. Their decoders use a fixed value of 16 in CV31. QSI created a non-standard indexing system with CV49 only, or CV49 and 50 as subindexes to CVs less than 257. TCS adopted a more complicated addressing scheme with CVs 201, 202, 203 & 204.

Indexed Configuration Variables

An Indexed Configuration Variable is a special version of the CV. They are used to group a number of functions together, simplifying access when additional related functions have been added over time to the decoder software. Often they are employed to configure sound effects, lighting or motor operation variables.

Indexed CVs allow the programmer to organize related programming functions under a Master CV. Access to the Master CV is only available through its Indexes. A Master CV can have two Indexes.

Identified as Primary and Secondary indexes, they are expressed as decimal places in the formula used to set them. They will appear as CV100.150.140, which means the Master CV is 100, the Primary Index is value is 150, and the Secondary Index is set to 140.

The rules are confusing. They are as follows:

The Master CV holds broadly related functions, such as lighting effects or horn/whistle parameters.
Only the Master CV is programmed to control a given function when using indexed CVs.
The same Primary and Secondary indexes control access to the Master CV, regardless of which Master CV is being accessed.
Values entered into the Primary and Secondary Indexes determine the function to be set in the Master CV.

The confusing part is that the Index values are are entered in reverse order:

The Secondary Index Value, Primary Index Value, Master CV. So, as per the above example, it is entered as 140.150, then you can set the Master CV whatever value you wish. (The low byte is set to 140, the high byte to 150, then the master CV value is entered.)

Not all Indexed CVs will require a Secondary Index value.

In many cases, you don't need to re-enter the Primary and Secondary Index values if you want to alter the Master CV.

ESU uses a similar technique to allow systems which are not able to access CVs greater than 255 to set CVs above that limit. See Programming_ESU_Decoders for more.

Indexed CV Programming Issues

There may be some problems with programming when using Indexed CVs.

Command station software may have issues with CVs over 255, such as:

NCE's Power Pro firmware has a bug which causes the wrong CV to be written in Program Track mode for any CV above 256. Attempting to do so may corrupt the decoder's memory.

Both ESU and ZIMO provide decoder firmware based workaround solutions for this problem. See Programming_ESU_Decoders for details related to programming an ESU decoder.

Certain decoder brands may have problems processing indexed CV calculations inside the decoder within the timing specifications of the NMRA standards. This can potentially lead to issues with some brands of DCC systems.

Issues with Indexed CVs and NCE

Options

Use the built-in serial interface and JMRI
Program on the Main: Set CV 31 and 32 first

Accessing a CV greater than 255 may require a different approach, depending on the actual decoder and the NCE DCC system you have. A software issue in the 5A PH-Pro prevents access to indexed CV using the program track. Programming on the Main has no issues.

This does not apply to the Power Cab. There is more information on NCE's Zendesk.

NMRA Basic Configuration Variable Set

The NMRA has defined a basic set of CVs that all decoders have. This ensures that interchange between various manufacturers is possible.

Standard Configuration Variables

Motor Control

CV 02, 03, 04, 23, 24, 65

Mode Control (CV29)

CV 29 (Mandatory)

CV 29 does a lot of things.

To use extended addresses (14 bit), Bit 5 is set to "1". When this bit is cleared (set to zero), the decoder reverts to the primary address in CV 1.

Bit	Function
Bit 7	Multifunction decoder, always reads 0
Bit 6	Reserved for future use
Bit 5	EAM, Extended Address Mode enable, 0 = Primary address in CV 1, 1 = Extended Address in CV 17/18
Bit 4	STE, Speed Table Enable, 0 = values in CVs 2, 4 and 6, 1 = Custom table selected by CV 25
Bit 3	ACK, Advanced Acknowledge mode enabled if 1, disabled if 0 (Railcom)
Bit 2	APS, Alternate Power Source enable, 0 = NMRA Digital only, 1 = Alternate power source set by CV12
Bit 1	FL (Forward Lamp) location: 0 = FL controlled by bit 4 of speed direction instruction (14 speed steps). 1 = FL controlled by bit 4 of function group 1 (28 and 128 speed step modes).
Bit 0	DIR: 0 = normal, if set to 1 the direction bit in speed/direction instruction is inverted.

When the DIR bit is set, Locomotive and headlight (FL, Forward Lamp) will run in opposite direction, useful for long hood forward operation. This bit controls the NDOT (Normal Direction of Travel)

With APS bit set, CV 12 must also be set to 1.

Speed Table

CV 66-95

Address

Short Address CV 01 (Mandatory) Long Address CV 17-18

CV 17 and 18 are paired together, the resulting in each register holding one piece of data, which when combined results in the 14 bit extended address, or four digit address.

CV 17 holds the MSB, the LSB is in CV 18. (Most Significant Bit and Least Significant Bit).

CV 29 must have bit 5 set to a value of "1". If this bit is not set, the four digit address will not work. Many systems automatically calculate the values needed for CV 17 and 18, and set CV 29 correctly to enable the four digit address.

Advanced Consist

CV 19

Bit 7 is the Consist Direction. Consist address is stored in bits 0 to 6.

Consist address run from 1 to 127. If set to 0, consist instructions are ignored. Instructions set to the primary or extended addresses are ignored.

Addresses set from 1 to 127 will assign the locomotive to that address, facing forward. Addresses from 129 to 255 result in the locomotive running backwards.

Decoder Identification

CV 07-08 (Mandatory)

CV7 holds the manufacturer's software revision codes.

CV8 holds the NMRA assigned Manufacturer code.

Reading the contents of these registers will let you determine what decoder is in the locomotive without having to open it up.

NOTE

Writing a value of 8 to CV8 will reset the entire decoder to factory defaults. Read the instructions for the decoder as not all follow this rule.

The purpose of these CVs is to allow you to get up and running quickly. These are the essential configuration variables you need to preform basic programming on a new decoder.

The NMRA Standard CV Definitions for Mobile Decoders

The Complete NMRA Standard Configuration Values, from S-9.2.2, July 2012

Multi-function Decoder Configuration Variables
CV Name	CV #	Required	Default Value	Read Only	Uniform Spec	Dynamic (Volatile)	Comments
Multi-function Decoders:
Primary Address	1	M	3		Y
Vstart	2	R
Acceleration Rate	3	R
Deceleration Rate	4	R
Vhigh	5	O
Vmid	6	O
Manufacturer Version No.	7	M		Y			Manufacturer defined version info
Manufacturer ID	8	M		Y	Y		Values assigned by NMRA
Total PWM Period	9	O
EMF Feedback Cutout	10	O
Packet Time-Out Value	11	R
Power Source Conversion	12	O			Y		Values assigned by NMRA
Alternate Mode Function Status F1-F8	13	O			Y
Alternate Mode Function Status FL, F9-F12	14	O			Y
Decoder Lock	15 - 16	O			Y
Extended Address	17 + 18	O			Y
Consist Address	19	O			Y
	20				Y		Reserved by NMRA for future use
Consist Addr Active for F1-F8	21	O			Y
Consist Addr Active for FL-F9-F12	22	O			Y
Acceleration Adjustment	23	O			Y
Deceleration Adjustment	24	O
Speed Table/Mid-range Cab Speed Step	25	O			Y
	26	O					Reserved by NMRA for future use
Decoder Automatic Stopping Configuration	27	O			Y		Under re-evaluation – see details
Bi-Directional Communication Configuration	28	O			Y		Under re-evaluation – see details
Configuration Data #1	29	M			Y		SEE NOTE 1
Error Information	30	O			Y
Index High Byte	31	O			Y		Primary index for CV257-512 00000000 - 00001111 reserved by NMRA for future use.
Index Low Byte	32	O			Y		Secondary index for CV257-512
Output Loc. FL(f), FL(r), F1-F12	33-46
Manufacturer Unique	47-64	O					Reserved for manufacturer use
Kick Start	65	O
Forward Trim	66	O
Speed Table	67-94	O
Reverse Trim	95	O
	96-104						Reserved by NMRA for future use
User Identifier #1	105	O					Reserved for customer use
User Identifier #2	106	O					Reserved for customer use
	107-111						Reserved by NMRA for future use, CV107,108: expanded Mfg. ID, CV109-111: expanded CV7
Manufacturer Unique	112-256						Reserved for manufacturer use
Indexed area	257-512						Indexed area - see CV# 31,32, Index values of 0-4095 reserved by NMRA
	513-879						Reserved by NMRA for future use
	880-891	-			Y		Reserved by NMRA for future use
Decoder Load	892	O			Y	Y
Dynamic Flags	893	O			Y	Y
Fuel/Coal	894	O			Y	Y
Water	895	O			Y	Y
SUSI Sound and Function Modules	896-1024	O			Y		See TN-9.2.3

Note 1: If any of these features are provided, then this CV is Mandatory.

Definitions

Required: Mandatory (M), Recommended (R), and Optional (O). CVs identified at Mandatory must be present to conform to the standard. Those marked Recommended the NMRA strongly encourages their implementation. Optional CVs can be included if the manufacturer wishes.

Read Only indicates a CV that is set and cannot be altered.

Uniform Specification: CVs are specific to the implementation and no uniform specification is needed. Others must be implemented in a uniform manner to maintain compatibility. If marked Yes, the CV must be implemented according to a common specification. If there is no Y in the column, the CV must be used for its designated purpose, but the actions taken by the decoder for a certain CV value can vary among decoder makers.

Dynamic: These CVs are used for Unsolicited Decoder Initiated Transmission.

Note

All Digital Decoders don't implement all the CVs, but if the function is provided the relevant CV information must be adhered to.

External Links

NMRA 9.2.2 - NMRA CV Specs and further details.

NMRA Assigned Manufacturer ID Numbers

Understanding and Using Indexed CVs Further explanation of the Index CV by QSI