Package jmri.jmrix.dccpp

Class DCCppMessage

  • All Implemented Interfaces:
    java.lang.Comparable<java.util.concurrent.Delayed>, java.util.concurrent.Delayed, Message
    public class DCCppMessage
extends AbstractMRMessage
implements java.util.concurrent.Delayed
    Represents a single command or response on the DCC++.

    Content is represented with ints to avoid the problems with sign-extension that bytes have, and because a Java char is actually a variable number of bytes in Unicode.

    • Constructor Detail

      • DCCppMessage

        public DCCppMessage​(int len)
        Create a new object, representing a specific-length message.
        Parameters:
        len - Total bytes in message, including opcode and error-detection byte.

      • DCCppMessage

        public DCCppMessage​(DCCppMessage message)
        Create a new object, that is a copy of an existing message.
        Parameters:
        message - existing message.

      • DCCppMessage

        public DCCppMessage​(DCCppReply message)
        Create an DCCppMessage from an DCCppReply. Not used. Really, not even possible. Consider removing.
        Parameters:
        message - existing reply to replicate.

      • DCCppMessage

        public DCCppMessage​(java.lang.String s)
        Create a DCCppMessage from a String containing bytes.

        Since DCCppMessages are text, there is no Hex-to-byte conversion.

        NOTE 15-Feb-17: un-Deprecating this function so that it can be used in the DCCppOverTCP server/client interface. Messages shouldn't be parsed, they are already in DCC++ format, so we need the string constructor to generate a DCCppMessage from the incoming byte stream.

        Parameters:
        s - message in string form.

      • DCCppMessage

        protected DCCppMessage​(char c,
                       java.lang.String regex)

    • Method Detail

      • toString

        public java.lang.String toString()
        Converts DCCppMessage to String format (without the <> brackets)
        Specified by:
        toString in interface Message
        Overrides:
        toString in class AbstractMRMessage
        Returns:
        String form of message.

      • toMonitorString

        public java.lang.String toMonitorString()
        Generate text translations of messages for use in the DCCpp monitor.
        Specified by:
        toMonitorString in interface Message
        Returns:
        representation of the DCCpp as a string.

      • getValueString

        public java.lang.String getValueString​(int idx)

      • length

        public int length()
        Returns:
        the message length

      • setDCCppMessageRetries

        public static void setDCCppMessageRetries​(int t)
        Change the default number of retries for an DCC++ message.
        Parameters:
        t - number of retries to attempt

      • setDCCppMessageTimeout

        public static void setDCCppMessageTimeout​(int t)
        Change the default timeout for a DCC++ message.
        Parameters:
        t - Timeout in milliseconds

      • isValidMessageFormat

        public boolean isValidMessageFormat()
        Returns true if this DCCppMessage is properly formatted (or will generate a properly formatted command when converted to String).
        Returns:
        boolean true/false

      • replyExpected

        public boolean replyExpected()
        Description copied from class: AbstractMRMessage
        Is a reply expected to this message?

        By default, a reply is expected to every message; either a reply or a timeout is needed before the next message can be sent.

        If this returns false, the transmit queue will immediately go on to transmit the next message (if any).

        Overrides:
        replyExpected in class AbstractMRMessage
        Returns:
        true by default in Abstract MR message.

      • makeAccessoryDecoderMsg

        public static DCCppMessage makeAccessoryDecoderMsg​(int address,
                                                   int subaddress,
                                                   boolean activate)
        Stationary Decoder Message.

        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

        Parameters:
        address - the primary address of the decoder (0-511).
        subaddress - the subaddress of the decoder (0-3).
        activate - true on, false off.
        Returns:
        accessory decoder message.

      • makeTurnoutCommandMsg

        public static DCCppMessage makeTurnoutCommandMsg​(int id,
                                                 boolean thrown)
        Predefined Turnout Control Message.
        Parameters:
        id - the numeric ID (0-32767) of the turnout to control.
        thrown - true thrown, false closed.
        Returns:
        message to set turnout.

      • makeSensorAddMsg

        public static DCCppMessage makeSensorAddMsg​(int id,
                                            int pin,
                                            int pullup)
        Create/Delete/Query Sensor.

        sensor, or <X> if no sensors defined.

        Parameters:
        id - pin pullup (0-32767).
        pin - Arduino pin index of sensor.
        pullup - true if use internal pullup for PIN, false if not.
        Returns:
        message to create the sensor.

      • makeWriteDirectCVMsg

        public static DCCppMessage makeWriteDirectCVMsg​(int cv,
                                                int val)
        Write Direct CV Byte to Programming Track

        Format: <W CV VALUE CALLBACKNUM CALLBACKSUB>

        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

        Note: The two-argument form embeds the opcode in CALLBACKSUB to aid in decoding the responses.

        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

        Parameters:
        cv - CV index, 1-1024.
        val - new CV value, 0-255.
        Returns:
        message to write Direct CV.

      • makeBitWriteDirectCVMsg

        public static DCCppMessage makeBitWriteDirectCVMsg​(int cv,
                                                   int bit,
                                                   int val)
        Write Direct CV Bit to Programming Track.

        Format: <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 Configurarion 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

        Note: The two-argument form embeds the opcode in CALLBACKSUB to aid in decoding the responses.

        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

        Parameters:
        cv - CV index, 1-1024.
        bit - bit index, 0-7
        val - bit value, 0-1.
        Returns:
        message to write direct CV bit.

      • makeReadDirectCVMsg

        public static DCCppMessage makeReadDirectCVMsg​(int cv)
        Read Direct CV Byte from Programming Track.

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

        Note: The two-argument form embeds the opcode in CALLBACKSUB to aid in decoding the responses.

        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

        Parameters:
        cv - CV index.
        Returns:
        message to send read direct CV.

      • makeVerifyCVMsg

        public static DCCppMessage makeVerifyCVMsg​(int cv,
                                           int startVal)
        Verify Direct CV Byte from Programming Track.

        Format: <V CV STARTVAL>

        Verifies a Configuration Variable from the decoder of an engine on the programming track. Returns the current value of that CV. Used as faster replacement for 'R'eadCV command

        CV: the number of the Configuration Variable memory location in the decoder to read from (1-1024) STARTVAL: a "guess" as to the current value of the CV. DCC-EX will try this value first, then read and return the current value if different

        returns: <v CV VALUE> where VALUE is a number from 0-255 as read from the requested CV, -1 if read could not be performed

        Parameters:
        cv - CV index.
        startVal - "guess" as to current value
        Returns:
        message to send verify direct CV.

      • makeWriteOpsModeCVMsg

        @CheckForNull
