Package org.ka2ddo.ax25
Class AX25Frame
java.lang.Object
org.ka2ddo.ax25.AX25Frame
- All Implemented Interfaces:
Serializable
,Comparable<AX25Frame>
,AX25FrameSource
public class AX25Frame
extends Object
implements Serializable, AX25FrameSource, Comparable<AX25Frame>
This class defines 1 AX.25 packet, as defined by the AX.25 Link Level Protocol specification,
version 2.2. Note that the Comparable interface is simply sorting
by rcptTime.
- Version:
- 2.2
- Author:
- Andrew Pavlin, KA2DDO
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionbyte[]
Byte array containing the higher-level protocol payload for I and UI frames.byte
Bitmask identifying the frame type and subtype, and windowing position for connection-oriented I and S frames.byte
Extension of ctl when using 128-segment windowing.Callsign of the destination station, or some broadcast code with an alternate meaning (such as APRS tocalls and Mic-E encoded latitude and status values).Optional array of digipeater callsigns and aliases, if this frame should be digipeated.static final int
Numeric code for information (I) frame type.static final int
Numeric code for supervisory (S) frame type.static final int
Numeric code for unnumbered (U) frame type.static final int
The bitmask to extract the frametype bits from the ctl byte of the frame.static final int
Bitmask to extract supervisory (S) frame subtype from the ctl byte.static final int
Bitmask to extract poll/final bit from unnumbered (U) frame ctl byte, mod 8 format.static final int
Bitmask to extract poll/final bit from I/S frame 2nd ctl byte, mod 128 format.static final int
Bitmask to extract unnumbered (U) frame subtype from the ctl byte.boolean
Indicates whether 128-segment windowing is used for I frame connections.The decoded APRS (or other protocol) message (if the AX25Frame contains a higher-level protocol).byte
The one-byte code identifying how to interpret the body of I and UI frames.static final byte
Protocol ID for Appletalk Address Resolution Protocol (ARP).static final byte
Protocol ID for Appletalk.static final byte
Protocol ID for escape code indicating second byte of PID (not supported).static final byte
Protocol ID for FlexNet.static final byte
Protocol ID for ARPA Internet Address Resolution Protocol (ARP).static final byte
Protocol ID for ARPA Internet Protocol.static final byte
Protocol ID for Link Quality Protocol.static final byte
Protocol ID for NET/ROM.static final byte
Protocol ID for no level 3 protocol (also used for APRS).static final byte
Protocol ID for OpenTRAC.static final byte
Protocol ID for AX.25 segmentation fragment.static final byte
Protocol ID for TEXNET datagram.static final byte
Protocol ID for Van Jacobson compressed TCP/IP packet, per RFC 1144.static final byte
Protocol ID for Van Jacobson uncompressed TCP/IP packet, per RFC 1144.static final byte
Protocol ID for CCITT X.25 PLP (also used by the ROSE network).Hashmap of Information (I) or Unnumbered Information (UI) frame protocol ID to protocol name strings.long
The time when this message was received in Java milliseconds since midnight, Jan 1 1970 UTC.Callsign of the transmitting station (not of any intermediate digipeaters).static final int
Bit shift to get least significant bit of S frame subtype into least significant bit of integer.static final int
Bit shift to get least significant bit of U frame subtype into least significant bit of integer.Pointer to the I/O port from which this frame was received.static final int
Unshifted S frame subtype for Reject frame.static final int
Unshifted S frame subtype for Receive Not Ready frame.static final int
Unshifted S frame subtype for Receive Ready frame.static final int
Unshifted S frame subtype for Selective Reject frame.static final int
Unshifted U frame subtype for Disconnect (DISC).static final int
Unshifted U frame subtype for Disconnected Mode (DM).static final int
Deprecated.2.0static final int
Unshifted U frame subtype for Set Asynchronous Balanced Mode (SABM).static final int
Unshifted U frame subtype for Set Asynchronous Balanced Mode Extended (SABME).static final int
Unshifted U frame subtype for Test (TEST).static final int
Unshifted U frame subtype for Unnumbered Acknowledge (UA).static final int
Unshifted U frame subtype for Unnumbered Information (UI).static final int
Unshifted U frame subtype for Exchange Identification (XID).Fields inherited from interface org.ka2ddo.ax25.AX25FrameSource
NO_FRAMES
-
Constructor Summary
ConstructorsConstructorDescriptionCreate an empty AX25Frame initialized for a UI frame containing an APRS packet. -
Method Summary
Modifier and TypeMethodDescriptionint
Compares this object with the specified object for order.static AX25Frame
decodeFrame
(byte[] buf, int offset, int length) Create a AX25Frame from a byte array presumed to contain an AX.25 protocol sequence.dup()
Create a deep copy of this frame.Create a deep copy of this frame, excluding the body.boolean
Indicates whether some other object is "equal to" this one.static int
findSTypeByName
(String sTypeName) Given a string name, get the numeric S-type value for that type of AX.25 frame.static int
findUTypeByName
(String uTypeName) Given a string name, get the numeric U-type value for that type of AX.25 frame.Produce an ASCIIfied version of frame body.int
Compute a checksum for this frame to allow efficiently identifying duplicate frames.Specify the Connector this message should be transmitted through.int
Estimate the number of bits needed to transmit this frame over RF in AX.25 standard physical layer (HDLC).static String
getFirstDigi
(AX25Callsign[] digipeaters) Get the first actual digipeated digipeater station callsign in the digipeater sequence.getFrames
(boolean incrementXmtCount, ProtocolFamily protocolId, String senderCallsign) Get the frames associated with this FrameSource (in this case, itself).int
Get the type of this frame, as stored in the ctl byte.Generate a string describing the type of the frame.static String
getLastDigi
(AX25Callsign[] digipeaters) Find the last callsign through which a frame has been digipeated.int
getNR()
Get the reception sequence number.int
getNS()
Get the transmission sequence number.static String
getNthDigi
(AX25Callsign[] digipeaters, int index) Get the Nth digipeated digipeater station callsign in the digipeater sequence.int
Get number of times frame will be retransmitted before inter-packet delay is increased.boolean
getP()
Get poll bit.Get the protocol family or families that this message corresponds to, so ports that don't support all protocols will not forward inappropriate packets.int
getSType()
Get the Supervisory frame subtype.int
getUType()
Get Unordered frame subtype.int
hashCode()
Returns a hash code value for the object.static void
Properly set the isCmd flag of a frame based on theAX25Callsign.h_c
bits in the sender and destination addresses.boolean
isDirect()
Test if this message was sent directly (without any relay station).boolean
isDuplicate
(AX25Frame other) Test if this frame has the same contents (at least as regards duplicate checking) as the provided older frame.static boolean
isRealCallsign
(String callsign) Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase).isRf
(int maxDigis) Test if this AX25Frame came from an RF connection.boolean
isValid()
Report whether this packet is strictly valid according to the AX.25 protocol specification,void
setCmd
(boolean isCmd) Set the command bits in the sender and destination fields.toString()
Return a String representing this AX25Frame object.void
write
(OutputStream os) Transmit this AX25Frame to an output byte stream.
-
Field Details
-
sender
Callsign of the transmitting station (not of any intermediate digipeaters). -
dest
Callsign of the destination station, or some broadcast code with an alternate meaning (such as APRS tocalls and Mic-E encoded latitude and status values). -
digipeaters
Optional array of digipeater callsigns and aliases, if this frame should be digipeated. May have up to 8 elements in the array. -
sourcePort
Pointer to the I/O port from which this frame was received. -
ctl
public byte ctlBitmask identifying the frame type and subtype, and windowing position for connection-oriented I and S frames.- See Also:
-
ctl2
public byte ctl2Extension of ctl when using 128-segment windowing. -
pid
public byte pidThe one-byte code identifying how to interpret the body of I and UI frames. -
body
public byte[] bodyByte array containing the higher-level protocol payload for I and UI frames. -
mod128
public boolean mod128Indicates whether 128-segment windowing is used for I frame connections. If this is false, the backwards-compatible 8-segment windowing is used. -
rcptTime
public long rcptTimeThe time when this message was received in Java milliseconds since midnight, Jan 1 1970 UTC. -
parsedAX25Msg
The decoded APRS (or other protocol) message (if the AX25Frame contains a higher-level protocol). May be null. -
MASK_FRAMETYPE
public static final int MASK_FRAMETYPEThe bitmask to extract the frametype bits from the ctl byte of the frame.- See Also:
-
FRAMETYPE_I
public static final int FRAMETYPE_INumeric code for information (I) frame type.- See Also:
-
FRAMETYPE_S
public static final int FRAMETYPE_SNumeric code for supervisory (S) frame type.- See Also:
-
FRAMETYPE_U
public static final int FRAMETYPE_UNumeric code for unnumbered (U) frame type.- See Also:
-
MASK_STYPE
public static final int MASK_STYPEBitmask to extract supervisory (S) frame subtype from the ctl byte.- See Also:
-
SHIFT_STYPE
public static final int SHIFT_STYPEBit shift to get least significant bit of S frame subtype into least significant bit of integer.- See Also:
-
STYPE_RR
public static final int STYPE_RRUnshifted S frame subtype for Receive Ready frame.- See Also:
-
STYPE_RNR
public static final int STYPE_RNRUnshifted S frame subtype for Receive Not Ready frame.- See Also:
-
STYPE_REJ
public static final int STYPE_REJUnshifted S frame subtype for Reject frame.- See Also:
-
STYPE_SREJ
public static final int STYPE_SREJUnshifted S frame subtype for Selective Reject frame.- See Also:
-
MASK_UTYPE
public static final int MASK_UTYPEBitmask to extract unnumbered (U) frame subtype from the ctl byte.- See Also:
-
MASK_U_P
public static final int MASK_U_PBitmask to extract poll/final bit from unnumbered (U) frame ctl byte, mod 8 format.- See Also:
-
MASK_U_P128
public static final int MASK_U_P128Bitmask to extract poll/final bit from I/S frame 2nd ctl byte, mod 128 format.- See Also:
-
SHIFT_UTYPE
public static final int SHIFT_UTYPEBit shift to get least significant bit of U frame subtype into least significant bit of integer.- See Also:
-
UTYPE_UI
public static final int UTYPE_UIUnshifted U frame subtype for Unnumbered Information (UI).- See Also:
-
UTYPE_DM
public static final int UTYPE_DMUnshifted U frame subtype for Disconnected Mode (DM).- See Also:
-
UTYPE_SABM
public static final int UTYPE_SABMUnshifted U frame subtype for Set Asynchronous Balanced Mode (SABM). Only allowed window sizing for AX.25 V2.0 stations.- See Also:
-
UTYPE_DISC
public static final int UTYPE_DISCUnshifted U frame subtype for Disconnect (DISC).- See Also:
-
UTYPE_UA
public static final int UTYPE_UAUnshifted U frame subtype for Unnumbered Acknowledge (UA).- See Also:
-
UTYPE_SABME
public static final int UTYPE_SABMEUnshifted U frame subtype for Set Asynchronous Balanced Mode Extended (SABME). Only usable between AX.25 V2.2 stations.- Since:
- 2.2
- See Also:
-
UTYPE_FRMR
public static final int UTYPE_FRMRDeprecated.2.0Unshifted U frame subtype for obsolete Frame Reject (FRMR).- See Also:
-
UTYPE_XID
public static final int UTYPE_XIDUnshifted U frame subtype for Exchange Identification (XID).- See Also:
-
UTYPE_TEST
public static final int UTYPE_TESTUnshifted U frame subtype for Test (TEST).- See Also:
-
PID_X25_PLP
public static final byte PID_X25_PLPProtocol ID for CCITT X.25 PLP (also used by the ROSE network).- See Also:
-
PID_VJC_TCPIP
public static final byte PID_VJC_TCPIPProtocol ID for Van Jacobson compressed TCP/IP packet, per RFC 1144.- See Also:
-
PID_VJUC_TCPIP
public static final byte PID_VJUC_TCPIPProtocol ID for Van Jacobson uncompressed TCP/IP packet, per RFC 1144.- See Also:
-
PID_SEG_FRAG
public static final byte PID_SEG_FRAGProtocol ID for AX.25 segmentation fragment.- See Also:
-
PID_OPENTRAC
public static final byte PID_OPENTRACProtocol ID for OpenTRAC.- See Also:
-
PID_TEXNET
public static final byte PID_TEXNETProtocol ID for TEXNET datagram.- See Also:
-
PID_LQP
public static final byte PID_LQPProtocol ID for Link Quality Protocol.- See Also:
-
PID_ATALK
public static final byte PID_ATALKProtocol ID for Appletalk.- See Also:
-
PID_AARP
public static final byte PID_AARPProtocol ID for Appletalk Address Resolution Protocol (ARP).- See Also:
-
PID_IP
public static final byte PID_IPProtocol ID for ARPA Internet Protocol.- See Also:
-
PID_IARP
public static final byte PID_IARPProtocol ID for ARPA Internet Address Resolution Protocol (ARP).- See Also:
-
PID_FLEXNET
public static final byte PID_FLEXNETProtocol ID for FlexNet.- See Also:
-
PID_NETROM
public static final byte PID_NETROMProtocol ID for NET/ROM.- See Also:
-
PID_NOLVL3
public static final byte PID_NOLVL3Protocol ID for no level 3 protocol (also used for APRS).- See Also:
-
PID_ESCAPE
public static final byte PID_ESCAPEProtocol ID for escape code indicating second byte of PID (not supported).- See Also:
-
PTYPES_S
Hashmap of Information (I) or Unnumbered Information (UI) frame protocol ID to protocol name strings.- See Also:
-
-
Constructor Details
-
AX25Frame
public AX25Frame()Create an empty AX25Frame initialized for a UI frame containing an APRS packet.
-
-
Method Details
-
decodeFrame
Create a AX25Frame from a byte array presumed to contain an AX.25 protocol sequence.- Parameters:
buf
- byte array to read frame fromoffset
- zero-based index into the array where the frame startslength
- number of bytes making up the frame- Returns:
- structured AX25Frame object, or null if byte array doesn't have enough bytes for a frame
-
initializeCmd
Properly set the isCmd flag of a frame based on theAX25Callsign.h_c
bits in the sender and destination addresses.- Parameters:
f
- AX25Frame to set
-
getFrameTypeString
Generate a string describing the type of the frame.- Returns:
- descriptive String
-
getFrameType
public int getFrameType()Get the type of this frame, as stored in the ctl byte.- Returns:
- frame type code
- See Also:
-
getNS
public int getNS()Get the transmission sequence number.- Returns:
- sequence number
- Throws:
IllegalStateException
- if this is not an I frame
-
getNR
public int getNR()Get the reception sequence number.- Returns:
- sequence number
- Throws:
IllegalStateException
- if this is not an I frame
-
getSType
public int getSType()Get the Supervisory frame subtype.- Returns:
- S frame subtype (masked but not bit-shifted from its position in ctl bitmask)
- See Also:
-
findSTypeByName
Given a string name, get the numeric S-type value for that type of AX.25 frame.- Parameters:
sTypeName
- String name of frame type- Returns:
- S-type numeric value, or -1 if no match found
-
getP
public boolean getP()Get poll bit.- Returns:
- boolean state of poll bit
-
findUTypeByName
Given a string name, get the numeric U-type value for that type of AX.25 frame.- Parameters:
uTypeName
- String name of frame type- Returns:
- U-type numeric value, or -1 if no match found
-
getUType
public int getUType()Get Unordered frame subtype.- Returns:
- U frame subtype (masked but not bit-shifted from its position in ctl bitmask)
- See Also:
-
write
Transmit this AX25Frame to an output byte stream.- Parameters:
os
- OutputStream to write the frame to- Throws:
IOException
- if writing fails
-
dup
Create a deep copy of this frame.- Returns:
- duplicate AX25Frame instance
-
dupOnlyHeader
Create a deep copy of this frame, excluding the body. This is useful for digipeating messages received from APRS-IS, because it skips making a copy of the message body that will immediately be discarded as part of the 3rd-party re-packaging.- Returns:
- almost-duplicate AX25Frame instance
-
getFrames
public AX25Frame[] getFrames(boolean incrementXmtCount, ProtocolFamily protocolId, String senderCallsign) Get the frames associated with this FrameSource (in this case, itself).- Specified by:
getFrames
in interfaceAX25FrameSource
- Parameters:
incrementXmtCount
- indicate whether the transmit counter (used to cycle through proportional pathing) should be incrementedprotocolId
- indicate the protocol to generate this frame for (not relevant for digipeated frames)senderCallsign
- local sending callsign (ignored if frame already has the callsign filled in)- Returns:
- one-element array point at this frame
-
getNumTransmitsBeforeDecay
public int getNumTransmitsBeforeDecay()Get number of times frame will be retransmitted before inter-packet delay is increased.- Specified by:
getNumTransmitsBeforeDecay
in interfaceAX25FrameSource
- Returns:
- transmission count before interval increase
-
getConnector
Specify the Connector this message should be transmitted through.- Specified by:
getConnector
in interfaceAX25FrameSource
- Returns:
- a specific Connector instance to transmit through, or null for all applicable ports (Connector.CAP_XMT_PACKET_DATA and not rejecting this specific packet [such as IGateConnectors shouldn't re-transmit something received from the IGate])
- See Also:
-
isRealCallsign
Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase). Note this will automatically strip off the SSID (if any) before testing. Note this is safe for empty strings, and will properly report them as not being a valid real-station callsign,- Parameters:
callsign
- String callsign to test- Returns:
- boolean true if callsign looks like real
-
getFirstDigi
Get the first actual digipeated digipeater station callsign in the digipeater sequence.- Parameters:
digipeaters
- array of AX25Callsigns for digipeating a message- Returns:
- String of first real callsign in sequence, or empty String if no actual digipeater callsign
-
getNthDigi
Get the Nth digipeated digipeater station callsign in the digipeater sequence.- Parameters:
digipeaters
- array of AX25Callsigns for digipeating a messageindex
- zero-based index of digipeater to report- Returns:
- String of callsign in sequence, or null if run out of repeated aliases
-
getLastDigi
Find the last callsign through which a frame has been digipeated.- Parameters:
digipeaters
- array of digipeater callsigns- Returns:
- String callsign of last digipeater entry that is marked as used, or empty String if none used
-
isRf
Test if this AX25Frame came from an RF connection.- Parameters:
maxDigis
- int maximum number of digipeat hops before we're not going to count it- Returns:
- Boolean.TRUE if a local Rf transmission, Boolean.FALSE if not RF-only, null if we can't tell
-
isDirect
public boolean isDirect()Test if this message was sent directly (without any relay station).- Returns:
- boolean true if direct, false if not
-
setCmd
public void setCmd(boolean isCmd) Set the command bits in the sender and destination fields.- Parameters:
isCmd
- boolean true if this is a command frame, false if a response
-
toString
Return a String representing this AX25Frame object. -
getAsciiFrame
Produce an ASCIIfied version of frame body.- Returns:
- String version of frame body
-
getChecksum
public int getChecksum()Compute a checksum for this frame to allow efficiently identifying duplicate frames. The checksum only covers the sender callsign and the body, as its purpose is to prevent duplicate digipeating. Alas, it won't work with duplicate transmit IGates, since they change the the sending callsign to that of the IGate and inject a third-party header into the body.- Returns:
- int checksum of the current contents of this AX25Frame object
-
compareTo
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.- Specified by:
compareTo
in interfaceComparable<AX25Frame>
- Parameters:
o
- the object to be compared.- Returns:
- a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
- Throws:
ClassCastException
- if the specified object's type prevents it from being compared to this object.
-
equals
Indicates whether some other object is "equal to" this one. -
hashCode
public int hashCode()Returns a hash code value for the object. -
isDuplicate
Test if this frame has the same contents (at least as regards duplicate checking) as the provided older frame.- Parameters:
other
- AX25Frame to compare payloads with- Returns:
- boolean true if this frame should be treated as a duplicate for digipeating purposes
-
getEstimatedBitCount
public int getEstimatedBitCount()Estimate the number of bits needed to transmit this frame over RF in AX.25 standard physical layer (HDLC).- Returns:
- bit count estimate
-
isValid
public boolean isValid()Report whether this packet is strictly valid according to the AX.25 protocol specification,- Returns:
- boolean true if packet is valid
-
getProtocols
Get the protocol family or families that this message corresponds to, so ports that don't support all protocols will not forward inappropriate packets.- Returns:
- array of supported ProtocolFamily enums
-