Class LocoNetMessage

java.lang.Object
jmri.jmrix.AbstractMessage
jmri.jmrix.loconet.LocoNetMessage
All Implemented Interfaces:
Serializable, Message

public class LocoNetMessage
extends AbstractMessage
implements Serializable
Represents a single command or response on the LocoNet.

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.

Note that this class does not manage the upper bit of the message. By convention, most LocoNet messages have the upper bit set on the first byte, and on no other byte; but not all of them do, and that must be managed elsewhere.

Note that many specific message types are created elsewhere. In general, if more than one tool will need to use a particular format, it's useful to refactor it to here.


This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Some of the message formats used in this class are Copyright Digitrax, Inc. and used with permission as part of the JMRI project. That permission does not extend to uses in other software products. If you wish to use this code, algorithm or these message formats outside of JMRI, please contact Digitrax Inc for separate permission.

See Also:
NceMessage, AbstractMessage, Serialized Form
  • Field Summary

    Fields 
    Modifier and Type Field Description
    (package private) static char[] hexChars  
    (package private) static long serialVersionUID  

    Fields inherited from class jmri.jmrix.AbstractMessage

    _dataChars, _nDataChars
  • Constructor Summary

    Constructors 
    Constructor Description
    LocoNetMessage()
    Create a LocoNetMessage object without providing any indication of its size or contents.
    LocoNetMessage​(byte[] contents)
    Create a message with specified contents.
    LocoNetMessage​(int len)
    Create a new object, representing a specific-length message.
    LocoNetMessage​(int[] contents)
    Create a message with specified contents.
    LocoNetMessage​(String s)
    Create a LocoNetMessage from a String
    LocoNetMessage​(LocoNetMessage original)  
  • Method Summary

    Modifier and Type Method Description
    boolean checkParity()
    Check whether the message has a valid checksum.
    boolean equals​(Object o)
    Two messages are the same if their entire data content is the same.
    int getElement​(int n)
    Get a specific byte from the message
    int getOpCode()  
    String getOpCodeHex()
    Get a String representation of the op code in hex.
    int[] getPeerXfrData()
    Get the 8 data bytes from an OPC_PEER_XFR message.
    int hashCode()
    Hash code from base data.
    protected static boolean highBit​(int val)
    Check if a high bit is set, usually used to store it in some other location (LocoNet does not allow the high bit to be set in data bytes).
    protected static int highByte​(int val)  
    int inputRepAddr()
    If this is an OPC_INPUT_REP, get the 0-n address, else -1
    protected static int lowByte​(int val)  
    static LocoNetMessage makePeerXfr​(int src, int dst, int[] d, int code)
    Return a newly created OPC_PEER_XFR message.
    int sensorAddr()
    Extract sensor address from a sensor message.
    void setElement​(int n, int v)
    set a specific byte at a specific index in the message
    void setOpCode​(int i)  
    void setParity()
    Set the checksum byte(s) of this message.
    String toMonitorString()
    Interprets a LocoNet message into a string describing the message.
    String toMonitorString​(String prefix)
    Interprets a LocoNet message into a string describing the message when a specific connection prefix is known.
    String toString()
    Get a String representation of the entire message in hex.
    int turnoutAddr()
    Get turnout address.

    Methods inherited from class jmri.jmrix.AbstractMessage

    getNumDataElements

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

  • Constructor Details

    • LocoNetMessage

      public LocoNetMessage()
      Create a LocoNetMessage object without providing any indication of its size or contents.

      Because a LocoNet message requires at least a size, if not actual contents, this constructor always logs an error.

    • LocoNetMessage

      public LocoNetMessage​(int len)
      Create a new object, representing a specific-length message.

      Logs an error if len is less than 2

      Parameters:
      len - Total bytes in message, including opcode and error-detection byte.
    • LocoNetMessage

      public LocoNetMessage​(String s)
      Create a LocoNetMessage from a String

      Because it is difficult to create a complete LocoNet object using a string, this method of AbstractMessage is not supported.

      This constructor always logs an error

      Parameters:
      s - an unused parameter
    • LocoNetMessage

      public LocoNetMessage​(int[] contents)
      Create a message with specified contents.

      This method logs an error and returns if the contents are too short to represent a valid LocoNet message.

      Parameters:
      contents - The array of contents for the message. The error check word must be present, e.g. a 4-byte message must have four values in the array
    • LocoNetMessage

      public LocoNetMessage​(byte[] contents)
      Create a message with specified contents. Each element is forced into an 8-bit value.

      This method logs an error and returns if the message length is too short to represent a valid LocoNet message.

      Parameters:
      contents - The array of contents for the message. The error check word must be present, e.g. a 4-byte message must have four values in the array
    • LocoNetMessage

      public LocoNetMessage​(LocoNetMessage original)
  • Method Details

    • setOpCode

      public void setOpCode​(int i)
    • getOpCode

      public int getOpCode()
    • getOpCodeHex

      public String getOpCodeHex()
      Get a String representation of the op code in hex.
      Returns:
      string containing a hexadecimal representation of the message OpCode
    • getElement

      public int getElement​(int n)
      Get a specific byte from the message

      Logs an error and aborts if the index is beyond the length of the message.

      Specified by:
      getElement in interface Message
      Overrides:
      getElement in class AbstractMessage
      Parameters:
      n - the byte index within the message
      Returns:
      integer value of the byte at the index within the message
    • setElement

      public void setElement​(int n, int v)
      set a specific byte at a specific index in the message

      Logs an error and aborts if the index is beyond the length of the message.

      Specified by:
      setElement in interface Message
      Overrides:
      setElement in class AbstractMessage
      Parameters:
      n - the byte index within the message
      v - the value to be set
    • toString

      public String toString()
      Get a String representation of the entire message in hex.
      Specified by:
      toString in interface Message
      Overrides:
      toString in class Object
      Returns:
      a string representation containing a space-delimited set of hexadecimal values.
    • setParity

      public void setParity()
      Set the checksum byte(s) of this message.
    • checkParity

      public boolean checkParity()
      Check whether the message has a valid checksum.
      Returns:
      true if checksum is correct, else false
    • getPeerXfrData

      public int[] getPeerXfrData()
      Get the 8 data bytes from an OPC_PEER_XFR message.
      Returns:
      int[8] data bytes
    • equals

      public boolean equals​(Object o)
      Two messages are the same if their entire data content is the same. We ignore the error-check byte to ease comparisons before a message is transmitted.
      Overrides:
      equals in class AbstractMessage
      Returns:
      true if objects contain the same message contents
    • hashCode

      public int hashCode()
      Description copied from class: AbstractMessage
      Hash code from base data.
      Overrides:
      hashCode in class AbstractMessage
      Returns:
      hashcode from sum of elements.
    • toMonitorString

      Interprets a LocoNet message into a string describing the message.

      Where appropriate, this method presents both the JMRI "System Name" and the JMRI "User Name" (where available) for messages which contain control or status information for a Turnout, Sensor or Reporter.

      Display of "User Name" information is acquired from the appropriate "manager", via a reference to an object with an assembled "System Name". This method assumes a system connection "prefix" of "L" when assembling that system name. The remainder of the assembled system name depends on the message contents - message type determines which JMRI object type letter to add - "T" for turnouts, "S" for sensors, and "R" for transponding reporters.

      If the appropriate manager already has an object for the system name being referenced, the method requests the associated user name. If a user name is returned, then the method uses that user name as part of the message. If there is no associated JMRI object configured, or if the associated JMRI object does not have a user name assigned, then the method does not display a user name.

      The method is not appropriate when the user has multiple LocoNet connections or when the user has a single LocoNet connection but has changed the connection prefix to something other than the default of "L".

      Specified by:
      toMonitorString in interface Message
      Returns:
      a human readable representation of the message.
    • toMonitorString

      public String toMonitorString​(@Nonnull String prefix)
      Interprets a LocoNet message into a string describing the message when a specific connection prefix is known.

      Where appropriate, this method presents both the JMRI "System Name" and the JMRI "User Name" (where available) for messages which contain control or status information for a Turnout, Sensor or Reporter.

      Display of "User Name" information is acquired from the appropriate "manager", via a reference to an object with an assembled "System Name". This method uses system connection "prefix" as specified in the "prefix" argument when assembling that system name. The remainder of the assembled system name depends on the message contents. Message type determines which JMRI object type letter is added after the "prefix" - "T" for turnouts, * "S" for sensors, and "R" for transponding reporters. The item number specified in the LocoNet message is appended to finish the system name.

      If the appropriate manager already has an object for the system name being referenced, the method requests the associated user name. If a user name is returned, then the method uses that user name as part of the message. If there is no associated JMRI object configured, or if the associated JMRI object does not have a user name assigned, then the method does not display a user name.

      Parameters:
      prefix - the "System Name" prefix denoting the connection
      Returns:
      a human readable representation of the message.
    • makePeerXfr

      public static LocoNetMessage makePeerXfr​(int src, int dst, int[] d, int code)
      Return a newly created OPC_PEER_XFR message.
      Parameters:
      src - Source address
      dst - Destination address
      d - int[8] for the data contents or null
      code - The instruction code placed in the pcxt1 pcxt2 bytes
      Returns:
      The formatted message
    • highBit

      protected static boolean highBit​(int val)
      Check if a high bit is set, usually used to store it in some other location (LocoNet does not allow the high bit to be set in data bytes).
      Parameters:
      val - value to be checked
      Returns:
      True if the argument has the high bit set
    • lowByte

      protected static int lowByte​(int val)
    • highByte

      protected static int highByte​(int val)
    • sensorAddr

      public int sensorAddr()
      Extract sensor address from a sensor message. Does not verify that the message is a sensor message.
      Returns:
      address (in range 0 to n-1)
    • inputRepAddr

      public int inputRepAddr()
      If this is an OPC_INPUT_REP, get the 0-n address, else -1
      Returns:
      address (in range 0 to n-1)
    • turnoutAddr

      public int turnoutAddr()
      Get turnout address. Does not check to see that the message is a turnout message.
      Returns:
      address (in range 1 to n )