ax25

AX.25 Frame Structure

Structure definitions together with methods to pack and unpack native AX.25 frames and the constituent parts of those frames. This can be used together with a communication protocol such as AGWPE, KISS, or a native AX.25 stack for applications across the gamut, from simple ‘listen’ monitoring to full connected mode systems.

Protocol reference:: http://www.tapr.org/pdf/AX25.2.2.pdf

Submodules

Classes

`FrameType`	The type of an AX.25 frame, as identified within the control field.
`Address`	A single element (subfield) of the address field for an AX.25 frame.
`Control`	The control field for an AX.25 frame.
`Frame`	A complete AX.25 frame, excluding the flag and FCS fields.

Package Contents

class ax25.FrameType(*args, **kwds)

Bases: enum.Enum

The type of an AX.25 frame, as identified within the control field.

The values match those defined in the AX.25 spec, with an additional value to identify an as yet unknown frame. General types are also defined, to allow for categorization of I, S and U frames, along with methods to determine whether a value matches a specific category.

RR = 1: Receive Ready

RNR = 5: Receive Not Ready

REJ = 9: Reject

SREJ = 13: Selective Reject

UI = 3: Unnumbered Information

DM = 15: Disconnect Mode

SABM = 47: Set Async Balanced Mode

DISC = 67: Disconnect

UA = 99: Unnumbered Acknowledge

SABME = 111: Set Async Balanced Mode

FRMR = 135: Frame Reject

XID = 175: Exchange Identification

TEST = 227: Test

UNK = 255: Unknown frame type

I = 0: I Frame

S = 1: S Frame

U = 3: U Frame

is_I(): Is this an I frame type?

is_S(): Is this an S frame type?

is_U(): Is this an U frame type?

class ax25.Address(call, ssid=0, repeater=False)

A single element (subfield) of the address field for an AX.25 frame.

In addition to the callsign and SSID, this includes fields corresponding to has-been-repeated and command/response state.

Parameters:

call (str) – Callsign, with or without an SSID. If an SSID is included in this string, the ssid argument must not be used. If the callsign ends with an asterisk, the address is marked as having been repeated.
ssid (int) – SSID, in the range 0..15.
repeater (bool) – Indicates whether or not this instance represents a repeater address. This is used to determine whether this instance has a command/response bit or a has-been-repeated bit.

Raises:

TypeError – if the repeater argument is False but the callsign ends with an asterisk.
ValueError – if the callsign or SSID is invalid, or if the callsign includes an SSID value that conflicts with the ssid argument.

static valid_call(call, base_only=False)

Check a callsign to determine its validity.

The following checks are performed:

Base callsign is of a valid length, and is alphanumeric.

Zero or one callsign/SSID separators are present.

SSID, if present, is numeric and within the valid range.

Parameters:

call (str) – The callsign to be validated.
base_only (bool) – If True, the callsign will be validated as one without an SSID, such that a callsign with an SSID will be considered invalid; if False, an SSID may be present.

Returns:

True if the callsign is valid; False otherwise.

Return type:

bool

property call

Retrieve the callsign (only) for this address. Readonly.

Returns:: The callsign, without SSID.
Return type:: str

property ssid

Retrieve the SSID for this address. Readonly.

Returns:: The SSID.
Return type:: int

property repeater

Determine whether or not this is a repeater address. Readonly.

Returns:: True if this is a repeater address; False otherwise.
Return type:: bool

property has_been_repeated

Determine whether or not this repeater address has been repeated.

The getter returns True if this address has been repeated; False otherwise.

The setter takes a bool value, and raises TypeError if an attempt is made to set this property for a non-repeater address.

property command_response

Determine whether or not the command/response bit is set for this non-repeater address.

The getter returns True if the command/response bit is set; False otherwise.

The setter takes a bool value, and raises TypeError if an attempt is made to set this property for a repeater address.

pack()

Pack this Address instance into an encoded byte sequence.

Returns:: Encoded byte sequence for this Address.
Return type:: bytes

classmethod unpack(buffer, repeater=False)

