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
SET ENGINE THROTTLES USING 128-STEP SPEED CONTROL
<t REGISTER CAB SPEED DIRECTION>
sets the throttle for a given register/cab combination
- REGISTER: an internal register number, from 1 through MAX_MAIN_REGISTERS (inclusive), to store the DCC packet used to control this throttle setting
- CAB: the short (1-127) or long (128-10293) address of the engine decoder
- SPEED: throttle speed from 0-126, or -1 for emergency stop (resets SPEED to 0)
- DIRECTION: 1=forward, 0=reverse. Setting direction when speed=0 or speed=-1 only effects directionality of cab lighting for a stopped train
returns: <T REGISTER SPEED DIRECTION>
OPERATE ENGINE DECODER FUNCTIONS F0-F28
<f 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
- CAB: the short (1-127) or long (128-10293) address of the engine decoder
To set functions F0-F4 on (=1) or off (=0):
- BYTE1: 128 + F1*1 + F2*2 + F3*4 + F4*8 + F0*16
- BYTE2: omitted
To set functions F5-F8 on (=1) or off (=0):
- BYTE1: 176 + F5*1 + F6*2 + F7*4 + F8*8
- BYTE2: omitted
To set functions F9-F12 on (=1) or off (=0):
- BYTE1: 160 + F9*1 +F10*2 + F11*4 + F12*8
- BYTE2: omitted
To set functions F13-F20 on (=1) or off (=0):
- BYTE1: 222
- BYTE2: F13*1 + F14*2 + F15*4 + F16*8 + F17*16 + F18*32 + F19*64 + F20*128
To set functions F21-F28 on (=1) of off (=0):
- BYTE1: 223
- BYTE2: F21*1 + F22*2 + F23*4 + F24*8 + F25*16 + F26*32 + F27*64 + F28*128
returns: NONE
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
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
- 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)
- VALUE: the value to be written to the Configuration Variable memory location (0-255)
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
- 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
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
- 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