Class XNetMessage

  • All Implemented Interfaces:
    java.io.Serializable, Message
    Direct Known Subclasses:
    Z21XNetMessage

    public class XNetMessage
    extends AbstractMRMessage
    implements java.io.Serializable
    Represents a single command or response on the XpressNet.

    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.

    See Also:
    Serialized Form
    • Constructor Detail

      • XNetMessage

        public XNetMessage​(int len)
        Create a new object, representing a specific-length message.
        Parameters:
        len - Total bytes in message, including opcode and error-detection byte. Valid values are 0 to 15 (0x0 to 0xF).
      • XNetMessage

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

        public XNetMessage​(XNetReply message)
        Create an XNetMessage from an XNetReply.
        Parameters:
        message - existing XNetReply.
      • XNetMessage

        public XNetMessage​(java.lang.String s)
        Create an XNetMessage from a String containing bytes.
        Parameters:
        s - string containing data bytes.
    • Method Detail

      • checkParity

        public boolean checkParity()
        Check whether the message has a valid parity.
        Returns:
        true if parity valid, else false.
      • getElementBCD

        public java.lang.Integer getElementBCD​(int n)
        Get an integer representation of a BCD value.
        Parameters:
        n - message element index.
        Returns:
        integer of BCD.
      • length

        public int length()
        Get the message length.
        Returns:
        message length.
      • setXNetMessageRetries

        public static void setXNetMessageRetries​(int t)
        Set the default number of retries for an XpressNet message.
        Parameters:
        t - number of retries to attempt
      • setXNetMessageTimeout

        public static void setXNetMessageTimeout​(int t)
        Set the default timeout for an XpressNet message.
        Parameters:
        t - Timeout in milliseconds
      • replyExpected

        public boolean replyExpected()
        Most messages are sent with a reply expected, but we have a few that we treat as though the reply is always a broadcast message, because the reply usually comes to us that way. 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.
      • setBroadcastReply

        public void setBroadcastReply()
        Tell the traffic controller we expect this message to have a broadcast reply.
      • getNMRAXNetMsg

        public static XNetMessage getNMRAXNetMsg​(byte[] packet)
        Encapsulate an NMRA DCC packet in an XpressNet message.

        On Current (v3.5) Lenz command stations, the Operations Mode Programming Request is implemented by sending a packet directly to the rails. This packet is not checked by the XpressNet protocol, and is just the track packet with an added header byte.

        NOTE: Lenz does not say this will work for anything but 5 byte packets.

        Parameters:
        packet - byte array containing packet data elements.
        Returns:
        message to send DCC packet.
      • getTurnoutCommandMsg

        public static XNetMessage getTurnoutCommandMsg​(int pNumber,
                                                       boolean pClose,
                                                       boolean pThrow,
                                                       boolean pOn)
        Generate a message to change turnout state.
        Parameters:
        pNumber - address number.
        pClose - true if set turnout closed.
        pThrow - true if set turnout thrown.
        pOn - accessory line true for on, false off.
        Returns:
        message containing turnout command.
      • getFeedbackRequestMsg

        public static XNetMessage getFeedbackRequestMsg​(int pNumber,
                                                        boolean pLowerNibble)
        Generate a message to receive the feedback information for an upper or lower nibble of the feedback address in question.
        Parameters:
        pNumber - feedback address.
        pLowerNibble - true for upper nibble, else false for lower.
        Returns:
        feedback request message.
      • getBuildDoubleHeaderMsg

        public static XNetMessage getBuildDoubleHeaderMsg​(int address1,
                                                          int address2)
        Build a Double Header.
        Parameters:
        address1 - the first address in the consist
        address2 - the second address in the consist.
        Returns:
        message to build double header.
      • getDisolveDoubleHeaderMsg

        public static XNetMessage getDisolveDoubleHeaderMsg​(int address)
        Dissolve a Double Header.
        Parameters:
        address - one of the two addresses in the Double Header
        Returns:
        message to dissolve a double header.
      • getAddLocoToConsistMsg

        public static XNetMessage getAddLocoToConsistMsg​(int consist,
                                                         int address,
                                                         boolean isNormalDir)
        Add a Single address to a specified Advanced consist.
        Parameters:
        consist - the consist address (1-99)
        address - the locomotive address to add.
        isNormalDir - tells us if the locomotive is going forward when the consist is going forward.
        Returns:
        message to add address to consist.
      • getRemoveLocoFromConsistMsg

        public static XNetMessage getRemoveLocoFromConsistMsg​(int consist,
                                                              int address)
        Remove a Single address to a specified Advanced consist.
        Parameters:
        consist - the consist address (1-99)
        address - the locomotive address to remove
        Returns:
        message to remove single address from consist.
      • getNextAddressOnStackMsg

        public static XNetMessage getNextAddressOnStackMsg​(int address,
                                                           boolean searchForward)
        Given a locomotive address, search the database for the next member. (if the Address is zero start at the beginning of the database).
        Parameters:
        address - is the locomotive address
        searchForward - indicates to search the database Forward if true, or backwards if False
        Returns:
        message to request next address.
      • getDBSearchMsgConsistAddress

        public static XNetMessage getDBSearchMsgConsistAddress​(int address,
                                                               boolean searchForward)
        Given a consist address, search the database for the next Consist address.
        Parameters:
        address - is the consist address (in the range 1-99). If the Address is zero start at the beginning of the database.
        searchForward - indicates to search the database Forward if true, or backwards if false
        Returns:
        message to get next consist address.
      • getDBSearchMsgNextMULoco

        public static XNetMessage getDBSearchMsgNextMULoco​(int consist,
                                                           int address,
                                                           boolean searchForward)
        Given a consist and a locomotive address, search the database for the next Locomotive in the consist.
        Parameters:
        consist - the consist address (1-99). If the Consist Address is zero start at the begining of the database
        address - the locomotive address. If the Address is zero start at the begining of the consist
        searchForward - indicates to search the database Forward if true, or backwards if False
        Returns:
        message to request next loco in consist.
      • getDeleteAddressOnStackMsg

        public static XNetMessage getDeleteAddressOnStackMsg​(int address)
        Given a locomotive address, delete it from the database .
        Parameters:
        address - the locomotive address
        Returns:
        message to delete loco address from stack.
      • getLocomotiveInfoRequestMsg

        public static XNetMessage getLocomotiveInfoRequestMsg​(int address)
        Given a locomotive address, request its status .
        Parameters:
        address - the locomotive address
        Returns:
        message to request loco status.
      • getLocomotiveFunctionStatusMsg

        public static XNetMessage getLocomotiveFunctionStatusMsg​(int address)
        Given a locomotive address, request the function state (momentary status).
        Parameters:
        address - the locomotive address
        Returns:
        momentary function state request request.
      • getLocomotiveFunctionHighOnStatusMsg

        public static XNetMessage getLocomotiveFunctionHighOnStatusMsg​(int address)
        Given a locomotive address, request the function on/off state for functions 13-28
        Parameters:
        address - the locomotive address
        Returns:
        function state request request f13-f28.
      • getLocomotiveFunctionHighMomStatusMsg

        public static XNetMessage getLocomotiveFunctionHighMomStatusMsg​(int address)
        Given a locomotive address, request the function state (momentary status) for high functions (functions 13-28).
        Parameters:
        address - the locomotive address
        Returns:
        momentary function state request request f13-f28.
      • getSpeedAndDirectionMsg

        public static XNetMessage getSpeedAndDirectionMsg​(int address,
                                                          SpeedStepMode speedStepMode,
                                                          float speed,
                                                          boolean isForward)
        Generate a Speed and Direction Request message.
        Parameters:
        address - the locomotive address
        speedStepMode - the speedstep mode see @jmri.DccThrottle for possible values.
        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.
        Returns:
        set speed and direction message.
      • getFunctionGroup1OpsMsg

        public static XNetMessage getFunctionGroup1OpsMsg​(int address,
                                                          boolean f0,
                                                          boolean f1,
                                                          boolean f2,
                                                          boolean f3,
                                                          boolean f4)
        Generate a Function Group One Operation Request message.
        Parameters:
        address - 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:
        set function group 1 message.
      • getFunctionGroup1SetMomMsg

        public static XNetMessage getFunctionGroup1SetMomMsg​(int address,
                                                             boolean f0,
                                                             boolean f1,
                                                             boolean f2,
                                                             boolean f3,
                                                             boolean f4)
        Generate a Function Group One Set Momentary Functions message.
        Parameters:
        address - 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:
        set momentary function group 1 message.
      • getFunctionGroup2OpsMsg

        public static XNetMessage getFunctionGroup2OpsMsg​(int address,
                                                          boolean f5,
                                                          boolean f6,
                                                          boolean f7,
                                                          boolean f8)
        Generate a Function Group Two Operation Request message.
        Parameters:
        address - 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:
        set function group 2 message.
      • getFunctionGroup2SetMomMsg

        public static XNetMessage getFunctionGroup2SetMomMsg​(int address,
                                                             boolean f5,
                                                             boolean f6,
                                                             boolean f7,
                                                             boolean f8)
        Generate a Function Group Two Set Momentary Functions message.
        Parameters:
        address - 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:
        set momentary function group 2 message.
      • getFunctionGroup3OpsMsg

        public static XNetMessage getFunctionGroup3OpsMsg​(int address,
                                                          boolean f9,
                                                          boolean f10,
                                                          boolean f11,
                                                          boolean f12)
        Generate a Function Group Three Operation Request message.
        Parameters:
        address - 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:
        set function group 3 message.
      • getFunctionGroup3SetMomMsg

        public static XNetMessage getFunctionGroup3SetMomMsg​(int address,
                                                             boolean f9,
                                                             boolean f10,
                                                             boolean f11,
                                                             boolean f12)
        Generate a Function Group Three Set Momentary Functions message.
        Parameters:
        address - 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:
        set momentary function group 3 message.
      • getFunctionGroup4OpsMsg

        public static XNetMessage getFunctionGroup4OpsMsg​(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 - 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:
        set function group 4 message.
      • getFunctionGroup4SetMomMsg

        public static XNetMessage getFunctionGroup4SetMomMsg​(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 - 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:
        set momentary function group 4 message.
      • getFunctionGroup5OpsMsg

        public static XNetMessage getFunctionGroup5OpsMsg​(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 - 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:
        set function group 5 message.
      • getFunctionGroup5SetMomMsg

        public static XNetMessage getFunctionGroup5SetMomMsg​(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 - 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:
        set momentary function group 5 message.
      • getFunctionGroup6OpsMsg

        public static XNetMessage getFunctionGroup6OpsMsg​(int address,
                                                          boolean fA,
                                                          boolean fB,
                                                          boolean fC,
                                                          boolean fD,
                                                          boolean fE,
                                                          boolean fF,
                                                          boolean fG,
                                                          boolean fH)
      • getFunctionGroup7OpsMsg

        public static XNetMessage getFunctionGroup7OpsMsg​(int address,
                                                          boolean fA,
                                                          boolean fB,
                                                          boolean fC,
                                                          boolean fD,
                                                          boolean fE,
                                                          boolean fF,
                                                          boolean fG,
                                                          boolean fH)
      • getFunctionGroup8OpsMsg

        public static XNetMessage getFunctionGroup8OpsMsg​(int address,
                                                          boolean fA,
                                                          boolean fB,
                                                          boolean fC,
                                                          boolean fD,
                                                          boolean fE,
                                                          boolean fF,
                                                          boolean fG,
                                                          boolean fH)
      • getFunctionGroup9OpsMsg

        public static XNetMessage getFunctionGroup9OpsMsg​(int address,
                                                          boolean fA,
                                                          boolean fB,
                                                          boolean fC,
                                                          boolean fD,
                                                          boolean fE,
                                                          boolean fF,
                                                          boolean fG,
                                                          boolean fH)
      • getFunctionGroup10OpsMsg

        public static XNetMessage getFunctionGroup10OpsMsg​(int address,
                                                           boolean fA,
                                                           boolean fB,
                                                           boolean fC,
                                                           boolean fD,
                                                           boolean fE,
                                                           boolean fF,
                                                           boolean fG,
                                                           boolean fH)
      • getFunctionGroup6SetMomMsg

        public static XNetMessage getFunctionGroup6SetMomMsg​(int address,
                                                             boolean fA,
                                                             boolean fB,
                                                             boolean fC,
                                                             boolean fD,
                                                             boolean fE,
                                                             boolean fF,
                                                             boolean fG,
                                                             boolean fH)
      • getFunctionGroup7SetMomMsg

        public static XNetMessage getFunctionGroup7SetMomMsg​(int address,
                                                             boolean fA,
                                                             boolean fB,
                                                             boolean fC,
                                                             boolean fD,
                                                             boolean fE,
                                                             boolean fF,
                                                             boolean fG,
                                                             boolean fH)
      • getFunctionGroup8SetMomMsg

        public static XNetMessage getFunctionGroup8SetMomMsg​(int address,
                                                             boolean fA,
                                                             boolean fB,
                                                             boolean fC,
                                                             boolean fD,
                                                             boolean fE,
                                                             boolean fF,
                                                             boolean fG,
                                                             boolean fH)
      • getFunctionGroup9SetMomMsg

        public static XNetMessage getFunctionGroup9SetMomMsg​(int address,
                                                             boolean fA,
                                                             boolean fB,
                                                             boolean fC,
                                                             boolean fD,
                                                             boolean fE,
                                                             boolean fF,
                                                             boolean fG,
                                                             boolean fH)
      • getFunctionGroup10SetMomMsg

        public static XNetMessage getFunctionGroup10SetMomMsg​(int address,
                                                              boolean fA,
                                                              boolean fB,
                                                              boolean fC,
                                                              boolean fD,
                                                              boolean fE,
                                                              boolean fF,
                                                              boolean fG,
                                                              boolean fH)
      • getCSVersionRequestMessage

        public static XNetMessage getCSVersionRequestMessage()
        Generate the message to request the Command Station Hardware/Software Version.
        Returns:
        message to request CS hardware and software version.
      • getCSStatusRequestMessage

        public static XNetMessage getCSStatusRequestMessage()
        Generate the message to request the Command Station Status.
        Returns:
        message to request CS status.
      • getCSAutoStartMessage

        public static XNetMessage getCSAutoStartMessage​(boolean autoMode)
        Generate the message to set the Command Station to Auto or Manual restart mode.
        Parameters:
        autoMode - true if auto, false for manual.
        Returns:
        message to set CS restart mode.
      • getLIVersionRequestMessage

        public static XNetMessage getLIVersionRequestMessage()
        Generate the message to request the Computer Interface Hardware/Software Version.
        Returns:
        message to request interface hardware and software version.
      • getLIAddressRequestMsg

        public static XNetMessage getLIAddressRequestMsg​(int address)
        Generate the message to set or request the Computer Interface Address.
        Parameters:
        address - Interface address (0-31). Send invalid address to request the address (32-255).
        Returns:
        message to set or request interface address.
      • getLISpeedRequestMsg

        public static XNetMessage getLISpeedRequestMsg​(int speed)
        Generate the message to set or request the Computer Interface speed.
        Parameters:
        speed - 1 is 19,200bps, 2 is 38,400bps, 3 is 57,600bps, 4 is 115,200bps. Send invalid speed to request the current setting.
        Returns:
        message for set / request interface speed.
      • toMonitorString

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