Summary: A Configuration Variable is a setting stored within a Digital Command Control Multifunction or Accessory Decoder. These allow the user to set parameters such as the address to their preferences, or customize the decoder for prototypical operation or sounds.
Introduction to Configuration Variables
A Configuration Variable is a memory address in a multifunction decoder or Accessory Decoder that controls its behaviour. 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. CV29 is sometimes referred to as Mode Control.
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 or CVs are memory addresses within a decoder. They are the means for controlling the performance of a DCC decoder. The decoder's software creates and maintains these addresses.
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 a high/low bit format such as "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 "switches", each bit controlling a specific function, turning it on or off.
- CV 29 is a series of switches.
- A combination of the above. For example, CV 19 (Consist Address) works in this manner.
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. 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 Bit Switches
- Main article: Configuration Variable/BitSwitches
Use of a specific memory address allows the creation of a Bit Switch. Much like a physical switch, the bits represent an ON or OFF, determined by the value written into that bit.
By writing a binary value to a memory address, the decoders software can examine the contents of that byte to determine if a condition is True or False, and act on that. An example would be determining the addressing mode in use for a multifunction decoder.
For more detailed information see the BitSwitches page linked above.
Configuration Variable Worksheet
For convenience a page with blank tables that can be used as a worksheet to determine various CV values is located here: CV Worksheet
- Main article: Configuration Variable/Indexed Configuration Variables
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.
NMRA Basic Configuration Variable Set
The NMRA has defined a basic set of CVs that all multifunction decoders have. This ensures that interchange between various manufacturers is possible.
Mandatory and Recommended Configuration Variables
The following four CVs are Mandatory to meet the definition of a Multifunction Decoder under the NMRA DCC Standard:
The following CVs are Recommended:
Meaning that it is strongly recommended that multifunction decoders implement these CVs
Standard Configuration Variables
CV 2, 3, 4, 23, 24, 65
- Acceleration Rate
- Deceleration Rate
- Acceleration Adjustment
- Deceleration Adjustment
- Kick Start
Mode Control (CV29)
- Main article: Configuration Variable/Configuration Register 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.
CV 66-95 are the speed table, if available.
- Short Address CV 01 (Mandatory)
- Extended (Long) Address CV 17-18
- 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 extended address will not work. Many systems automatically calculate the values needed for CV 17 and 18, and then set CV 29 correctly to enable the extended address.
Advanced Consist: CV19
- Bit 7 is the Consist Direction. The Consist address is stored in bits 0 to 6.
- Consist addresses run from 1 to 127. If CV19 is set to 0, consist instructions are ignored. Speed and direction instructions sent to the primary or extended addresses are ignored when active.
- 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.
- It may be possible to control functions using individual locomotive addresses.
This CV is cleared (set to 0) when the consist is deleted, and control returned to the Primary or Extended Address.
This address is set automatically by the command station as part of the Advanced Consisting process.
Advanced Consisting may be referred to as Decoder Assisted consisting.
CVs 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 NMRA Standard CV Definitions for Multifunction Decoders
The Complete NMRA Standard Configuration Values, from S-9.2.2, July 2012
|Primary Address||Do Not Set to Zero! A value of "0" interacts with CV12, overriding CV29's APS value, resulting in a runaway. |
|Manufacturer Version No.||Manufacturer defined version info|
|Manufacturer ID||Values assigned by NMRA |
|Total PWM Period||The value of CV#9 sets the nominal PWM period at the decoder output and therefore the frequency is proportional to the reciprocal of the value. |
|BEMF Feedback Cutout||Contains a value between 1 and 128 that indicates the speed step above which the back EMF motor control cuts off. When 14 or 28 speed steps are used the LSB's of the value are truncated appropriately.|
|Packet Time-Out Value||Set time to stop vehicle if DCC signal lost. |
|Power Source Conversion†||Values assigned by NMRA. See note regarding CV1.|
|Alternate Mode Function Status F1-F8||Indicates the status of each function (F1 - F8) when the unit is operating in alternate power mode, which cannot control the functions. If a function can be controlled, then the corresponding bit is ignored. A value of "0" indicates the function is off, while a value of "1" indicates the function is on. Bit 0 corresponds to F1, Bit 7 to F8.|
|Alternate Mode Function 2 Status FL, F9-F12||Indicates the status of each function (F9 to F12, plus FL) when the unit is operating in alternate power mode, which cannot control the functions. If a function can be controlled, then the corresponding bit is ignored. A value of "0" indicates the function is off, a value of "1" indicates the function is on. FL in the forward direction is controlled by bit 0, FL in the reverse direction is controlled by bit 1. Bit 2 corresponds to F9, Bit 5 to F12.|
|Decoder Lock||Used to control decoder programming when more than one decoder is present at that address. If CV15 does not match CV16 any programming instructions are ignored.|
|Extended Address||These two bytes form the Extended Address. |
|Consist Address||Contains the seven bit Consist Address in bits 0 − 6. Bit 7 indicates direction of travel, "0" is normal, "1" is reversed from the normal detection of travel. A value of 0000 0000 indicate this unit is not part of a consist.|
|Reserved by NMRA for future use|
|Consist Addr Active for F1-F8||Defines for functions F1-F8 whether the function is controlled by the consist address. For each Bit a value of "1" indicates that the function will respond to instructions addressed to the consist address. A value of "0" indicates that the function will only respond to instructions addressed to the locomotive address. F1 is indicated by bit 0. F8 by bit 7.|
|Consist Addr Active for FL-F9-F12||Defines for function FL whether the function is controlled by the consist address. For each Bit a value of "1" indicates that the function will respond to instructions addressed to the consist address. A value of "0" indicates that the function will only respond to instructions addressed to the locomotive address. FL in the forward direction is indicated by bit 0, FL in the reverse direction is controlled by bit 1. Bit 2 corresponds to F9, while Bit 5 controls F12.|
|Acceleration Adjustment||This Configuration Variable contains additional acceleration rate information that is to be added to or subtracted from the base value contained in CV3. This is a 7 bit value (bits 0-6) with bit 7 being reserved for a sign bit (0-add, 1-subtract). In case of overflow the maximum acceleration rate shall be used. In case of underflow no acceleration shall be used. The expected use is for changing momentum to simulate differing train lengths/loads, most often when operating in a consist.|
|Deceleration Adjustment||This Configuration Variable contains additional braking rate information that is to be added to or subtracted from the base value contained in CV4. See CV23 for additional details.|
|Speed Table/Mid-range Cab Speed Step||A value between 2 and 127 shall be used to indicate 1 of 126 factory preset speed tables. A value of 0000 0010 indicates a linear curve shall be used. A value between 128 and 154 defines the 28-speed step position (1 − 26) which will define where the mid-range decoder speed value will be applied. In 14-speed mode the decoder will utilize this value divided by two. If the value in this variable is outside the range, the default mid cab speed of 14 (for 28 speed mode or 7 for 14 speed mode) shall be used as the mid speed value. Values of 0000 0000 or 0000 0001 shall indicate that this CV is not used.|
|Reserved by NMRA for future use|
|Decoder Automatic Stopping Configuration||Used to configure which actions will cause the decoder to automatically stop.|
|Bi-Directional Communication Configuration||Used to configure decoder’s Bi-Directional communication characteristics when CV29-Bit 3 is set.|
|Configuration Data #1||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).|
|Error Information||In the case where the decoder has an error condition this CV shall contain the error condition as specified by the manufacturer. A value of 0 indicates that no error has occurred.|
|Index High Byte||Primary index for CV257-512 |
|Index Low Byte||Secondary index for CV257-512|
|Output Loc. FL(f), FL(r), F1-F12||Contains a matrix indication of which function inputs control which Digital Decoder outputs. This allows the user to customize which outputs are controlled by which input commands. |
|Manufacturer Unique||Reserved for manufacturer use|
|Kick Start||Specifies the amount of extra Kick that will supplied to the motor when transitioning between stop and the first speed step.|
|Forward Trim||Specifies a scale factor by which a voltage drive level should be multiplied, when the controller is driving the unit in the forward direction.|
|Speed Table||The speed table is defined to be 28 bytes wide, consisting of 28 values for forward speeds. A digital controller that uses this table shall have at least 64 voltage drive levels and can have as many as 256 so that a smooth power curve can be constructed.|
|Reverse Trim||Specifies a scale factor by which a voltage drive level should be multiplied, when the controller is driving the unit in reverse.|
|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. Expanded Mfg. ID, with CV8=0xEE a 16-bit manufacturer ID is stored in CVs 107,108. CVs 109-111: with CV7=_____, these three CVs expand the version number feature.|
|Manufacturer Unique||CVs in this range are already being used by many manufacturers. Opening up this area officially is an attempt to legitimize what is already being done.|
|Indexed area||Indexed area - see CV# 31,32, |
|Reserved by NMRA for future use|
|Reserved by NMRA for future use. CVs in this range are dynamic and are used for Unsolicited Decoder Initiated Transmission.|
|Decoder Load||Specifies the current load of the decoder. The load is volatile and is not stored across power interruptions. Bits 0-6 indicate the value of the load, 0 indicates no load. Bit 7 indicates a positive or negative load.|
|Dynamic Flags||Up to 8 dynamic flags can be transmitted. Bits 0-7 are Reserved for Future Use.|
|Fuel/Coal||Amount of Fuel/Coal remaining before the decoder will stop the locomotive. A value of 0 indicates that the Fuel/Coal is totally consumed, 254 indicates totally full. A value of 255 indicates that this CV is not currently supported and its contents should not be transmitted.|
|Water||Water left before the decoder will stop the locomotive. A value of 0 indicates that all the water has been consumed, 254 indicates full. A value equalling 255 indicates that this CV is not currently supported and its contents should not be transmitted.|
|SUSI Sound and Function Modules||See TN-9.2.3. For use by SUSI to define CVs for Sound and Function auxiliary modules.|
Binary numerical quantities are stored such that the rightmost bit is the least significant, and the leftmost is the most significant.
- 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.
- All Digital Decoders do not implement all the CVs, but if the function is provided the relevant CV information must be adhered to.
Accessory Decoder Configuration Variables
|Accessory Decoder Configuration Variables|
|CV Name||CV #||CV # (optional)||Required||Default Value||Read Only||Uniform Spec||Additional Comments|
|Decoder Address LSB||1||513||M||1||Y||The 6 Least Significant Bits of the accessory decoder address|
|Auxiliary Activation||2||514||O||Auxiliary activation of outputs|
|Time On F1||3||515||O|
|Time On F2||4||516||O|
|Time On F3||5||517||O|
|Time On F4||6||518||O|
|Manufacturer Version Info||7||519||M||Manufacturer defined version info|
|Manufacturer ID||8||520||M||Y||Y||Values assigned by NMRA|
|Decoder Address MSB||9||521||M||0||Y||The 3 Most Significant Bits of the accessory decoder address|
|10 – 27||–||Reserved by NMRA for future use|
|Bi-Directional Communication Configuration||28||540||O||Y|
|Accessory Decoder Configuration||29||541||M1||Y||similar to CV#29; for acc. decoders|
|30||–||Reserved by NMRA for future use|
|Indexed Area Pointers||31, 32||Index High and Low Address|
|Manufacturer Unique||33 – 81||O||Reserved for manufacturer use|
|82 – 111||Reserved by NMRA for future use|
|Manufacturer Unique||112 – 128||O||Reserved for manufacturer use|
|Manufacturer Unique||129 – 256|
|Indexed Area||257-512||Indexed area: See CV31, 32; Index address values of 0-4095 reserved by NMRA|
|Manufacturer Unique||513 – 895||O||Reserved for manufacturer use|
|896 – 1024||Reserved by NMRA for future use|
Accessory Decoder Notes
The NMRA revised the Accessory Decoder CVs to recognize that while the standard reserved CVs 1 - 512, with 513-1024 being available, older accessory decoders may not have followed the standard. Manufacturers deviated from the standard for a number of reasons, such as the command station software lacking the ability to address CVs greater than 512.
The revision has relocated the CVs from 512-1024 to the 1-512 range. CVs above 512 are available for optional use, giving more space for features to be added in the future.
Accessory Decoder Configuration Variable Descriptions
- Refer to Standard S-9.2.2 for full and complete descriptions.
CV1: This contains the LSB (low order address bits). The MSB (high order bits) are stored in CV 9. Decoder and Output Addressing are supported, the accessory decoder must support one mode, and optionally the other. Default value is specified as 1. Supported Addressing types must be identified on the packaging and in the manual.
- Decoder-Address: Contains the six least significant bits of the accessory decoder's address in bits 0-5. These bits are transmitted as bits 0-5 in the first byte of the accessory decoder packet. See S-9.2.1 for more 360 information.
- Output-Address: The user places the output address, contains the address value which results from the following formula: Output Address modulus 256. (ex. Output Address mod 256, or Output Address % 256). The values contained in CV1 and 9 correspond to the bits in the Accessory Decoder packets as follows:
- Accessory-Output = (CV1 + (CV9 × 256)) − 1
- Bits 0 & 1 of the Accessory-Output are transmitted as bits 1 & 2 of byte 2 of both Accessory Decoder Control Packets. Bits 2-7 of the Accessory-Output are transmitted as bits 0-5 of byte 1 of both Accessory Decoder Control Packets. The three least-significant bits of CV9 contain the ones-complement of bits 4-6 of both Accessory Decoder Control Packets.
- See S-9.2.1 for more information on the Accessory Decoder Control Packets.
If an accessory decoder supports more than one sequential output the value in CV1 will be the first output in the series
- CV2: Bits 1-8 control auxiliary activation. A value of 0 does not activate the auxiliary, a value of 1 does.
- CV3 - CV6: Time on for functions F1-F4. A value of zero equals always on.
- CV9: MSB of address byte. See CV1
- CV28: Bi-Directional communications, see CV 29. Enabled by setting bit 0 to 1, or 0 to disable.
CV29: Accessory Decoder Configuration.
- Bit 3 controls Bi-Directional Communication.
- Bit 5: Decoder Type, 0 = Basic Decoder, 1 = Extended
- Bit 6: Addressing: Decoder Address (0) or Output Address (1)
- Bit 7: This bit determines the type of Decoder, 0=Multifunction, 1=Accessory.
- If set to 1, the decoder may ignore the two most significant bits of the CV number when in Service Mode only. This allows CV513 to become CV1, etc. This must be documented in the manual.
CV31, 32: Index Address High and Low Bytes (respectively).
- CV31 can have values from 16 to 255 for 4096 indexed pages, CV32 has the LSB, for a total of 61440 indexed pages of 256 bytes each available to the manufacturer.
Programming CVs Greater Than 255
DCC System Compatibility
This list is by no means complete. If in doubt, consult the manuals for your DCC System.
DT400 throttle used with
- Zephyr, Zephyr Xtra, Zephyr Express
- Super Chief
- Empire Builder
- Power Pro when the programming track is used.
DT402/DT500 Throttle with:
- Zephyr, Zephyr Xtra, Zephyr Express
- Firmware issues may prevent programming from being completed.
- Super Chief
- Empire Builder
- Power Cab
- Main or Program Track
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
- Set CV96 to the hundreds digit of the CV number: Range is 0-9.
- Set CV97 to the units and tens digits of the CV number: Range is 0-99.
- 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.
- Divide 300 by 100, result is 3.01
- 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.
|96||3||This is the hundreds value|
|97||1||The tens and units value|
|99||5||The desired value to be written to CV300|
- Decoder - All about various decoders.
- Decoder Reset
- Binary - More about the binary system used by digital devices.
- Video - CV Programming and Myths
- List of NMRA Standards
There are a number of videos available regarding Configuration Variables
- CV Shortcuts Part One
- CV Shortcuts Part Two
- CV Shortcuts Part Three
- CV Programming Myths
- CV Programming, DCC Myths and More with SoundTraxx
- What Is a CV?
- NMRA CV Specs and further details.
- Understanding and Using Indexed CVs Further explanation of the Index CV by QSI
- Bits 0-6 contain an address with a value between 1 and 127. Bit seven must have a value of "0". If the value of Configuration Variable #1 is "00000000" then the decoder will go out of NMRA digital mode and convert to the alternate power source as defined by Configuration Variable #12. This setting will not affect the Digital Decoder's ability to respond to service mode packets (see S 9.2.3). The default value for this Configuration Variable is 3, if the decoder is not installed in a locomotive or other unit when shipped from the manufacturer.
- CV8 shall contain the NMRA assigned id number of the manufacturer of this decoder. The currently assigned manufacturer ID codes are listed in Appendix A of this Standard. The use of a value not assigned by the NMRA shall immediately cause the decoder to not be in conformance to this Standard. The CV shall be 85 implemented as a read-only value, which cannot be modified.
- The value of CV#9 sets the nominal PWM period at the decoder output and therefore the frequency is proportional to the reciprocal of the value. The recommend formula for PWM period should be: PWM period (uS) = (131 + MANTISSA x 4)x 2 EXP ,Where MANTISSA is in bits 0-4 bits of CV#9 (low order) and EXP is bits 5-7 for CV#9. If the value programmed into CV-9 falls outside a decoder's capability, it is suggested (but not required) that the decoder "adjust" the value to the appropriate highest or lowest setting supported by the decoder.
- Contains the maximum time period that the decoder will maintain its speed without receiving a valid packet. See S 9.2.4 Section C for further information.
- The Extended Address is the locomotives address when the decoder is set up for extended addressing (indicated by a value of "1" in bit location 5 of CV#29). CV#17 contains the most significant bits of the two byte address and must have a value between 11000000 and 11100111, inclusive, in order for this two byte 135 address to be valid. CV 18 contains the least significant bits of the address and may contain any value.
- 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 245 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.
- Contains a matrix indication of which function inputs control which Digital Decoder outputs. This allows the user to customize which outputs are controlled by which input commands. The outputs that Function FL(f) controls are indicated in CV #33, FL (r) in CV#34, F1 in CV #35, to F12 in CV#46. A value of “1” in each bit location indicates that the function controls that output. This allows a single function to control multiple 260 outputs, or the same output to be controlled by multiple functions. CVs 33-37 control outputs 1-8. CVs 38-42 control outputs 4-11 CVs 43-46 control outputs 7-14. The defaults is that FL (f) controls output 1, FL (r) controls output 2, F1 controls output 3 to F12 controls output 14. The lowest numbered output is in the LSB of the CV, as shown in the table below.
- A total of 65536 pages is in the Indexed Area, each 256 bytes in length. The first 4096 pages are reserved for NMRA use. The remaining 61440 pages are available to manufacturers for their own purposes. For the manufacturer that needs only 256 additional bytes of CVs, he can simply specify a base address in CV#31-32 and not respond if that address is not enabled without actually paging data.