DCCpp
This is the library version of a program for Arduino to control railroading DCC devices.
Text Commands Syntax

CREATES A NEW SENSOR

<S ID PIN PULLUP>

creates a new sensor ID, with specified PIN and PULLUP if sensor ID already exists, it is updated with specified PIN and PULLUP

returns: <O> if successful and <X> if unsuccessful (e.g. out of memory)

DELETES AN EXISTING SENSOR

<S ID>

deletes definition of sensor ID.

returns: <O> if successful and <X> if unsuccessful (e.g. ID does not exist)

LISTS ALL DEFINED SENSORS

<S>

lists all defined sensors

returns: <Q ID PIN PULLUP> for each defined sensor or <X> if no sensors defined where

CREATES A NEW TURNOUT

<T ID ADDRESS SUBADDRESS>

creates a new turnout ID, with specified ADDRESS and SUBADDRESS if turnout ID already exists, it is updated with specified ADDRESS and SUBADDRESS

returns: <O> if successful and <X> if unsuccessful (e.g. out of memory)

DELETES AN EXISTING TURNOUT

<T ID>

deletes definition of turnout ID

returns: <O> if successful and <X> if unsuccessful (e.g. ID does not exist)

LISTS ALL TURNOUTS

<T>

returns: <H ID ADDRESS SUBADDRESS THROW> for each defined turnout or <X> if no turnouts defined where

THROWS AN EXISTING TURNOUT

<T ID THROW>

sets turnout ID to either the "thrown" or "not thrown" position

returns: <H ID THROW>, or <X> if turnout ID does not exist

SET ENGINE THROTTLES USING 128-STEP SPEED CONTROL

<t REGISTER CAB SPEED DIRECTION>

sets the throttle for a given register/cab combination

returns: <T REGISTER SPEED DIRECTION>

OPERATE ENGINE DECODER FUNCTIONS F0-F28

<f CAB BYTE1 [BYTE2]>
<f -1 REGISTER CAB BYTE1 [BYTE2]>

turns on and off engine decoder functions F0-F28 (F0 is sometimes called FL) NOTE: setting requests transmitted directly to mobile engine decoder — current state of engine functions is not stored by this program

To set functions F0-F4 on (=1) or off (=0):

To set functions F5-F8 on (=1) or off (=0):

To set functions F9-F12 on (=1) or off (=0):

To set functions F13-F20 on (=1) or off (=0):

To set functions F21-F28 on (=1) of off (=0):

returns: NONE

OPERATE STATIONARY ACCESSORY DECODERS

<a ADDRESS SUBADDRESS ACTIVATE>

turns an accessory (stationary) decoder on or off

Note that many decoders and controllers combine the ADDRESS and SUBADDRESS into a single number, N, from 1 through a max of 2044, where

N = (ADDRESS - 1) * 4 + SUBADDRESS + 1, for all ADDRESS>0

OR

However, this general command simply sends the appropriate DCC instruction packet to the main tracks to operate connected accessories. It does not store or retain any information regarding the current status of that accessory. To have this sketch store and retain the direction of DCC-connected turnouts, as well as automatically invoke the required <a> command as needed, first define/edit/delete turnouts using the following variations of the "T" command.

returns: NONE

SHOW STATUS OF ALL SENSORS

<Q>

returns: the status of each sensor ID in the form <Q ID> (active) or <q ID> (not active)

WRITE CONFIGURATION VARIABLE BYTE TO ENGINE DECODER ON MAIN OPERATIONS TRACK

<w CAB CV VALUE>

writes, without any verification, a Configuration Variable to the decoder of an engine on the main operations track

returns: NONE

WRITE CONFIGURATION VARIABLE BIT TO ENGINE DECODER ON MAIN OPERATIONS TRACK

<b CAB CV BIT VALUE>

writes, without any verification, a single bit within a Configuration Variable to the decoder of an engine on the main operations track

returns: NONE

WRITE CONFIGURATION VARIABLE BYTE TO ENGINE DECODER ON PROGRAMMING TRACK

<W CV VALUE CALLBACKNUM CALLBACKSUB>

writes, and then verifies, a Configuration Variable to the decoder of an engine on the programming track

returns: <r CALLBACKNUM|CALLBACKSUB|CV Value> where VALUE is a number from 0-255 as read from the requested CV, or -1 if verification read fails

WRITE CONFIGURATION VARIABLE BIT TO ENGINE DECODER ON PROGRAMMING TRACK

<B CV BIT VALUE CALLBACKNUM CALLBACKSUB>

writes, and then verifies, a single bit within a Configuration Variable to the decoder of an engine on the programming track

returns: <r CALLBACKNUM|CALLBACKSUB|CV BIT VALUE> where VALUE is a number from 0-1 as read from the requested CV bit, or -1 if verification read fails

