Configuration Variable

Summary: A Configuration Variable is a setting stored within a Digital Command Control Decoder. These allow the user to set various parameters such as the address to their preferences, or to customize the decoder for prototypical operation or sounds. Some CVs are mandated by the NMRA DCC Standard, others are optional. As decoders have grown in complexity, so have their configuration variables.

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:

1. The Master CV holds broadly related functions, such as lighting effects or horn/whistle parameters.
2. Only the Master CV is programmed to control a given function when using indexed CVs.
3. The same Primary and Secondary indexes control access to the Master CV, regardless of which Master CV is being accessed.
4. 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 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

1. Use the built-in serial interface and JMRI
2. Program on the Main: Set CV 31 and 32 first
   1. 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.
      1. This does not apply to the Power Cab. There is more information on NCE's Zendesk.

NMRA Basic Configuration Variable Set

Multifunction Decoders

The NMRA has defined a basic set of CVs that all multifunction 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). The default value for CV29 is 6 (in both decimal and hexadecimal form). This indicates bits 2 and 3 are enabled (1), while all other bits hold a value of 0.

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). If this switch is set to 1, the 28/128 speed step mode is active, 0 = 14 steps.
Bit 0	DIR: 0 = normal, if set to 1 the direction bit in speed/direction instruction is inverted. 0 = NDOT Forward

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.

Setting CV 29

This is a more advanced subject, and is for information only. Many DCC systems have include the capability to set CV29 correctly when setting a Primary or Extended Address. Other bits may need to be set manually. For example, subtracting 4 from the default value will set the decoder for NMRA DCC operation only.

CV29 Default

Bit Position	Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
Value	2^7	2^6	2^5	2^4	2^3	2^2	2^1	2^0
Decimal Value	128	64	32	16	8	4	2	1
Default Binary Value	0	0	0	0	0	1	1	0
Result (Decimal)	0	0	0	0	0	4	2	0
Sum	6

CV29 Extended Address Mode Enabled

Bit Position	Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
Value	2^7	2^6	2^5	2^4	2^3	2^2	2^1	2^0
Decimal Value	128	64	32	16	8	4	2	1
Default Binary Value	0	0	1	0	0	1	1	0
Result (Decimal)	0	0	32	0	0	4	2	0
Sum	38
Sum, Hex	$26

The default value for CV29 is 6, in both decimal and hexadecimal numbers. As shown in the examples, adding a value of $20 to the default value in CV29 allows extended addresses. Subtracting $20 from the value in CV29 turns it off. In many cases this will be unneeded, as the command station software will set CV29 for a Primary or Extended address automatically.

If NMRA DCC Mode only, with extended address mode is desired, the required value would be 6 - 4 + 32 = 34.

NDOT: If the value in CV29 is an even value, NDOT has not be enabled. If odd, NDOT is enabled. To reverse the direction of the locomotive using NDOT, you just add or subtract 1, depending on the CV's value being even or odd.

Speed Table

CV 66-95 are the speed table, if available.

Address CVs

Short Address CV 01 (Mandatory) Extended (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: CV19

• Bit 7 is the Consist Direction. Consist address is stored in bits 0 to 6.
• Consist address run from 1 to 127. If CV19 is 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.

This CV is cleared (set to 0) when the consist is deleted.

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 Multifunction 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		Do Not Set to Zero! A value of "0" interacts with CV12, overriding CV29's APS value, resulting in a runaway.
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
BEMF Feedback Cutout	10	O
Packet Time-Out Value	11	R
Power Source Conversion	12	O			Y		Values assigned by NMRA. See note regarding CV1.
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		These two bytes form the Extended Address.
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 do not implement all the CVs, but if the function is provided the relevant CV information must be adhered to.

Technical Notes

Programming CV Greater Than 255

Some DCC systems manufactured by Digitrax and NCE cannot program CVs greater than 255.

DCC System Compatibility

This list is by no means complete. If in doubt, consult the manuals for your DCC System.

Not Compatibile

Digitrax

• DCS51 Zephyr Xtra
• DT400 throttle used with
  • Zephyr or Zephyr Xtra
  • Super Chief
  • Empire Builder

NCE

Power Pro when the programming track is used.

Digitrax

• DT402 Throttle with:
  • Zephyr or Zephyr Xtra
  • Super Chief
  • Empire Builder

NCE

• Power Cab
  • Main or Program Track
• Power Pro
  • Programming with OPS mode on mainline.

ESU Decoders

With a DCC system that does not allow programming CVs greater than 255, ESU implemented a programming process. This method can be employed on either a program track or the mainline with any DCC system and can program CVs from 255-511 in sequence. Digitrax users: Use "DIR" or "Pd" mode for all CV programming with ESU decoders.

ESU Programming Method

1. Set CV96 to the hundreds digit of the CV number: Range is 0-9.
2. Set CV97 to the units and tens digits of the CV number: Range is 0-99.
3. Set CV99 to the desired value of the CV that you are programming: 0-255.

When CV99 is set, values in CV 96, 97, and 99 are reset to 0. Another CV above 255 can be immediately programmed, another CV, or exit programming mode.

Example Program CV301 to 5.

1. Divide 300 by 100, result is 3.01
2. The fraction is 0.01, which when multiplied by 100 results in a value of 1

To visualize this easily, when the address is divided by 100, the whole number (integer) is the CV96 value, and the number to the right of the decimal is the value for CV97.

CV	Value	Notes
96	3	This is the hundreds value
97	1	The tens and units value
99	5	The desired value to be written to CV300

See Also

• Decoder - All aboout various decoders.
• Binary - More about the binary system used by digital devices.

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