Unpack the encoded byte sequence into a new Address instance.

The repeater argument specifies whether the byte sequence represents a repeater or non-repeater address.

Parameters:

buffer (bytes or bytearray) – Encoded byte sequence.
repeater (bool) – Whether or not this address represents a repeater address.

Returns:

A new Address instance.

Return type:

Address

Raises:

ValueError – if the encoded information results in an invalid callsign.

class ax25.Control(frame_type, poll_final=False, recv_seqno=0, send_seqno=0)

The control field for an AX.25 frame.

This includes the frame type, the poll/final indicator, and the send and receive sequence numbers. At this time, only modulo 8 (single octet) control fields are supported.

Parameters:

frame_type (FrameType) – Type of the associated Frame.
poll_final (bool) – State of the poll/final indicator.
recv_seqno (int) – Receive sequence number.
send_seqno (int) – Send sequence number.

property frame_type

Retrieve the type of the associated frame. Readonly.

Returns:: Type of the frame.
Return type:: FrameType

property poll_final

Determine whether or not the poll/final bit is set.

The getter returns True if the poll/final bit is set; False otherwise.

The setter takes a bool value to set or unset the poll/final bit.

property recv_seqno

Retrieve or set the receive sequence number.

The receive sequence number is an int, and is valid only on I and S frames; a TypeError is raised if an attempt is made to retrieve or set this value on a U frame.

property send_seqno

Retrieve or set the send sequence number.

The send sequence number is an int, and is valid only on I frames; a TypeError is raised if an attempt is made to retrieve or set this value on an S or U frame.

pack()

Pack this Control instance into an encoded value.

Returns:: Encoded value for this Control.
Return type:: int
Raises:: ValueError – if the frame type is not set (i.e. it is FrameType.UNK).

classmethod unpack(control)

Unpack the encoded value into a new Control instance.

Values for the poll/final bit and receive and send sequence numbers are determined based upon the frame type.

Parameters:: control (int) – Encoded value.
Returns:: A new Control instance.
Return type:: Control
Raises:: ValueError – if the frame type is invalid.

class ax25.Frame(dst, src, via=None, control=None, pid=0, data=None)

A complete AX.25 frame, excluding the flag and FCS fields.

This includes the address field and control field, and the protocol identifier and information field where present.

Parameters:

dst (Address or str) – Destination address. Required.
src (Address or str) – Source address. Required.
via (list[Address or str] or None) – List of Via addresses. Optional.
control (Control) – Control field. Required.
pid (int) – Protocol Identifier. Valid only for I and UI frames.
data (bytes or bytearray or None) – Data for information field. Valid only for I, UI, FRMR, XID and TEST frames.

Raises:

TypeError – if any provided field has an invalid type.
ValueError – if data is provided for an invalid frame type, or if the data field is too long.

property dst

Retrieve the destination address for this frame. Readonly.

Returns:: Destination address.
Return type:: Address

property src

Retrieve the source address for this frame. Readonly.

Returns:: Source address.
Return type:: Address

property via

Retrieve the list of Via addresses for this frame. Readonly.

Returns:: List of Via addresses.
Return type:: list[Address] or None

property control

Retrieve the control field for this frame. Readonly.

Returns:: Control field.
Return type:: int

property pid

Retrieve the Protocol Identifier for this frame. Readonly.

Returns:: Protocol identifier, or 0 if PID is not permitted for this frame type.
Return type:: int

property data

Retrieve the information field for this frame. Readonly.

Returns:: Information field data, or None if the information field is not permitted for this frame type.
Return type:: bytes or None

pack()

Pack this Frame instance into an encoded byte sequence.

Returns:: Encoded byte sequence for this Frame.
Return type:: bytes

classmethod unpack(buffer)

Unpack the encoded byte sequence into a new Frame instance.

Parameters:: buffer (bytes or bytearray) – Encoded byte sequence.
Returns:: A new Frame instance.
Return type:: Frame
Raises:: ValueError – if any encoded address results in an invalid callsign.