public static DCCppMessage makeWriteOpsModeCVMsg​(int address,
                                                 int cv,
                                                 int val)
        Write Direct CV Byte to Main Track

        Format: <w CAB CV VALUE>

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

        Parameters:
        address - 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).
        val - the value to be written to the Configuration Variable memory location (0-255).
        Returns:
        message to Write CV in Ops Mode.

      • makeBitWriteOpsModeCVMsg

        public static DCCppMessage makeBitWriteOpsModeCVMsg​(int address,
                                                    int cv,
                                                    int bit,
                                                    int val)
        Write Direct CV Bit to Main Track.

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

        Parameters:
        address - loco cab address.
        cv - CV index, 1-1024.
        bit - bit index, 0-7.
        val - bit value, 0 or 1.
        Returns:
        message to write direct CV bit to main track.

      • makeSetTrackPowerMsg

        public static DCCppMessage makeSetTrackPowerMsg​(boolean on)
        Set Track Power ON or OFF.

        Format: <1> (ON) or <0> (OFF)

        Parameters:
        on - true on, false off.
        Returns:
        message to send track power on or off.

      • makeReadTrackCurrentMsg

        public static DCCppMessage makeReadTrackCurrentMsg()
        Read main operations track current

        Format: <c> reads current being drawn on main operations track

        Returns:
        (for DCC-EX), 1 or more of <c MeterName value C/V unit min max res warn> where name and settings are used to define arbitrary meters on the DCC-EX side AND <a CURRENT> where CURRENT = 0-1024, based on exponentially-smoothed weighting scheme

      • makeCSStatusMsg

        public static DCCppMessage makeCSStatusMsg()
        Read DCC++ Base Station Status

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

      • makeCSMaxNumSlotsMsg

        public static DCCppMessage makeCSMaxNumSlotsMsg()
        Get number of supported slots for this DCC++ Base Station Status

        Format: <N>

        returns number of slots NOTE: this is not implemented in older versions which then do not return anything at all

        Returns:
        status message with to get number of slots.

      • makeFunctionV4Message

        public static DCCppMessage makeFunctionV4Message​(int cab,
                                                 int func,
                                                 boolean state)
        Generate a function message using the V4 'F' syntax supported by DCC-EX
        Parameters:
        cab - cab address to send function to
        func - function number to set
        state - new state of function 0/1
        Returns:
        function functionV4message

      • makeForgetCabMessage

        public static DCCppMessage makeForgetCabMessage​(int cab)
        Generate a "Forget Cab" message '-'
        Parameters:
        cab - cab address to send function to (or 0 for all)
        Returns:
        forget message to be sent

      • makeAddressedEmergencyStop

        public static DCCppMessage makeAddressedEmergencyStop​(int register,
                                                      int address)
        Generate an emergency stop for the specified address.

        Note: This just sends a THROTTLE command with speed = -1

        Parameters:
        register - Register Number for the loco assigned address.
        address - is the locomotive address.
        Returns:
        message to send e stop to the specified address.

      • makeAddressedEmergencyStop

        public static DCCppMessage makeAddressedEmergencyStop​(int address)
        Generate an emergency stop for the specified address.

        Note: This just sends a THROTTLE command with speed = -1

        Parameters:
        address - is the locomotive address.
        Returns:
        message to send e stop to the specified address.

      • makeEmergencyStopAllMsg

        public static DCCppMessage makeEmergencyStopAllMsg()
        Generate an emergency stop for all locos in reminder table.
        Returns:
        message to send e stop for all locos

      • makeSpeedAndDirectionMsg

        public static DCCppMessage makeSpeedAndDirectionMsg​(int register,
                                                    int address,
                                                    float speed,
                                                    boolean isForward)
        Generate a Speed and Direction Request message
        Parameters:
        register - is the DCC++ base station register assigned.
        address - is the locomotive address
        speed - a normalized speed value (a floating point number between 0 and 1). A negative value indicates emergency stop.
        isForward - true for forward, false for reverse. Format: <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 CAB SPEED DIRECTION>

      • makeSpeedAndDirectionMsg

        public static DCCppMessage makeSpeedAndDirectionMsg​(int address,
                                                    float speed,
                                                    boolean isForward)
        Generate a Speed and Direction Request message
        Parameters:
        address - is the locomotive address
        speed - a normalized speed value (a floating point number between 0 and 1). A negative value indicates emergency stop.
        isForward - true for forward, false for reverse. Format: <t CAB SPEED DIRECTION> sets the throttle for a given register/cab combination 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 CAB SPEED DIRECTION>

      • makeFunctionGroup1OpsMsg

        public static DCCppMessage makeFunctionGroup1OpsMsg​(int address,
                                                    boolean f0,
                                                    boolean f1,
                                                    boolean f2,
                                                    boolean f3,
                                                    boolean f4)
        Generate a Function Group One Operation Request message.
        Parameters:
        address - is the locomotive address
        f0 - is true if f0 is on, false if f0 is off
        f1 - is true if f1 is on, false if f1 is off
        f2 - is true if f2 is on, false if f2 is off
        f3 - is true if f3 is on, false if f3 is off
        f4 - is true if f4 is on, false if f4 is off
        Returns:
        message to set function group 1.

      • makeFunctionGroup1SetMomMsg

        public static DCCppMessage makeFunctionGroup1SetMomMsg​(int address,
                                                       boolean f0,
                                                       boolean f1,
                                                       boolean f2,
                                                       boolean f3,
                                                       boolean f4)
        Generate a Function Group One Set Momentary Functions message.
        Parameters:
        address - is the locomotive address
        f0 - is true if f0 is momentary
        f1 - is true if f1 is momentary
        f2 - is true if f2 is momentary
        f3 - is true if f3 is momentary
        f4 - is true if f4 is momentary
        Returns:
        message to set momentary function group 1.

      • makeFunctionGroup2OpsMsg

        public static DCCppMessage makeFunctionGroup2OpsMsg​(int address,
                                                    boolean f5,
                                                    boolean f6,
                                                    boolean f7,
                                                    boolean f8)
        Generate a Function Group Two Operation Request message.
        Parameters:
        address - is the locomotive address
        f5 - is true if f5 is on, false if f5 is off
        f6 - is true if f6 is on, false if f6 is off
        f7 - is true if f7 is on, false if f7 is off
        f8 - is true if f8 is on, false if f8 is off
        Returns:
        message to set function group 2.

      • makeFunctionGroup2SetMomMsg

        public static DCCppMessage makeFunctionGroup2SetMomMsg​(int address,
                                                       boolean f5,
                                                       boolean f6,
                                                       boolean f7,
                                                       boolean f8)
        Generate a Function Group Two Set Momentary Functions message.
        Parameters:
        address - is the locomotive address
        f5 - is true if f5 is momentary
        f6 - is true if f6 is momentary
        f7 - is true if f7 is momentary
        f8 - is true if f8 is momentary
        Returns:
        message to set momentary function group 2.

      • makeFunctionGroup3OpsMsg

        public static DCCppMessage makeFunctionGroup3OpsMsg​(int address,
                                                    boolean f9,
                                                    boolean f10,
                                                    boolean f11,
                                                    boolean f12)
        Generate a Function Group Three Operation Request message.
        Parameters:
        address - is the locomotive address
        f9 - is true if f9 is on, false if f9 is off
        f10 - is true if f10 is on, false if f10 is off
        f11 - is true if f11 is on, false if f11 is off
        f12 - is true if f12 is on, false if f12 is off
        Returns:
        message to set function group 3.

      • makeFunctionGroup3SetMomMsg

        public static DCCppMessage makeFunctionGroup3SetMomMsg​(int address,
                                                       boolean f9,
                                                       boolean f10,
                                                       boolean f11,
                                                       boolean f12)
        Generate a Function Group Three Set Momentary Functions message.
        Parameters:
        address - is the locomotive address
        f9 - is true if f9 is momentary
        f10 - is true if f10 is momentary
        f11 - is true if f11 is momentary
        f12 - is true if f12 is momentary
        Returns:
        message to set momentary function group 3.

      • makeFunctionGroup4OpsMsg

        public static DCCppMessage makeFunctionGroup4OpsMsg​(int address,
                                                    boolean f13,
                                                    boolean f14,
                                                    boolean f15,
                                                    boolean f16,
                                                    boolean f17,
                                                    boolean f18,
                                                    boolean f19,
                                                    boolean f20)
        Generate a Function Group Four Operation Request message.
        Parameters:
        address - is the locomotive address
        f13 - is true if f13 is on, false if f13 is off
        f14 - is true if f14 is on, false if f14 is off
        f15 - is true if f15 is on, false if f15 is off
        f16 - is true if f18 is on, false if f16 is off
        f17 - is true if f17 is on, false if f17 is off
        f18 - is true if f18 is on, false if f18 is off
        f19 - is true if f19 is on, false if f19 is off
        f20 - is true if f20 is on, false if f20 is off
        Returns:
        message to set function group 4.

      • makeFunctionGroup4SetMomMsg

        public static DCCppMessage makeFunctionGroup4SetMomMsg​(int address,
                                                       boolean f13,
                                                       boolean f14,
                                                       boolean f15,
                                                       boolean f16,
                                                       boolean f17,
                                                       boolean f18,
                                                       boolean f19,
                                                       boolean f20)
        Generate a Function Group Four Set Momentary Function message.
        Parameters:
        address - is the locomotive address
        f13 - is true if f13 is Momentary
        f14 - is true if f14 is Momentary
        f15 - is true if f15 is Momentary
        f16 - is true if f18 is Momentary
        f17 - is true if f17 is Momentary
        f18 - is true if f18 is Momentary
        f19 - is true if f19 is Momentary
        f20 - is true if f20 is Momentary
        Returns:
        message to set momentary function group 4.

      • makeFunctionGroup5OpsMsg

        public static DCCppMessage makeFunctionGroup5OpsMsg​(int address,
                                                    boolean f21,
                                                    boolean f22,
                                                    boolean f23,
                                                    boolean f24,
                                                    boolean f25,
                                                    boolean f26,
                                                    boolean f27,
                                                    boolean f28)
        Generate a Function Group Five Operation Request message.
        Parameters:
        address - is the locomotive address
        f21 - is true if f21 is on, false if f21 is off
        f22 - is true if f22 is on, false if f22 is off
        f23 - is true if f23 is on, false if f23 is off
        f24 - is true if f24 is on, false if f24 is off
        f25 - is true if f25 is on, false if f25 is off
        f26 - is true if f26 is on, false if f26 is off
        f27 - is true if f27 is on, false if f27 is off
        f28 - is true if f28 is on, false if f28 is off
        Returns:
        message to set function group 5.

      • makeFunctionGroup5SetMomMsg

        public static DCCppMessage makeFunctionGroup5SetMomMsg​(int address,
                                                       boolean f21,
                                                       boolean f22,
                                                       boolean f23,
                                                       boolean f24,
                                                       boolean f25,
                                                       boolean f26,
                                                       boolean f27,
                                                       boolean f28)
        Generate a Function Group Five Set Momentary Function message.
        Parameters:
        address - is the locomotive address
        f21 - is true if f21 is momentary
        f22 - is true if f22 is momentary
        f23 - is true if f23 is momentary
        f24 - is true if f24 is momentary
        f25 - is true if f25 is momentary
        f26 - is true if f26 is momentary
        f27 - is true if f27 is momentary
        f28 - is true if f28 is momentary
        Returns:
        message to set momentary function group 5.

      • makeWriteDCCPacketMainMsg

        public static DCCppMessage makeWriteDCCPacketMainMsg​(int register,
                                                     int numBytes,
                                                     byte[] bytes)
        Write DCC Packet to a specified Register on the Main.
        DCC++ BaseStation code appends its own error-correction byte so we must not provide one.
        Parameters:
        register - the DCC++ BaseStation main register number to use
        numBytes - the number of bytes in the packet
        bytes - byte array representing the packet. The first num_bytes are used.
        Returns:
        the formatted message to send

      • makeWriteDCCPacketProgMsg

        public static DCCppMessage makeWriteDCCPacketProgMsg​(int register,
                                                     int numBytes,
                                                     byte[] bytes)
        Write DCC Packet to a specified Register on the Programming Track.

        DCC++ BaseStation code appends its own error-correction byte so we must not provide one.
        Parameters:
        register - the DCC++ BaseStation main register number to use
        numBytes - the number of bytes in the packet
        bytes - byte array representing the packet. The first num_bytes are used.
        Returns:
        the formatted message to send

      • equals

        public boolean equals​(java.lang.Object obj)
        This implementation of equals is targeted to the background function refreshing in SerialDCCppPacketizer. To keep only one function group in the refresh queue the logic is as follows. Two messages are equal if they are:
        • actually identical, or
        • a function call to the same address and same function group
        Overrides:
        equals in class AbstractMessage

      • delayFor

        public void delayFor​(long millis)
        Before adding the message to the delay queue call this method to set when the message should be repeated. The only time guarantee is that it will be repeated after at least this much time, but it can be significantly longer until it is repeated, function of the message queue length.
        Parameters:
        millis - milliseconds in the future

      • compareTo

        public int compareTo​(@Nonnull
                     java.util.concurrent.Delayed o)
        Comparing two queued message for refreshing the function calls, based on their expected execution time.
        Specified by:
        compareTo in interface java.lang.Comparable<java.util.concurrent.Delayed>

      • getDelay

        public long getDelay​(java.util.concurrent.TimeUnit unit)
        From the Delayed interface, how long this message still has until it should be executed.
        Specified by:
        getDelay in interface java.util.concurrent.Delayed