DCC++ Serial Commands

Collaboration diagram for DCC++ Serial Commands:

Modules
	DCC++ Commands Extended by LccFusion

Detailed Description

CREATES A NEW OUTPUT

<Z ID PIN IFLAG>

creates a new output ID, with specified PIN and IFLAG values. if output ID already exists, it is updated with specified PIN and IFLAG. note: output state will be immediately set to ACTIVE/INACTIVE and pin will be set to HIGH/LOW according to IFLAG value specified (see output class comment).

• ID: the numeric ID (0-32767) of the output
• PIN: the arduino pin number to use for the output
• STATE: the state of the output (0=INACTIVE / 1=ACTIVE)
• IFLAG: defines the operational behavior of the output based on bits 0, 1, and 2 (see 'lists all outputs' command for more information).

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

DELETES AN EXISTING OUTPUT

<Z ID>

deletes definition of output ID

• ID: the numeric ID (0-32767) of the output

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

LISTS ALL OUTPUTS

<Z>

lists all defined output pins

returns: <Y ID PIN IFLAG STATE> for each defined output pin or <X> if no output pins defined where

• ID: the numeric ID (0-32767) of the output
• PIN: the arduino pin number to use for the output
• STATE: the state of the output (0=INACTIVE / 1=ACTIVE)
• IFLAG: defines the operational behavior of the output based on bits 0, 1, and 2 as follows:
  • IFLAG, bit 0: 0 = forward operation (ACTIVE=HIGH / INACTIVE=LOW) 1 = inverted operation (ACTIVE=LOW / INACTIVE=HIGH)
  • IFLAG, bit 1: 0 = state of pin restored on power-up to either ACTIVE or INACTIVE depending on state before power-down; state of pin set to INACTIVE when first created 1 = state of pin set on power-up, or when first created, to either ACTIVE of INACTIVE depending on IFLAG, bit 2
  • IFLAG, bit 2: 0 = state of pin set to INACTIVE upon power-up or when first created 1 = state of pin set to ACTIVE upon power-up or when first created

CHANGES OUTPUT STATE

<Z ID STATE>

sets output ID to either ACTIVE or INACTIVE state

• ID: the numeric ID (0-32767) of the output
• PIN: the arduino pin number to use for the output
• STATE: the state of the output (0=INACTIVE / 1=ACTIVE)

returns: <Y ID STATE>, or <X> if turnout ID does not exist

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

• ID: the numeric ID (0-32767) of the sensor
• PIN: the arduino pin number the sensor is connected to
• PULLUP: PULLUP: 1=use internal pull-up resistor for PIN, 0=don't use internal pull-up resistor for PIN

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

DELETES AN EXISTING SENSOR

<S ID>

deletes definition of sensor ID.

• ID: the numeric ID (0-32767) of the sensor to check

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

• ID: the numeric ID (0-32767) of the sensor
• PIN: the arduino pin number the sensor is connected to
• PULLUP: PULLUP: 1=use internal pull-up resistor for PIN, 0=don't use internal pull-up resistor for PIN

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

• ID: the numeric ID (0-32767) of the turnout to control
• ADDRESS: the primary address of the decoder controlling this turnout (0-511)
• SUBADDRESS: the sub-address of the decoder controlling this turnout (0-3)

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

DELETES AN EXISTING TURNOUT

<T ID>

deletes definition of turnout ID

• ID: the numeric ID (0-32767) of the turnout to control

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

• ID: the numeric ID (0-32767) of the turnout to control
• ADDRESS: the primary address of the decoder controlling this turnout (0-511)
• SUBADDRESS: the sub-address of the decoder controlling this turnout (0-3)

THROWS AN EXISTING TURNOUT

<T ID THROW>

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

• ID: the numeric ID (0-32767) of the turnout to control
• THROW: 0 (not thrown) or 1 (thrown)

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

---

START MONITORING OF A DCC COMMAND

  <e ADDR [TRACK] >

Start the monitoring of the DCC commands for the specified address, on the specified track

• ADDR: DCC address (or CV number) to be monitored
• [TRACK]: track #, defaults to main track when not specified
  • 0=both
  • 1=main
  • 2=prog returns: < e ADDR [TRACK] >

