Class XNetMessage

All Implemented Interfaces:
Serializable, Message
Direct Known Subclasses:
Z21XNetMessage

public class XNetMessage
extends AbstractMRMessage
implements 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
  • Field Details

  • Constructor Details

    • 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​(String s)
      Create an XNetMessage from a String containing bytes.
      Parameters:
      s - string containing data bytes.
  • Method Details

    • setOpCode

      public void setOpCode​(int i)
      Overrides:
      setOpCode in class AbstractMRMessage
    • getOpCode

      public int getOpCode()
      Overrides:
      getOpCode in class AbstractMRMessage
    • getOpCodeHex

      public String getOpCodeHex()
      Get a String representation of the op code in hex.
      Overrides:
      getOpCodeHex in class AbstractMRMessage
    • checkParity

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

      public void setParity()
    • getElementBCD

      public 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.
    • getServiceModeResultsMsg

    • getExitProgModeMsg

    • getReadPagedCVMsg

      public static XNetMessage getReadPagedCVMsg​(int cv)
    • getReadDirectCVMsg

      public static XNetMessage getReadDirectCVMsg​(int cv)
    • getWritePagedCVMsg

      public static XNetMessage getWritePagedCVMsg​(int cv, int val)
    • getWriteDirectCVMsg

      public static XNetMessage getWriteDirectCVMsg​(int cv, int val)
    • getReadRegisterMsg

      public static XNetMessage getReadRegisterMsg​(int reg)
    • getWriteRegisterMsg

      public static XNetMessage getWriteRegisterMsg​(int reg, int val)
    • getWriteOpsModeCVMsg

      public static XNetMessage getWriteOpsModeCVMsg​(int AH, int AL, int cv, int val)
    • getVerifyOpsModeCVMsg

      public static XNetMessage getVerifyOpsModeCVMsg​(int AH, int AL, int cv, int val)
    • getBitWriteOpsModeCVMsg

      public static XNetMessage getBitWriteOpsModeCVMsg​(int AH, int AL, int cv, int bit, boolean value)
    • getBitVerifyOpsModeCVMsg

      public static XNetMessage getBitVerifyOpsModeCVMsg​(int AH, int AL, int cv, int bit, boolean value)
    • 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.
    • getAddressedEmergencyStop

      public static XNetMessage getAddressedEmergencyStop​(int address)
    • 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.
    • getResumeOperationsMsg

      Build a Resume operations Message.
      Returns:
      resume message.
    • getEmergencyOffMsg

      Build an EmergencyOff Message.
      Returns:
      emergency off message.
    • getEmergencyStopMsg

      Build an EmergencyStop Message.
      Returns:
      emergency stop message.
    • getCSVersionRequestMessage

      Generate the message to request the Command Station Hardware/Software Version.
      Returns:
      message to request CS hardware and software version.
    • 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

      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

      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.