READ CONFIGURATION VARIABLE BYTE FROM ENGINE DECODER ON PROGRAMMING TRACK

<R CV CALLBACKNUM CALLBACKSUB>

reads a Configuration Variable from the decoder of an engine on the programming track

returns: <r CALLBACKNUM|CALLBACKSUB|CV VALUE> where VALUE is a number from 0-255 as read from the requested CV, or -1 if read could not be verified

READ CONFIGURATION VARIABLE BYTE FROM ENGINE DECODER ON MAIN TRACK

<r CV CALLBACKNUM CALLBACKSUB>

reads a Configuration Variable from the decoder of an engine on the main track

returns: <r CALLBACKNUM|CALLBACKSUB|CV VALUE> where VALUE is a number from 0-255 as read from the requested CV, or -1 if read could not be verified

TURN ON POWER FROM MOTOR SHIELD TO TRACKS

<1>

enables power from the motor shield to the main operations and programming tracks

returns: <p1>

TURN OFF POWER FROM MOTOR SHIELD TO TRACKS

<0>

disables power from the motor shield to the main operations and programming tracks

returns: <p0>

READ MAIN OPERATIONS TRACK CURRENT

<c>

reads current being drawn on main operations track

returns: <a CURRENT> where CURRENT = 0-1024, based on exponentially-smoothed weighting scheme

STATUS OF DCC++ BASE STATION

<s>

returns status messages containing track power status, throttle status, turn-out status, and a version number NOTE: this is very useful as a first command for an interface to send to this sketch in order to verify connectivity and update any GUI to reflect actual throttle and turn-out settings

returns: series of status messages that can be read by an interface to determine status of DCC++ Base Station and important settings

STORE SETTINGS IN EEPROM

<E>

Stores settings for turnouts and sensors EEPROM

returns: <e nTurnouts nSensors>

CLEAR SETTINGS IN EEPROM

<e>

clears settings for Turnouts in EEPROM

returns: <O>

PRINT CARRIAGE RETURN IN SERIAL MONITOR WINDOW

< >

simply prints a carriage return - useful when interacting with ArduIno through serial monitor window

returns: a carriage return

THE FOLLOWING COMMANDS ARE NOT NEEDED FOR NORMAL OPERATIONS AND ARE ONLY USED FOR TESTING AND DEBUGGING PURPOSES PLEASE SEE SPECIFIC WARNINGS IN EACH COMMAND BELOW

ENTER DIAGNOSTIC MODE

<D>

changes the clock speed of the chip and the pre-scaler for the timers so that you can visually see the DCC signals flickering with an LED SERIAL COMMUNICATION WILL BE INTERUPTED ONCE THIS COMMAND IS ISSUED - MUST RESET BOARD OR RE-OPEN SERIAL WINDOW TO RE-ESTABLISH COMMS

WRITE A DCC PACKET TO ONE OF THE REGISTERS DRIVING THE MAIN OPERATIONS TRACK

<M REGISTER BYTE1 BYTE2 [BYTE3] [BYTE4] [BYTE5]>

writes a DCC packet of two, three, four, or five hexadecimal bytes to a register driving the main operations track fOR DEBUGGING AND TESTING PURPOSES ONLY. DO NOT USE UNLESS YOU KNOW HOW TO CONSTRUCT NMRA DCC PACKETS - YOU CAN INADVERTENTLY RE-PROGRAM YOUR ENGINE DECODER

returns: NONE

WRITE A DCC PACKET TO ONE OF THE REGISTERS DRIVING THE MAIN OPERATIONS TRACK

<P REGISTER BYTE1 BYTE2 [BYTE3] [BYTE4] [BYTE5]>

writes a DCC packet of two, three, four, or five hexadecimal bytes to a register driving the programming track FOR DEBUGGING AND TESTING PURPOSES ONLY. DO NOT USE UNLESS YOU KNOW HOW TO CONSTRUCT NMRA DCC PACKETS - YOU CAN INADVERTENTLY RE-PROGRAM YOUR ENGINE DECODER

returns: NONE

ATTEMPTS TO DETERMINE HOW MUCH FREE SRAM IS AVAILABLE IN ARDUINO

<F>

measure amount of free SRAM memory left on the Arduino based on trick found on the Internet. Useful when setting dynamic array sizes, considering the Uno only has 2048 bytes of dynamic SRAM. Unfortunately not very reliable — would be great to find a better method

returns: <f MEM> where MEM is the number of free bytes remaining in the Arduino's SRAM

LISTS BIT CONTENTS OF ALL INTERNAL DCC PACKET REGISTERS

<L>

lists the packet contents of the main operations track registers and the programming track registers FOR DIAGNOSTIC AND TESTING USE ONLY