OpenDCC Z1 configuration using Special Options (SO)

    OpenDCC can be flexibly adjusted to personal user preferences during compilation as well as during runtime.
  • Possible adjustments and settings to be considered already during compilation usually are defined as parameters within the config.h. Those parameters comprise, for instance, the internal memory size, command lists and the overall support for specific functions and protocols like Intellibox, Lenz, S88, and DMX. For more details and examples refer to config.h and config.h.
  • Each selected configuration provides for additional customizations which can be set and modified during operation using internal, persistent variables kept in the commands stations EEPROM. However, modification of those variables usually require a restart of the OpenDCC command station in order to make effective the changes.

    The variables kept in EEPROM can be set and modified using one of the following different ways:
    1. Preset during compilation. The EEPROM contents is defined by config.h and config.c.
    2. Access using command SO (P50X-ASCII-Mode) or XSOset (0xa3) respectively XSOget (0xa4) in P50X-Binary-Mode.
    3. Access using Xpressnet-commands 0x23 0x28 and 0x23 0x29 to read and write the command stations' CVs. This is supported by respective menues available on the OpenDCC throttle.
    4. Access by programming the CVs of a "virtual" loco (V0.14 and higher). This requires to press the green "GO" button during startup of the command station to enter the configuration mode. Once in that mode, all programming commands (DCC bytewise) are routed to the command station, i.e. the internal EEPROM variables. (See also: Configuration using Trainprogrammer using a PC)
    Note that the OpenDCC configuration is extremely well integrated in rocrail which includes a respective configuration menu just for OpenDCC.

