ax253

ax253 (pronounced “Ay-Ex-twenty-five-three”) is a python implementation of the ax25 protocol used in Amateur Radio applications.

This library provides the essential building blocks that other applications can use to encode and decode frames and addresses in ax25 format (common for KISS TNCs) or TNC2 (APRS-IS format, for UI frames only).

API

class ax253.address.Address(callsign, ssid=0, digi=False, a7_hldc=False)

A source, destination, or path entry in an AX.25 frame.

callsign: bytes

The callsign associated with the address.

digi: bool

If true, indicates that this address has digipeated the packet.

evolve(**kwargs) → Address

Create a new Address by applying kwargs to this Address.

classmethod from_any(address: Union[Address, bytes, str], **kwargs: Any) → Address

Create an address from any supported value.

classmethod from_bytes(ax25_address: bytes, **kwargs: Any) → Address

Create an address from ax25 bytes.

classmethod from_str(address_spec: str, a7_hldc: bool = False, **kwargs: Any) → Address

Create an address from a string (TNC2 format).

ssid: int

The ssid (0-15) extension of the callsign.

class ax253.frame.Frame(destination: Address, source: Address, path: Sequence[Address], control: Any = Control(v=b'\x03'), pid=b'\xf0', info=b'')

An AX.25 Frame.

classmethod from_bytes(ax25_bytes: bytes) → Frame

Decode the frame from AX.25 bytes.

classmethod from_str(ax25_text: str) → Frame

Decode the frame from TNC2 monitor format.

classmethod ui(destination: Union[Address, str], source: Union[Address, str], path: Optional[Sequence[Union[Address, str]]] = None, info: bytes = b'')

Create a UI frame with the given information.

class ax253.frame.Control(v)

The Frame control byte, indicates FrameType and PID

property ftype: FrameType

The FrameType associated with this Control byte.

class ax253.frame.FrameType(value)

Determines the type of the packet based on the control field.

Decoders

class ax253.decode.GenericDecoder

Generic stateful decoder.

static decode_frames(frame: bytes) → Iterable[_T]

Decode a single deframed byte chunk.

Parameters

frame – should represent a single higher level frame to decode in some way.

flush() → Iterable[_T]

Call when the stream is closing to decode any final buffered bytes.

update(new_data: bytes) → Iterable[_T]

Decode the next sequence of bytes from the stream.

Parameters

new_data – the next bytes from the stream

Returns

an iterable of decoded frames

class ax253.decode.FrameDecodeProtocol(transport: Optional[Transport] = None, decoder: GenericDecoder[_T] = NOTHING)

Protocol which uses a GenericDecoder to split the stream into frames.

connection_lost(exc: Exception) → None

asyncio callback when connection is lost.

connection_made(transport: Transport) → None

asyncio callback when connection is established.

Because this protocol exposes higher-level read/write operations that require the transport, an awaitable connection_future is completed for consumers who depend on an active connection.

data_received(data: bytes) → None

Pass data off to decoder instance and put frames on the queue.

frame_decoded(frame: _T) → None

Subclasses may override this function to handle new frame.

async read(n_frames: Optional[int] = None, callback: Optional[Callable[[_T], None]] = None) → AsyncIterable[_T]

Iterate through decoded frames.

If n_frames is specified, exit after yielding that number of frames.

read_frames(n_frames: Optional[int] = - 1, callback: Optional[Callable[[_T], None]] = None, loop: Optional[BaseEventLoop] = None) → Sequence[_T]

Blocking read of the given number of frames.

write(frame: SupportsBytes) → None

Write serialized frame to the underlying transport.

Parameters

frame – Frame to write.

class ax253.decode.SyncFrameDecode(protocol: Optional[FrameDecodeProtocol[_T]] = None)

Synchronous wrapper over FrameDecodeProtocol.

It is recommended to use this class as a contextmanager for automatic start/stop functionality.

property loop: BaseEventLoop

Get a reference to a shared event loop for this class.

read(callback: Optional[Callable[[_T], None]] = None, min_frames: Optional[int] = - 1) → Sequence[_T]

Read frames from underlying protocol.

Parameters

  • callback – optional function is called after each frame is decoded. The callback will be fired for already-decoded frames immediately, and then for any frames that are decoded while blocked.

  • min_frames – block until this minimum number of frames are available. if -1 (default), return all buffered frames without blocking if None, read until EOF is seen (device closed)

Returns

List of frames

abstract start(**kwargs: Any) → None

Method is responsible for establishing the connection and assigning self.protocol.

If self.protocol isn’t assigned, the SyncFrameDecode is considered closed.

abstract stop() → None

Method is responsible for closing the transport.

write(frame: SupportsBytes) → None

Writes frame to KISS interface.

Parameters

frame – Frame to write.

class ax253.frame.AX25BytestreamDecoder

Decode a generic AX25_FLAG delimited bytestream

static decode_frames(frame: bytes) → Iterable[Frame]

Decode a single deframed byte chunk.

Parameters

frame – should represent a single higher level frame to decode in some way.

flush() → Iterable[Frame]

Call when the stream is closing to decode any final buffered bytes.

update(new_data: bytes) → Iterable[Frame]

Decode the next sequence of bytes from the stream.

Parameters

new_data – the next bytes from the stream

Returns

an iterable of decoded frames

class ax253.tnc2.TNC2Decode

Decode packets in CR-LF delimited TNC2 monitor format.

Example: SENDER>DEST,PATH:data for the packet

static decode_frames(frame: bytes) → Iterable[Frame]

Decode a single deframed byte chunk.

Parameters

frame – should represent a single higher level frame to decode in some way.

update(new_data: bytes) → Iterable[Frame]

Decode the next sequence of bytes from the stream.

Parameters

new_data – the next bytes from the stream

Returns

an iterable of decoded frames

class ax253.tnc2.TNC2Protocol(transport: Optional[Transport] = None, decoder: TNC2Decode = NOTHING)

Protocol for decoding a stream of TNC2 format packets.

write(frame: Frame) → None

Write the Frame to the transport.

Utility

class ax253.fcs.FCS(fcs: int = 65535)

Indices and tables