Configuration Variables

DCCWiki, a community DCC encyclopedia.
(Redirected from Configuration variable)
Jump to: navigation, search

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

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.

Indexed CVs

NMRA Standards

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

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.

Mandatory and Recommended Configuration Variables

The following four CVs are Mandatory to meet the definition of a Multifunction Decoder under the NMRA DCC Standard:

  1. CV1: Primary Address
  2. CV7: Manufacturer Version Number
  3. CV8: Manufacturer ID
  4. CV29

The following CVs are Recommended:

  1. CV2: V-Start
  2. CV3: Acceleration Rate
  3. CV4: Deceleration Rate
  4. CV1:1 Packet Time-out

Meaning that it is strongly recommended that multifunction decoders implement these CVs

Standard Configuration Variables

Motor Control

CV 2, 3, 4, 23, 24, 65

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.

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.

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, often called a 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 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. Instructions set 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.

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

Decoder Identification

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

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
 Consisting
Packet Time-Out Value
11
R
 Set time to stop vehicle if DCC signal lost.
Power Source Conversion†
12
O
Y
 Values assigned by NMRA. See note regarding CV1.
Alternate Mode Function Status F1-F8
13
O
Y
 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
14
O
Y
 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
15-16
O
Y
 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
17+18
O
Y
 These two bytes form the Extended Address.
Consist Address
19
O
Y
 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.
20
Y
 Reserved by NMRA for future use
Consist Addr Active for F1-F8
21
O
Y
 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
22
O
Y
 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
23
O
Y
 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
24
O
 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
25
O
Y
 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.


26
O
 Reserved by NMRA for future use
Decoder Automatic Stopping Configuration
27
O
Y
 Under re-evaluation – See details. Used to configure which actions will cause the decoder to automatically stop.
Bi-Directional Communication Configuration
28
O
Y
 Under re-evaluation – see details
Configuration Data #1
29
M
Y
Error Information
30
O
Y
 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
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
 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
47-64
O
 Reserved for manufacturer use
Kick Start
65
O
 Specifies the amount of extra Kick that will supplied to the motor when transitioning between stop and the first speed step.
Forward Trim
66
O
 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
67-94
O
 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
95
O
 Specifies a scale factor by which a voltage drive level should be multiplied, when the controller is driving the unit in reverse.
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. 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
112-256
 Reserved for manufacturer use
Indexed area
257-512
 Indexed area - see CV# 31,32, 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.
513-879
 Reserved by NMRA for future use
880-891
-
Y
 Reserved by NMRA for future use. CVs in this range are dynamic and are used for Unsolicited Decoder Initiated Transmission.
Decoder Load
892
O
Y
Y
 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
893
O
Y
Y
 Up to 8 dynamic flags can be transmitted. Bits 0-7 are Reserved for Future Use.
Fuel/Coal
894
O
Y
Y
 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
895
O
Y
Y
 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
896-1024
O
Y
 See TN-9.2.3. For use by SUSI to define CVs for Sound and Function auxiliary modules.
Notes
†
Primary Address
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.

Note 1: CV29: If any of these features are provided, then this CV is Mandatory. If the decoder does not support a feature controlled by this, that bit must not be allowed to be set improperly, it must be set to the default.

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.

Accessory Decoder Configuration Variables

Accessory Decoders
CV Name CV # CV # (optional) Required Default Value Read Only Uniform Spec Additional Comments
Decoder Address LSB 1 513 M 1 Y LSB of 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 MSB of 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 accessory. 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 CV# 31, 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.

Technical Notes

Programming CVs 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 Compatible
Digitrax

DT400 throttle used with

    • Zephyr, Zephyr Xtra, Zephyr Express
    • Super Chief
    • Empire Builder
NCE
Compatible
Digitrax

DT402/DT500 Throttle with:

  • Zephyr, Zephyr Xtra, Zephyr Express
    • Firmware issues may prevent programming from being completed.
  • Super Chief
  • Empire Builder
NCE
  • Power Cab
    • Main or Program Track

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

Videos

There are a number of videos available regarding Configuration Variables

External Links

Retrieved from "https://dccwiki.com/w/index.php?title=Configuration_Variable&oldid=25701#Mode_Control_.28CV29.29"