Package org.ka2ddo.aprs

Class PositionMessage

java.lang.Object
org.ka2ddo.ax25.AX25Message
org.ka2ddo.aprs.Message
org.ka2ddo.aprs.PositionMessage
All Implemented Interfaces:
Serializable, Cloneable, Comparable<AX25Message>, CommentedMessage
Direct Known Subclasses:
GpsRawMessage, MaidenheadLocatorBeacon, MicE, ObjectReport, PositionReport
public abstract class PositionMessage extends Message
This abstract class extends Message to contain positional information, supporting several different kinds of APRS messages with position data.
Author:
Andrew Pavlin, KA2DDO
See Also:

  • Field Details

    • DHM

      protected static final String DHM
      Date format to parse day and hours:minutes (in UTC) for a longer delta into the past.
      See Also:

    • HMS

      protected static final String HMS
      Date format to decode hours/minutes/seconds timestamp string.
      See Also:

    • fmtMonitorFreq

      protected static final DecimalFormat fmtMonitorFreq
      Format string for APRS-standard frequency format.

    • COMPRESSED_LAT_SCALING

      public static final float COMPRESSED_LAT_SCALING
      Conversion scaling constant for encoding latitude in APRS compressed-text format.
      See Also:

    • ONE_DEGREE_F

      public static final float ONE_DEGREE_F
      Ambiguity value for one-degree resolution.
      See Also:

    • TEN_MINUTES_F

      public static final float TEN_MINUTES_F
      Ambiguity value for ten-minute resolution.
      See Also:

    • ONE_MINUTE_F

      public static final float ONE_MINUTE_F
      Ambiguity value for one-minute resolution.
      See Also:

    • TENTH_MINUTE_F

      public static final float TENTH_MINUTE_F
      Ambiguity value for tenth-of-a-minute resolution.
      See Also:

    • HUNDREDTH_MINUTE_F

      public static final float HUNDREDTH_MINUTE_F
      Ambiguity value for hundredth-of-a-minute resolution.
      See Also:

    • CONV_MPH_TO_METERS_PER_SEC

      public static final float CONV_MPH_TO_METERS_PER_SEC
      Convenience constant to convert statute miles-per-hour to meters-per-second.

    • LN_BASE1_08

      protected static final double LN_BASE1_08
      Scaling factor for encoding speed with compressed position.

    • latitude

      protected String latitude
      The latitude of this position in APRS text format DDMM.MMn.

    • longitude

      protected String longitude
      The longitude of this position in APRS text format DDDMM.MMw.

    • fLatitude

      protected double fLatitude
      Latitude in fractional degrees North, or NaN if not filled in yet.

    • fLongitude

      protected double fLongitude
      Longitude in fractional degrees East, or NaN if not filled in yet.

    • fLatPrecision

      protected float fLatPrecision
      The ambiguity level of the latitude in fractional degrees,

    • altitude

      public int altitude
      The altitude of this position in meters above mean sea level, or Integer.MIN_VALUE for unknown.

    • altitudeUnit

      public DistanceUnit altitudeUnit
      The unit for the altitude measurement.

    • abc

      protected byte abc
      The Mic-E status code ordinal, where 0 is Emergency and -1 means that no Mic-E status code is defined by this message.

    • isCustom

      protected boolean isCustom
      If true, indicates that the Mic-E status code should be treated as a custom value rather than the common standard meanings for the ordinal values 1 to 7.

    • enabledForTransmit

      protected boolean enabledForTransmit
      Indicate whether or not this position message is transmittable by this station.

  • Constructor Details

    • PositionMessage

      protected PositionMessage()
      Create an uninitialized PositionMessage (let the subclass initialize it).

    • PositionMessage

      protected PositionMessage(byte msgType, String tp, long rcptTime)
      Create a partially-initialized PositionMessage.
      Parameters:
      msgType - msgType character (should correspond to the subclass being created)
      tp - third-party routing string, or null if this message is still on its original network
      rcptTime - time in Java milliseconds in 1 Jan 1970 UTC when this message was received

  • Method Details

    • extractLatitude

      protected int extractLatitude(byte[] body, int pos) throws IllegalArgumentException
      Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed latitude expression. The decoded latitude is stored in the PositionMessage's latitude field.
      Parameters:
      body - byte array containing the message
      pos - int into array where latitude expression should start
      Returns:
      index immediately following the latitude expression
      Throws:
      IllegalArgumentException - if the pointed string is not a valid latitude expression
      See Also:

    • decodeLatitude

      public double decodeLatitude()
      Get the latitude from this PositionMessage in decimal degrees North.
      Returns:
      fractional degrees North latitude

    • decodeOnlyLatitude

      public static double decodeOnlyLatitude(String latitude)
      Decode standard long-format latitude without caring about the accuracy.
      Parameters:
      latitude - String in standard ddmm.mmN latitude format
      Returns:
      latitude in fractional degrees North

    • getLatitudeAccuracy

      public float getLatitudeAccuracy()
      Computes the precision of the latitude value in fractional degrees
      Returns:
      the double precision least significant digit range in fractional degrees

    • testIfValidCompressedLocation

      protected static boolean testIfValidCompressedLocation(byte[] body, int offset)
      Test if the passed APRS byte array looks like a valid compressed-mode APRS position.
      Parameters:
      body - byte array supposedly containing an APRS position
      offset - int array index into body where the position expression starts
      Returns:
      boolean true if this appears to be a valid compressed-mode position

    • extractCompressedLatitude

      protected String extractCompressedLatitude(byte[] body, int offset)
      Decode a compressed format latitude from a byte array.
      Parameters:
      body - byte array containing the latitude information
      offset - index into the byte array where the latitude information starts
      Returns:
      APRS standard text-format latitude

    • encodeLatitudePlainText

      public static String encodeLatitudePlainText(double latitude)
      Convert a double-precision fractional degrees North latitude into APRS-standard string format. Note this can only return the value without extra ambiguity, because there is no way to specify the amount of ambiguity in this method.
      Parameters:
      latitude - the floating-point latitude value
      Returns:
      the String representation of the latitude

    • encodeLatitudeCompressed

      public static String encodeLatitudeCompressed(double latitude)
      Convert a double-precision fractional degrees North latitude into APRS-standard compressed string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.
      Parameters:
      latitude - the floating-point latitude value
      Returns:
      the compressed String representation of the latitude

    • extractLongitude

      protected int extractLongitude(byte[] body, int pos) throws IllegalArgumentException
      Service method to decode a fragment of an AX.25 frame that is supposed to contain an APRS-standard non-compressed longitude expression. The decoded longitude is stored in the PositionMessage's longitude field. This also supports non-standard shortened longitudes with only 2-digit degree values.
      Parameters:
      body - byte array containing the message
      pos - int into array where longitude expression should start
      Returns:
      index immediately following the longitude expression
      Throws:
      IllegalArgumentException - if the pointed string is not a valid longitude expression
      See Also:

    • extractCompressedLongitude

      protected String extractCompressedLongitude(byte[] body, int offset)
      Decode a compressed format longitude from a byte array.
      Parameters:
      body - byte array containing the longitude information
      offset - index into the byte array where the longitude information starts
      Returns:
      APRS standard text-format longitude

    • decodeLongitude

      public double decodeLongitude()
      Get the longitude from this PositionMessage in decimal degrees East.
      Returns:
      fractional degrees East longitude

    • decodeOnlyLongitude

      public static double decodeOnlyLongitude(String longitude)
      Decode the specified String as a standard-format longitude "dddmm.mmE".
      Parameters:
      longitude - String to decode as a longitude
      Returns:
      longitude in fractional degrees East

    • encodeLongitudePlainText

      public static String encodeLongitudePlainText(double longitude)
      Convert a double-precision fractional degrees East longitude into APRS-standard string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.
      Parameters:
      longitude - the floating-point longitude value
      Returns:
      the String representation of the longitude

    • encodeLongitudeCompressed

      public static String encodeLongitudeCompressed(double longitude)
      Convert a double-precision fractional degrees East longitude into APRS-standard compressed string format. Note this can only return the maximum precision, because there is no way to specify the lack of precision.
      Parameters:
      longitude - the floating-point longitude value
      Returns:
      the compressed String representation of the latitude

    • setLocation

      public void setLocation(double latitude, double longitude)
      Set the latitude and longitude of this PositionMessage to the desired coordinates.
      Parameters:
      latitude - latitude in fractional degrees North
      longitude - longitude in fractional degrees East

    • setAmbiguity

      public void setAmbiguity(float ambiguityDeg)
      Set the ambiguity of position for this position report. Note that this should be called after setting the position, so there is a current position to ambiguate.
      Parameters:
      ambiguityDeg - ambiguity of position in fractional degrees
      See Also:

    • decodeDataExtension

      public int decodeDataExtension(byte[] body, int pos)
      Decode data extension if it exists. The following extensions are supported:
      • /A=nnnnnn
      • cse/spd (with optional DF bearing, number/range/quality, hurricane/tropical storm data, or dir/spd)
      • PHGphgd
      • RNGrrrr
      • DFSshgd
      • Tyy/Cxx (first, only if symbol is \l)
      • fff.fffMHz Tnnn +nnn (and variations thereof)
      • weather data (only if symbol code is _ )
      • supported digipeat aliases (Wn[,SSn-N])
      Parameters:
      body - byte array containing the message
      pos - starting index in array
      Returns:
      updated index in array

    • looksLikeFrequency

      protected static boolean looksLikeFrequency(byte[] body, int pos)
      Check if the ASCII character sequence in a byte array contains something that looks like an APRS frequency value.
      Parameters:
      body - byte array to search
      pos - zero-based index into array to start pattern match
      Returns:
      boolean true if specified index has a ddd.ddd pattern in it

    • looksLikeFrequency

      protected static boolean looksLikeFrequency(String body, int pos)
      Check if the character sequence in a String contains something that looks like an APRS frequency value.
      Parameters:
      body - byte array to search
      pos - zero-based index into array to start pattern match
      Returns:
      boolean true if specified index has a ddd.ddd pattern in it

    • paramString

      public String paramString()
      Descriptive text about this message, to be included in the toString() method's response.
      Overrides:
      paramString in class Message
      Returns:
      String describing the contents of this message
      See Also:

    • isShowDate

      public boolean isShowDate()
      Test whether a transmission of this message should include the timestamp.
      Returns:
      boolean true if timestamp is included

    • setShowDate

      public void setShowDate(boolean showDate)
      Specify whether this message should include the timestamp when transmitted or displayed.
      Parameters:
      showDate - boolean true to show the timestamp (separate from the receive time)

    • hasPosition

      public boolean hasPosition()
      Report if this AX25Message contains position data.
      Overrides:
      hasPosition in class AX25Message
      Returns:
      boolean true if message contains position information

    • getLatitude

      public String getLatitude()
      Get the string format latitude of this message.
      Returns:
      latitude String

    • getLongitude

      public String getLongitude()
      Get the string format longitude of this message.
      Returns:
      longitude String

    • setLatitude

      public void setLatitude(String latitude) throws IllegalArgumentException
      Set the string format latitude of this message.
      Parameters:
      latitude - String latitude to use
      Throws:
      IllegalArgumentException - if string has illegal format

    • setLongitude

      public void setLongitude(String longitude) throws IllegalArgumentException
      Set the string format longitude of this message.
      Parameters:
      longitude - String longitude to use
      Throws:
      IllegalArgumentException - if string has illegal format

    • getAltitude

      public int getAltitude()
      Get the altitude of this position relative to mean sea level.
      Returns:
      altitude in the specified units or Integer,MIN_VALUE to indicate the altitude is unknown
      See Also:

    • getAltitudeUnit

      public DistanceUnit getAltitudeUnit()
      Get the size unit for altitude in this position message.
      Returns:
      DistanceUnit for this message's altitude

    • appendAreaParameters

      protected static void appendAreaParameters(StringBuilder b, Map<Enum,Object> extensionMap)
      Appends the area "symbol" parameters to a StringBuilder for producing a transmittable version of this position message.
      Parameters:
      b - StringBuilder to add area parameters to
      extensionMap - Map of message extensions containing the area information

    • appendSignpostParameters

      protected static void appendSignpostParameters(StringBuilder b, Map<Enum,Object> extensionMap)
      Appends the signpost parameters (if any) to a StringBuilder for producing a transmittable version of this position message.
      Parameters:
      b - StringBuilder to add area parameters to
      extensionMap - Map of message extensions containing the signpost information

    • appendRepeaterParameters

      protected void appendRepeaterParameters(StringBuilder b)
      Appends the repeater parameters (if any) to a StringBuilder for producing a transmittable version of this position message.
      Parameters:
      b - StringBuilder to add repeater/monitor parameters to

    • getAbc

      public byte getAbc()
      Returns the decoded MicE status (if any) from this PositionMessage.
      Returns:
      MicE status code, or -1 if this PositionMessage does not contain a MicE status code

    • setAbc

      public void setAbc(byte abc)
      Set the encoded MicE status (if any) for this PositionMessage.
      Parameters:
      abc - MicE status code, or -1 if this PositionMessage should not contain a MicE status code

    • isCustom

      public boolean isCustom()
      Indicate whether the MicE status code is a standard code or a custom code.
      Returns:
      boolean true if custom MicE status, boolean false if standard MicE status or this message does not have MicE status

    • setCustom

      public void setCustom(boolean isCustom)
      Specify whether the MicE status code is a standard code or a custom code.
      Parameters:
      isCustom - boolean true if custom MicE status, boolean false if standard MicE status or this message does not have MicE status (ignored if status is EMERGENCY)

    • isEnabled

      public boolean isEnabled()
      Test if message should still be transmitted.
      Returns:
      boolean true if message should still be transmitted

    • createObjectFromThisPosition

      public ObjectReport createObjectFromThisPosition()
      Create an ObjectReport from this PositionMessage.
      Returns:
      new ObjectReport cloned from this PositionMessage

    • isUsingCompressedFormat

      public boolean isUsingCompressedFormat()
      Indicates whether this PositionMessage is using compressed-mode (but not Mic-E) encoding of latitude and longitude, because this affects what are legal symbol overlay codes. Intended to be overridden by appropriate subclasses.
      Returns:
      boolean true if compressed encoding in use

    • bodyEquals

      public boolean bodyEquals(AX25Message o)
      Compare the contents of the body of the message, reporting if they match.
      Overrides:
      bodyEquals in class Message
      Parameters:
      o - another AX25Message to compare against
      Returns:
      boolean true if the body values are equivalent