---

STOP MONITORING OF A DCC COMMAND

  <E ADDR [TRACK] >

Start the monitoring of the DCC commands for the specified address, on the specified track

• ADDR: DCC address (or CV number) to be monitored
• [TRACK]: track #, defaults to main track when not specified
  • 0=both
  • 1=main
  • 2=prog returns: < e ADDR [TRACK] >

---

OPERATE STATIONARY ACCESSORY DECODERS

<a ADDRESS SUBADDRESS ACTIVATE>

turns an accessory (stationary) decoder on or off

• ADDRESS: the primary address of the decoder (0-511)
• SUBADDRESS: the sub-address of the decoder (0-3)
• ACTIVATE: 1=on (set), 0=off (clear)

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

• ADDRESS = INT((N - 1) / 4) + 1
• SUBADDRESS = (N - 1) % 4

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

*** SEE TURNOUT.CPP FOR COMPLETE INFO ON THE DIFFERENT VARIATIONS OF THE "T" COMMAND USED TO CREATE/EDIT/REMOVE/SHOW TURNOUT DEFINITIONS

** SEE OUTPUT.CPP FOR COMPLETE INFO ON THE DIFFERENT VARIATIONS OF THE "Z" COMMAND USED TO CREATE / EDIT / REMOVE / SHOW OUTPUT DEFINITIONS

*** SEE SENSOR.CPP FOR COMPLETE INFO ON THE DIFFERENT VARIATIONS OF THE "S" COMMAND USED TO CREATE/EDIT/REMOVE/SHOW SENSOR DEFINITIONS

---

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 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

• CAB: the short (1-127) or long (128-10293) address of the engine decoder
• CV: the number of the Configuration Variable memory location in the decoder to write to (1-1024)
• BIT: the bit number of the Configuration Variable register to write (0-7)
• VALUE: the value of the bit to be written (0-1)

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

• CV: the number of the Configuration Variable memory location in the decoder to write to (1-1024)
• VALUE: the value to be written to the Configuration Variable memory location (0-255)
• CALLBACKNUM: an arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs that call this function
• CALLBACKSUB: a second arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs (e.g. DCC++ Interface) that call this function

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

• CV: the number of the Configuration Variable memory location in the decoder to write to (1-1024)
• BIT: the bit number of the Configuration Variable memory location to write (0-7)
• VALUE: the value of the bit to be written (0-1)
• CALLBACKNUM: an arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs that call this function
• CALLBACKSUB: a second arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs (e.g. DCC++ Interface) that call this function

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

• CV: the number of the Configuration Variable memory location in the decoder to read from (1-1024)
• CALLBACKNUM: an arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs that call this function
• CALLBACKSUB: a second arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs (e.g. DCC++ Interface) that call this function

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

• CV: the number of the Configuration Variable memory location in the decoder to read from (1-1024)
• CALLBACKNUM: an arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs that call this function
• CALLBACKSUB: a second arbitrary integer (0-32767) that is ignored by the Base Station and is simply echoed back in the output - useful for external programs (e.g. DCC++ Interface) that call this function

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 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

---

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

• REGISTER: an internal register number, from 0 through MAX_MAIN_REGISTERS (inclusive), to write (if REGISTER=0) or write and store (if REGISTER>0) the packet
• BYTE1: first hexadecimal byte in the packet
• BYTE2: second hexadecimal byte in the packet
• BYTE3: optional third hexadecimal byte in the packet
• BYTE4: optional fourth hexadecimal byte in the packet
• BYTE5: optional fifth hexadecimal byte in the packet

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

• REGISTER: an internal register number, from 0 through MAX_MAIN_REGISTERS (inclusive), to write (if REGISTER=0) or write and store (if REGISTER>0) the packet
• BYTE1: first hexadecimal byte in the packet
• BYTE2: second hexadecimal byte in the packet
• BYTE3: optional third hexadecimal byte in the packet
• BYTE4: optional fourth hexadecimal byte in the packet
• BYTE5: optional fifth hexadecimal byte in the packet

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