The DCC decoder core

Direct links:

• AP_DCC_Library: dcc.input()
• RSBus library: RSbusConnection
• Common Hardware Functions: decoderHardware.init() and decoderHardware.update()
• Configuration Variables: List of CVs, cvValues.init(), cvValues.read() and cvValues.write()
• CvProgramming: cvProgramming.processMessage(...)
• LEDs: BasicLed, FlashLed, DCCLed
• Buttons: DccButton, ToggleButton
• Timers: DccTimer
• Relays: DccRelay
• Pin assignments: boards.h

Purpose

Implements the common core functions and objects needed by DCC decoders, including the support for Configuration Variables (CVs) and possible feedback via RS-Bus messages. It builds upon the AP_DCC_library and the RSBus library.

The DCC decoder core initialises the DCC and RS-Bus hardware. The Arduino pins and the USART that are used are taken from boards.h, but the sketch may overwrite any of them. This makes it possible to use boards that are not listed in boards.h, and to leave out hardware that a particular decoder does not have, such as the RS-Bus, the onboard LED or the programming button.

The core functions handle most of the Programming on the Main (PoM) and Service Mode (Programming track) messages and support Configuration Variables (CVs) for different kinds of decoders; these CVs can be remotely accessed via SM and PoM. A speciality is that PoM feedback messages will not be sent via RailCom, but via the RS-Bus using address 128. Decoders without the RS-Bus can still be programmed via PoM, but cannot return any values. Reading CVs from such a decoder requires the programming track. Dedicated MAC programs are available that use this setup to configure these CVs; these programs can be downloaded from:

• https://github.com/aikopras/Programmer-Decoder-POM
• https://github.com/aikopras/Programmer-GBM-POM

If the decoder has a programming button and the user pushes it, the core functions respond by initialising the decoder's DCC and/or RS-Bus addresses based on the next DCC address that is received. The core functions provide an onboard LED object, to signal events to the user, and an onboard button object, to allow the user to configure a new address.

The library has been tested on traditional ATMega processors, such as the ATMega 16A, ATMega 328 (UNO, Nano) and ATMega2560 (Mega), but also on the newer MegaAVR processors, such as 4808 (Thinary), 4809 (Nano Every), the AVR128DA and megaTinyCore. For the design of new boards the use of these newer processors is recommended. Note that dedicated "boards" may need to be installed in the Arduino IDE to support these processors, such as MightyCore, MegaCore, MegaCoreX and DxCore. The mapping between external (DCC and RS-Bus) signals and Arduino pin numbers is for many boards defined in the boards.h file, but can also be provided by the sketch that uses this library. For processors that boards.h does not list, such as the ATtiny series, the sketch has to do so.

---

Using the DCC Decoder Core

The only library file that needs to be included by the main sketch is AP_DCC_Decoder_Core.h. This header file includes the following header files and libraries: boards.h, CvValues.h, AP_DCC_library, RSbus, AP_DccButton, AP_DccLED and AP_DccTimer. Instead of AP_DCC_Decoder_Core.h, it is also possible to include individual header files if limited functionality is needed only.

DCC decoder objects and classes

The following objects and classes become available to the user sketch:

• decoderHardware (class: CommonDecHwFunctions): initialises the decoder hardware: the DCC interface, the RS-Bus interface, the onboard LED and the programming button. Which Arduino pins and which USART are used is determined by a number of attributes; these are filled from boards.h, but the sketch may overwrite them before calling init(). Setting an attribute to PIN_UNDEFINED tells the core that this decoder does not have that piece of hardware. Provides two functions that must be included in the user sketch: init() and update().

• dcc (class:Dcc): the Dcc class informs the main sketch which kind of DCC command has been received. The main loop of the user sketch should call dcc.input() to check if a new DCC message is received. If a new DCC message is received, the dcc.cmdType should be inspected to determine the kind of DCC command. Three main command types are possible: accessory command, loco (multi-function) command or CV access (POM, SM) command. The Dcc class is defined as part of the AP_DCC_library.

  • accCmd (class: Accessory): if dcc.cmdType is of type MyAccessoryCmd, additional information, such as the turnout and position, is provided by the accCmd object.
  • locoCmd (class: Loco): if dcc.cmdType returns any of the loco types (such as MyLocoSpeedCmd or MyLocoF0F4Cmd), additional information is provided by the locoCmd object.
  • cvCmd (class: CvAccess): if dcc.cmdType returns MyPomCmd, the number and value of the received CV can be obtained via the cvCmd object.

• CvProgramming (class CvProgramming): processes a received PoM or SM command. Reads or modifies the CV that is targeted by this command. If dcc.cmdType returns MyPomCmd or SmCmd, the main sketch should call cvProgramming.processMessage() to ensure that the targeted CV is indeed being read or modified.

• cvValues (class CvValues): allows the main sketch to read() or write() individual CV values. To select the matching set of CV default values for this type of decoder, setup() of the main sketch should call cvValues.init().

• RS-Bus class; RS-Bus: To send feedback messages via the RS-Bus, the user sketch may instantiate one or more RS-Bus objects of class RSbusConnection. Note that the user sketch does not need to instantiate the RSbusHardware class itself or create RS-Bus objects for PoM feedback, since the decoderHardware object already takes care of that.

• onBoardLed (defined in AP_DccLED.h): the onboard LED may be used to inform the user of specific events. To accommodate different LED behaviour, the following classes are defined:

  • BasicLed: to turn on, off or toggle LEDs.
  • FlashLed: allows LEDs to flash slow, fast, or user specified.
  • DccLed: the typical class for onboard LEDs.

• Buttons: the user sketch may need to read the status of (debounced) buttons. Two different classes are provided: the DccButton class for normal buttons and the ToggleButton class for toggle buttons. The onBoardButton is of class DccButton; this button can not be used by the user sketch.

• Timers: the DccTimer class allows the user sketch to include (non-blocking) timers based on Arduino's millis().

• Relays: the Relays class allows the user sketch to include bi-stable relays. Mono-stable relays are not implemented.

---

Example

A skeleton that shows the basic usage of the core functions (without RS-Bus feedback) is shown below.
Each decoder should call in setup() cvValues.init() followed by decoderHardware.init(). The main loop should call dcc.input() to check if a new DCC message has been received, and decoderHardware.update() to update the onboard LED and check if the programming button was pushed.

#include <AP_DCC_Decoder_Core.h>

void setup() {
  cvValues.init(SwitchDecoder, 20);
  decoderHardware.init();
}

void loop() {
  // Do something with the DCC message received ...
  if (dcc.input()) {};
  // Check if the programming button is pushed
  decoderHardware.update();
}

A more elaborate example, which includes feedback via the RS-Bus, is shown BasicDecoder.md.