List of Special Options (SO)

    In the following table all default settings of version V0.15 are marked with an '*'.
    Defaults can be easily altered and are most likely subject to changes so please make sure to check all settings prior to use.

    SO# SO-Name Description
    0 Version A byte value to be interpreted as decimal, e.g. 0x0E = Version 0.14
    1 Baud rate the baud rate default. The values are consistent with the Lenz interface:
    baud rate, codes during write:
     0: 9600 baud
     *1: 19200 baud
     2: 38400 baud
     3: 57600 baud
     4: 115200 baud
     5: 2400 baud
     6: 4800 baud
    Note:
    When reading the SO using command XSOget (0xa4) the SO had to be recoded to Intellibox due to reconfiguration of the interface after reading this SO using Traincontroller. In this special case the baud rate must be set according to Intellibox:
    baud rate, codes during read using p50xb:
     0: 2400 baud
     1: 4800 baud
     2: 9600 baud
     3: 19200 baud
     4: 38400 baud
     5: 57600 baud (maybe - not yet tested)
     6: 115200 baud (maybe - not yet tested)
    Attention: This setting will become effective (as most of the other settings as well) only after a command station restart!
    2 OpenDCC Mode This CV is used to distinguish different configurations and properties of OpenDCC. (read only)
    BitMeaning
     0 0: OpenDCC standard version, atmega32
    1: OpenDCC Xpressnet version, atmega644p
     3..1 reserved
     4 0: Standard DCC
    1: DCC Fast Clock supported. (see CV26)
     6,5 Loco DB type (see below):
    00 = Loco data as 16-Bit values {Format, Addr}
    01 = Loco data as 16-Bit values + Pict-ID + Name {Format, Addr, Pict-ID, Name[10]}
    10, 11 = reserved
     7 reserved
    3 Virtual decoder low together with SO 4 provides a 16-Bit value
    4 Virtual decoder high 16-Bit value: when accessing a switching decoder having this address the command will not be put on the track as DCC-command but will be used for initiation of internal transfer of the loco database to Xpressnet.
    Preset to: 2040 (equals the most available address)

    Note: up to version 0.22 this variable was used to trigger the DMX output in case DMX_ENABLED had been compiled in. Access to a decoder with an address larger than the one stored here was used to trigger a DMX-macro rather than put on the track as DCC-command. DMX-macro therefore were virtual decoders available, see also Raumlichtsteuerung.
    Setting to 0xffff disables the feature completely.
    Preset to: 899
    5 Version A byte value to be interpreted as decimal, e.g. 0x0E = Version 0.14
    This is the same value as in CV0 (mirrored) to allow simplification of read-access, if required.
    6 CTS-Usage 255, CTS is unused - required for railware compatibility. Railware would like to see a value of 20 here, however OpenDCC wants to use CTS for communication rather than to misuse it for status reports.
    7 S88 Mode
    Bit 0:  0:  do not read external sensors
    *1:  standard S88-operation; read external sensors
    Bit 1: *0:  no turnout sensors
     1:  turnout sensoring enabled. Respective S88 bits are triggered by turnout sensors. See S0 17 for details on the meaning of sensor bits. The S88 bit number corresponds to the ID of the turnout added an offset as given by SO 16.
    Settings of S88 Mode need to consider that turnout sensoring must not interfere with reading of other sensors. In case both are active, the offset in SO 16 must be set to a value great enough to ensure that turnout sensors have addresses beyond the address space of other S88 sensor modules.
    8 S88 Autoread number of bytes that are read automatically by S88. That number must equal the sum of SO 9, SO 10 and SO 11. OpenDCC does not make any use of this (OpenDCC always does autoread), but railware wants to know :-). Max value is 128 bytes. (see also S88_SIZE_MAX in config.h)
    9 S88 modules 1 number of bytes on S88-line 1 (X10 respective X22, "left", seen from front). Usual modules have 2 bytes. In case there are 5 modules (16 Bit each) connected, a value of 10 is expected here.
    This CV can be read by X88PGet (0x9C-0x01) and can be written by X88PSet (0x9D-0x01).
    default: 2
    10 S88 modules 2 number of bytes on S88-line 1 (X8 respective X23, "middle"). Usual modules have 2 bytes. In case there are 5 modules (16 Bit each) connected, a value of 10 is expected here.
    This CV can be read by X88PGet (0x9C-0x01) and can be written by X88PSet (0x9D-0x01).
    default: 2
    11 S88 modules 3 number of bytes on S88-line 1 (X9 respective X24, "right", seen from front). Usual modules have 2 bytes. In case there are 5 modules (16 Bit each) connected, a value of 10 is expected here.
    This CV can be read by X88PGet (0x9C-0x01) and can be written by X88PSet (0x9D-0x01).
    default: 2
    12 Turnout command inversion
    Bit 0:  0:  no inversion on Lenz or Xpressnet
    *1:  switch red/green on Lenz or Xpressnet
    Bit 1: *0:  no inversion on Intellibox p50x
     1:  switch red/green on Intellibox p50x
    Background: There are different interpretations of the DCC-standard(!!!) by Intellibox and Lenz. This option eliminates this at the level of the command station rather than forwarding the issue to the control program.
    13 Turnout command repetition Number of times each turnout command is repeated on the main track. Preset: 2
    14 Turnout cycle time After this amount of time (in steps of 50ms) the turnout coils will be shut off. OpenDCC does never shut off coils (this is up to the decoders). Shut off commands from the host will be forwarded and might be used to sensor turnout position. This SO is used by railware, that is the reason why it is there. Preset : 100
    15 Power-on status Denotes the protocol in Intellibox mode:
    *0:  Normal mode (P50/P50X mixed)
     1:  P50X-Only Mode
    16 Offset for turnout sensoring In case turnout sensoring is enabled, S88 event are generated for turnouts not switched correctly. The events consider the offset defined here before writing the S88 buffer. Offset is in bytes.
    Example: Turnout 10 not switched, Offset be 6.
    => Sensor bit 58 is set (58 = 10 + 6*8). Note that the S88-buffer holds up to 1024 bits, therefore not all possible turnout addresses might be available for feedback.
    Preset : 0
    17 Turnout sensoring mode This SO defines how turnout sensoring is reported:
     0:  Corresponding S88 Bit turns 1 in case confirmation for last turnout switch command has been received (positive feedback). There is available one bit per turnout, only the last switch command can be confirmed.
     1:  Corresponding S88 Bit turns 1 in case the last switch command was not confirmed. (error bit).
    *2:  Corresponding S88 Bit reflects turnout position:
    1: turnout diverting (red)
    0: turnout straight (green)
     3:  Two bits per turnout are available:
    BitsMeaning
    00:Turnout about to switch
    01:Turnout diverting (rot)
    10:Turnout straight (green)
    11:invalid state, feedback failure
    Attention: Not implemented yet.
    Currently only SO 17 = 0,1 or 2 supported
    18 Extended Resets This SO defines if and by what account the number of reset packages is increased prior to a programming command:
     0:  Number of packages according to NMRA-standard are sent.
     1-10:  Additional number of reset packages to be sent. Preset : 3
    Background: Some decoders (like Lokpilot V.2) need some delay after reading a CV before they will accept read commands for the next CV. As a result, when reading blocks of CVs some requests are not responded in time leading to lost, unexpected or false CV values read. Consequently, checksum tests will then fail.
    19 Extended Program Commands This SO defines if and by what account the number of programming packages is increased:
     0:  Number of packages according to NMRA-standard are sent.
     1-10:  Additional number of programming packages to be sent. Preset : 3
    Background: Some decoders (like older Lenz/Roco) take their time in confirming programming commands. Using NMRA-conforming Timing might result in OpenDCC not waiting long enough for a receipt, thus resulting in incorrect values read from the CV. (see also the FAQ of Uhlenbrock (in German only)
    When using NMRA-conforming decoders SO 18 and S019 may be set to 0; setting other values lead to negligible delays in programming but does not harm at all.
    20 PoM (Programming on main) repetition This SO defines how often a PoM-command is repeated.
    Preset : 3 (NMRA requires 2)
    21 Speed repetition This SO defines how often a Speed-command is repeated. Preset : 3.
    Denotes immediate repetitions to be sent. There is implemented on top a cyclic refresh of all locos in case no new commands have been sent to them.
    In case too many locos are queued, the loco with the smallest repetition counter remaining is ignored. This allow for dynamic adaption of OpendDCC in case of heavy traffic.
    22 Function repetition This SO defines how often a Function-command is repeated. Preset : 0.
    Denotes immediate repetitions to be sent. There is implemented on top a cyclic refresh of all locos in case no new commands have been sent to them.
    24 Preset DCC Format This SO defines the format used to address locos.
     0:  DCC with 14 speed steps
     1:  reserved (DCC with 27 speed steps, not implemented)
     *2:  DCC with 28 speed steps
     3:  DCC with 128 speed steps (126 to be exact)
    Usually, PC applications request information from the command station on how to address the loco. OpenDCC reports back all locos using the above format. Exceptions can be defined for each loco using XLokCfgSet or by setting CV40+ (see additional tables below).
    It is recommended to use 28 speed steps - 128 speed steps cause less performance and are sometimes not considered by the applications, for instance, TC makes use of 50 speed steps, only.
    25 Preset BiDi (railcom) This SO defines whether OpenDCC generates the cutout for NMRA-BiDi (RailCom™)
    Bit: Meaning
     0:  *0: no Cutout
    1: Cutout
     1:  0: no IdNotify commands
    1: Every second an IdNotify command is sent.
     2:  0: no AccQuery commands
    1: Every second an AccQuery command is sent.
    The cutout is generated 30µs after the last bit of the preceding message and lasts 434µs. During cutout both DCC-outputs are shortcut. Following cutout 13 bits of preamble are generated. In case no cutout is generated 14 bits of preamble are generated.
    26 Preset Fast Clock This SO defines if and with what acceleration factor a modelrail clock is generated by OpenDCC (DCC FAST CLOCK). The time is generated as DCC message or Xpressnet message. Those messages are proprietary extensions of the standard and have been sent in for comments already.
    Value Meaning
     0:  no DCC FAST CLOCK generated
    1-31 Clock will be accelerated by the factor given.
    >31 reserved
    The modelrail time is sent as DCC message each virtual minute. In case the command station is in HALT, STOP, or programming mode, no message is issued. The message is handle as a function command with low priority, thus enqueued in a low-priority queue. It can be slightly delayed in case a lot of loco-commands are sent at the same time.
    Preset : 8
    29 Xpressnet Feedback Mapping This SO defines how turnouts and sensors are handled when read by Xpressnet. Due to protocol restrictions a distinction is required.
     0:  Switch decoder (turnouts) with an address < 256 are handled completely with read command and broadcast nmessage on Xpressnet. S88 sensors are reported using broadcast starting at address 65 (Bit address 513).
     1:  All read requests are reported as sensors.
     2:  All read requests are reported as switch decoders.

    Note: Command station only assigns addresses and status bits used by the commands according to the settings above. The commands themselves are not affected. In case turnout 257 is switched in mixed-mode, the respective command is forwarded and most likely interferes with the addresses of other sensors.
    30 Timing S88 This SO defines the length of pulses on S88-bus. The unit is 10µs; when reading the S88-bus a pulse is generated with the High and Low time defined here. Default 2 translates to 20µs High and 20µs Low.
    Background: Some modules are implemented using a processor and might not be capable to support fast reading. For instance, a value of 2 turned out to be too fast for module of railway-lauf.de. For details see also S88-N
    For performance reasons, the timing should not be set too generously. They are implemented by busy-waiting and therefore impact OpenDCC throughput.
    31 S88 turnout-sensors This SO defines the number of bytes on virtual S88 line turnout sensors. A set of 8 sensors (represented by a bit each) makes up a byte, so the highest available turnout address divided by 8 is to be entered here. Note that the S88 buffer has a limited capacity of 1024 bits so not all possible turnout addressed might be used for sensoring.
    This option also may be read by command X88PGet (0x9C-0x04) and written by command X88PSet (0x9D-0x04).
    Preset : 0

    General statements on S88 feedback bits:
    S88 feedback bits in OpenDCC may origin from 5 source: 3 real S8 hardware lines, the virtual line for turnout sensoring and external messages from xpressnet occupancy devices.
    S88 hardware:The existing hardware lines are evaluated sequentially and set the respective bits.
    turnout sensoring:Bits from the turnout sensoring line are added considering the offset as defined in SO 16.
    xpressnet messages:These messages bring their offset with them (the offest ist set up locally) and they put in the buffer according to this offset.
    The sum of S88 hardware + SO 31 is reported back when issuing command X88PGet (0x9C-0x00). In case there has been set a number of sensors bigger than that sum using command X88PSet (0x9D-0x00) that number is reported back instead.
    32 Total amount of feedback bits given in bytes, the S88 buffer has a limited capacity of 1024 bits, therefore this value has a valid range from 0..128.

    default: 0

    Notes:
    If there are no sources for feedback bytes outside the command station, then the internally used total amount is calculated from the sum of s88 hardware and turnout feedback. In this case, nothing needs to be set here! But if there are external sources for feedback bits (like an xpressnet occupancy detector), then the command station must be instructed to reserve feedback bits for these external messages. Use this SO to define the overall range of feedback bits. (contained in V0.23.6 or later, only XP version)
    33 I2C available OpenDDC does not honor connected I2C-Device (for instance Maerklin Keyboard), so a respective request from railware will be always answered with a value of 0.
    34 Switchoff time (shortcut) main This SO defines the time OpenDCC waits after detection of a short on the main before it shuts down power.
    Unit is 5ms; Preset : 6 (calculates to 30ms).
    35 Switchoff time (shortcut) programming This SO defines the time OpenDCC waits after detection of a short on the programming track before it shuts down power.
    Unit is 5ms; Preset : 8 (calculates to 40ms).
    36 External Shutdown enabled This SO defines whether OpenDCC may be shutdown externally using Ctrl-In.
    *0: no external switchoff
    1: in case a voltage of more than 5V is detected on Ctrl-In main track power will be switched off. This applies to standard mode only, in programming mode, voltage on Ctrl-In is ignored.
    After switchoff, the command station remains in that mode until released by PC or by the command stations front panel push-buttons.
    When shutdown, Ctrl-Out will be activated allowing for open-collector connections with other units.
    Note : This feature won't work in parallel with either turnout sensoring or DMX due to the fact that Ctrl-In and Ctrl-Out cannot be used for more than one purpose.
    37 External Shutdown downtime This SO defines the interval the command station ignores external shutdown requests after startup.

    In case the OpenDCC switched status from OFF to ON, it might be necessary to wait for some moments until an external shutdown has been reset. If not waiting, a previously issued shutdown request, e.g. issued by a shutdown booster, may still be active and result in an immediate shutdown. The command station therefore should ignore shutdown request after start for a defined amount of time.
    Unit: 5ms , Preset : 6 (calculates to 30ms of downtime)
    (available since V01.17 / XP: V0.21)
    38 Power Up Mode If = 0, OpenDCC will power-up with track output disabled. If = 1, OpenDCC Z1 will enable track output at power up. (available im FW 0.23.11 or later)
    Preset : 0
    39 Serial number This SO may be used to define a serial number, so the command station can be uniquely identified. No further use.
    Preset : 1

Loco decoder format

    Usually, PC applications request information from the command station on how to address the loco. OpenDCC reports back all locos using the format as defined by SO 24 (see table above). Exceptions can be defined for each loco using XLokCfgSet or by setting CV40+ (see additional tables below).
    It is recommended to use 28 speed steps - 128 speed steps cause less performance and are sometimes not considered by the applications, for instance, TC makes use of 50 speed steps, only.

    Loco parameters OpenDCC (Atmega32)
    SO# SO-Name Description
    40 Alternate loco format (low)
    loco #1    		 Together with SO 41 forms a 16 bit value
    41 Alternate loco format (high)
    loco #1    		 Together with SO 40 forms a 16 bit value, that get interpreted as follows:
    Bit: Meaning:
    0-13 Address of loco that uses an alternate format
    14,15 00 = DCC14
    01 = DCC27 (not impl.)
    10 = DCC28
    11 = DCC128
    It is highly recommended to use command XLokCfgSet (0x86), since this includes OpenDCC taking care of those values automatically.
    42-43 next loco
    [...] 64 SO pairs in total


    The loco database on OpenDCC including Xpressnet also contains a loco name and a Picture ID defining a loco picture associated with the loco.
    Loco parameters OpenDCC_XP (Atmega644p)
    SO# SO-Name Description
    40 Alternate loco format (low)
    loco #1    		 Together with SO 41 forms a 16 bit value
    41 Alternate loco format (high)
    loco #1    		 Together with SO 40 forms a 16 bit value, that get interpreted as follows:
    Bit: Meaning:
    0-13 Address of loco that uses an alternate format
    14,15 00 = DCC14
    01 = DCC27 (not impl.)
    10 = DCC28
    11 = DCC128
    It is highly recommended to use command XLokCfgSet (0x86), since this includes OpenDCC taking care of those values automatically.
    42-43 Pict-ID ID of picture associated with loco; SO 42 keeps LowByte, CV 43 HighByte
    (available since V0.22)
    44-53 Loco name 8-bit ASCII value
    54-67 next loco
    [...] 64 loco records in total

Important Compiler-Options

  • #define PARSER
    INTELLIBOX or LENZ: defines Host-protocol, Intellibox is default.
  • #define SHORT_TURNOFF_TIME
    15ms, time until short-cut power-off is activated. Works in addition to current limitation.
  • #define DMX_ENABLED
    0: no DMX (default), 1: include code for DMX
  • #define STORE_TURNOUT_POSITIONS
    0: turnout positions are not saved
    1: turnout positions are saved (default).
  • #define TURNOUT_FEEDBACK_ENABLED
    0: standard S88-operation (default)
    1: additional code, allowing for turnout sensoring (max. 1024 is activated)
  • #define TURNOUT_FEEDBACK_ACTIVATED
    0: turnout sensoring not activated.
    1: turnout sensoring activated.
  • #define DCC_DEFAULT_FORMAT
    DCC14
    DCC28(default)
    DCC128
    when addressing a loco this format is to be used
  • #define DCC_FAST_CLOCK
    0: 'normal' OpenDCC
    1: DCC Fast Clock support
  • #define XPRESSNET_ENABLED
    0: no Xpressnet code
    1: Xpressnet extension, includes Handling of both Interfaces (PC and Xpressnet) in parallel.
  • #define LOCO_DATABASE
    NAMED: Database with address, loco name and speed steps. LOK_NAME_LENGTH denotes number of characters.
    UNNAMED: Database with address and speed steps.
  • #define LOCO_DATABASE_XMT
    0: Transmission of Loco Database using LOCXMT command.
    TRAINCTRLR: Transmission of Loco Database also using turnout command address 2040 (virtual decoder).