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.
Contents
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.
Multifunction decoder, always reads 0 | |
Reserved for future use | |
EAM, Extended Address Mode enable, 0 = Primary address in CV 1, 1 = Extended Address in CV 17/18 | |
STE, Speed Table Enable, 0 = values in CVs 2, 4 and 6, 1 = Custom table selected by CV 25 | |
ACK, Advanced Acknowledge mode enabled if 1, disabled if 0 (Railcom) | |
APS, Alternate Power Source enable, 0 = NMRA Digital only, 1 = Alternate power source set by CV12 | |
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). | |
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 Decoders: | |||||||
Primary Address | |||||||
Vstart | |||||||
Acceleration Rate | |||||||
Deceleration Rate | |||||||
Vhigh | |||||||
Vmid | |||||||
Manufacturer Version No. | Manufacturer defined version info | ||||||
Manufacturer ID | Values assigned by NMRA | ||||||
Total PWM Period | |||||||
EMF Feedback Cutout | |||||||
Packet Time-Out Value | |||||||
Power Source Conversion | Values assigned by NMRA | ||||||
Alternate Mode Function Status F1-F8 | |||||||
Alternate Mode Function Status FL, F9-F12 | |||||||
Decoder Lock | |||||||
Extended Address | |||||||
Consist Address | |||||||
Reserved by NMRA for future use | |||||||
Consist Addr Active for F1-F8 | |||||||
Consist Addr Active for FL-F9-F12 | |||||||
Acceleration Adjustment | |||||||
Deceleration Adjustment | |||||||
Speed Table/Mid-range Cab Speed Step | |||||||
Reserved by NMRA for future use | |||||||
Decoder Automatic Stopping Configuration | Under re-evaluation – see details | ||||||
Bi-Directional Communication Configuration | Under re-evaluation – see details | ||||||
Configuration Data #1 | SEE NOTE 1 | ||||||
Error Information | |||||||
Index High Byte | Primary index for CV257-512
00000000 - 00001111 reserved by NMRA for future use. | ||||||
Index Low Byte | Secondary index for CV257-512 | ||||||
Output Loc. FL(f), FL(r), F1-F12 | |||||||
Manufacturer Unique | Reserved for manufacturer use | ||||||
Kick Start | |||||||
Forward Trim | |||||||
Speed Table | |||||||
Reverse Trim | |||||||
Reserved by NMRA for future use | |||||||
User Identifier #1 | Reserved for customer use | ||||||
User Identifier #2 | Reserved for customer use | ||||||
Reserved by NMRA for future use, CV107,108: expanded Mfg. ID,
CV109-111: expanded CV7 | |||||||
Manufacturer Unique | Reserved for manufacturer use | ||||||
Indexed area | Indexed area - see CV# 31,32, Index values of 0-4095 reserved by NMRA | ||||||
Reserved by NMRA for future use | |||||||
Reserved by NMRA for future use | |||||||
Decoder Load | |||||||
Dynamic Flags | |||||||
Fuel/Coal | |||||||
Water | |||||||
SUSI Sound and Function Modules | 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.
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.
- Understanding and Using Indexed CVs Further explanation of the Index CV by QSI