pe

Packet Engine Client

Client implementation for Packet Engine, providing a simple means of calling an engine running on a TCP/IP port. This module provides the low-level (i.e. close to the protocol) implementation. Other modules in this package provide higher level abstractions.

Protocol reference:: https://www.on7lds.net/42/sites/default/files/AGWPEAPI.HTM

Submodules

Classes

`ReceiveHandler`	A no-op base class for receive handlers.
`PortCaps`	Capabilities for a single port, as retrieved from the Packet Engine.
`HeardCall`	Record of a callsign heard on a port.
`PacketEngine`	The Packet Engine client.

Package Contents

class pe.ReceiveHandler

A no-op base class for receive handlers.

Use of this base class is not required, but since this class provides an empty implementation for each frame type, using it is convenient when not all frame types will be supported.

version_info(major, minor)

Called with the major and minor version as returned from the server.

Corresponding frame type: ‘R’

Parameters:

major (int) – Major version.
minor (int) – Minor version.

callsign_registered(callsign, success)

Called with the results of an attempt to register a callsign with the server.

Corresponding frame type: ‘X’

Parameters:

callsign (str) – Callsign being registered.
success (bool) – True if registration was successful; False otherwise.

port_info(info)

Called with the results of a request for information on available ports.

Each returned port is a string of the form “<number>;<desc>”, being the port number and its description, separated by a semicolon.

Corresponding frame type: ‘G’

Parameters:: info (list[str]) – List of available ports.

port_caps(port, caps)

Called with the results of a request for the capabilities of a specific port.

Corresponding frame type: ‘g’

Parameters:

port (int) – Port for which capabilities are provided.
caps (PortCaps) – A PortCaps instance for this port.

callsign_heard_on_port(port, heard_call)

Called with the results of a request for a list of callsigns heard on a specified port. This method may be called multiple times for a single request, once for each callsign heard on the port.

Corresponding frame type: ‘H’

Parameters:

port (int) – Port for which records were requested.
heard_call (HeardCall) – Record of one callsign heard as returned from the server.

frames_waiting_on_port(port, frames)

Called with the results of a request for the number of frames outstanding on a specified port.

Corresponding frame type: ‘y’

Parameters:

port (int) – Port for which count is provided.
frames (int) – The number of outstanding frames for this port.

connection_received(port, call_from, call_to, incoming, message)

Called with information about a new connection, whether outgoing (i.e. initiated by the client) or incoming (i.e. initiated by a remote node).

Corresponding frame type: ‘C’

Parameters:

port (int) – Port on which connection has been received.
call_from (str) – Callsign of station initiating the connection.
call_to (str) – Callsign of station receiving the connection.
incoming (bool) – True if the connection was initiated by a remote node; False if it was initiated by the client.
message (str) – Connection message. This will start with “*** CONNECTED To” for an incoming message, or “*** CONNECTED With” for an outgoing connection.

connected_data(port, call_from, call_to, pid, data)

Called with incoming data from on ongoing connection.

Corresponding frame type: ‘D’

Parameters:

port (int) – Port for ongoing connection.
call_from (str) – Callsign of station sending the data.
call_to (str) – Callsign of station receiving the data.
pid (int) – The PID corresponding to the incoming data.
data (bytearray) – The incoming data.

disconnected(port, call_from, call_to, message)

Called when an ongoing connection is disconnected, whether by the client, the remote node, or a timeout.

Corresponding frame type: ‘d’

Parameters:

port (int) – Port for ended connection.
call_from (str) – Callsign of station that initiated the connection.
call_to (str) – Callsign of station receiving the connection.
message (str) – Disconnection message. In the case of a timeout, this may include the string “RETRYOUT”.

frames_waiting_on_connection(port, call_from, call_to, frames)

Called with the results of a request for the number of frames outstanding on a specified connection.

Corresponding frame type: ‘Y’

Parameters:

port (int) – Port for ongoing connection.
call_from (str) – Callsign of station initiating the connection.
call_to (str) – Callsign of station receiving the connection.
frames (int) – The number of outstanding frames for this connection.

monitored_connected(port, call_from, call_to, text, data)

Called when an AX.25 Information (I) frame is received, if monitoring is enabled.

Corresponding frame type: ‘I’

Parameters:

port (int) – Port on which frame was received.
call_from (str) – Callsign of sending station.
call_to (str) – Callsign of destination station.
text (str) – Textual representation of frame, in AGWPE format.
data (bytearray) – Data associated with the frame.

monitored_supervisory(port, call_from, call_to, text)

Called when an AX.25 Supervisory (S) frame is received, if monitoring is enabled.

Corresponding frame type: ‘S’

Parameters:

port (int) – Port on which frame was received.
call_from (str) – Callsign of sending station.
call_to (str) – Callsign of destination station.
text (str) – Textual representation of frame, in AGWPE format.

monitored_unproto(port, call_from, call_to, text, data)

Called when an AX.25 Unproto (U) frame is received, if monitoring is enabled.

Corresponding frame type: ‘U’

Parameters:

port (int) – Port on which frame was received.
call_from (str) – Callsign of sending station.
call_to (str) – Callsign of destination station.
text (str) – Textual representation of frame, in AGWPE format.
data (bytearray) – Data associated with the frame.

monitored_own(port, call_from, call_to, text, data)

Called when an AX.25 Unproto (U) frame has been sent by the client, if monitoring is enabled, allowing for confirmation of sent frames.

Corresponding frame type: ‘T’

Parameters:

port (int) – Port on which frame was sent.
call_from (str) – Callsign of sending station.
call_to (str) – Callsign of destination station.
text (str) – Textual representation of frame, in AGWPE format.
data (bytearray) – Data associated with the frame.

monitored_raw(port, data)

Called for all monitored frames when monitoring in raw format has been enabled.

Corresponding frame type: ‘K’

Parameters:

port (int) – Port on which frame was received.
data (bytearray) – Raw AX.25 frame data.

class pe.PortCaps

Bases: NamedTuple

Capabilities for a single port, as retrieved from the Packet Engine.

This is a readonly structure.

baud_rate: int: baud rate

traffic_level: int: traffic level if port is in autoupdate mode

tx_delay: int: TX delay

tx_tail: int: TX tail

persist: int: persistence

slot_time: int: slot time

max_frame: int: maximum frames

active_connections: int: number of active connections

bytes_received: int: number of bytes received in last 2 minutes

classmethod unpack(buffer)

Unpack the encoded byte sequence into a new PortCaps instance.

Parameters:: buffer (bytes or bytearray) – Encoded byte sequence.
Returns:: A new PortCaps instance.
Return type:: PortCaps
Raises:: ValueError – if the length of the provided data is invalid.

class pe.HeardCall

Bases: NamedTuple

Record of a callsign heard on a port.

This is a readonly structure.

callsign: str: callsign heard

first_heard: str: when first heard, as a string

first_heard_ts: datetime.datetime: when first heard, as a datetime instance

last_heard: str: when last heard, as a string

last_heard_ts: datetime.datetime: when last heard, as a datetime instance

classmethod unpack(buffer)

Unpack the encoded byte sequence into a new HeardCall instance. Note that the datetime values may be None if those fields were not present in the data.

Parameters:: buffer (bytes or bytearray) – Encoded byte sequence.
Returns:: A new HeardCall instance.
Return type:: HeardCall

class pe.PacketEngine(handler=None)

The Packet Engine client.

Create an instance of this class to communicate with the Packet Engine server. A receive handler may be passed in as the engine is constructed, or later using the receive_handler property, but must be set before connecting to the server.

property receive_handler

Retrieve or set the current receive handler.

Type:: ReceiveHandler

connect_to_server(host=DEF_HOST, port=DEF_PORT)

Connect to the Packet Engine server. After setting a receive handler, call this before any other methods on this class.

Note that the engine is not yet ready when this method returns; the caller should listen for the ‘pe_engine_ready’ signal to determine when the client is ready for use.

Exceptions raised by a failed attempt to connect to the server are not translated, and are allowed to propagate to the client, hence the exceptions documented here.

Parameters:

host (str) – Name of host to connect to.
port (int) – Number of port to connect to.

Raises:

socket.gaierror – if the server name cannot be resolved. The most common cause is an incorrect host name.
ConnectionRefusedError – if the server refuses the attempt to connect. The most common cause is an incorrect port number.

disconnect_from_server(): Disconnect from the Packet Engine server. Do not call other methods on this class after this call, except to (re)connect to a server.

property connected_to_server

Determine whether or not the client is connected to the server.

Readonly.

Returns:: True if connected to the server; False otherwise.
Return type:: bool

register_callsign(callsign)

Register a callsign for use with the server. Must be called before the callsign is used to initiate a connection. Registration is not complete until the corresponding response is received from the server.

Corresponding frame type: ‘X’

Parameters:: callsign (str) – Callsign to register

unregister_callsign(callsign)

Unregister a callsign, such that it can no longer be used to initiate a connection. Unregistration is complete when this method returns.

Corresponding frame type: ‘x’

Parameters:: callsign (str) – Callsign to unregister

is_callsign_registered(callsign)

Determine whether or not the specified callsign has already been registered.

Parameters:: callsign (str) – Callsign to be checked.
Returns:: True if the callsign has been registed; False otherwise.
Return type:: bool

ask_port_info()

Request information on available ports from the server. Port information is not returned from this method but via the port_info() method of the current receive handler, and is cached for later use.

Corresponding frame type: ‘G’

get_cached_port_info()

Retrieve the currently cached port information.

Returns:: List of available ports.
Return type:: list[str]

enable_monitoring(onoff)

Enable or disable monitoring, per the argument. This is a no-op if the status of monitoring would not change.

Corresponding frame type: ‘m’

Parameters:: onoff (bool) – Set to True to enable monitoring; set to False to disable it.

property monitoring

Query or set the current state of monitoring. Setting this property is

equivalent to calling `enable_monitoring()`.

Type:: bool

ask_version()

Request version information from the server. The information is not returned from this method but via the version_info()` method of the current receive handler, and is cached for later use.

Corresponding frame type: ‘R’

property version_info

Retrieve the currently cached version information. Readonly.

Returns:: Major and minor version information.
Return type:: tuple(int, int)

enable_raw_ax25(onoff)

Enable or disable reception of frames in raw AX.25 format. When enabled, raw frames will be provided via the monitored_raw() method of the current receive handler. This method is a no-op if the status of raw frame reception would not change.

Corresponding frame type: ‘k’

Parameters:: onoff (bool) – Set to True to enable raw frames; set to False to disable them.

property raw_ax25

Query or set the current state of raw frame reception. Setting this

property is equivalent to calling `enable_raw_ax25()`.

Type:: bool

ask_port_caps(port)

Request capabilities for the specified port. Capabilities are not returned from this method but via the port_caps() method of the current receive handler, and are cached for later use.

Corresponding frame type: ‘g’

Parameters:: port (int) – Port for which capabilities are to be retrieved.

get_cached_port_caps(port)

Retrieve the currently cached port capabilities for the specified port.

Parameters:: port (int) – Port for which capabilities are to be retrieved.
Returns:: Capabilities for the specified port.
Return type:: PortCaps

send_unproto(port, call_from, call_to, data, via=None)

Send an unproto (UI) message to the specified port. The message may be specified either as a string or as a byte sequence. To send to a destination via one or more intermediaries, specify a list of those intermediaries.

Corresponding frame type: ‘M’ or ‘V’

Parameters:

port (int) – Port to which the unproto message is to be sent.
call_from (str) – Callsign of sender.
call_to (str) – Callsign of destination.
data (str or bytes or bytearray) – The message to be sent.
via (list(str) or None) – List of intermediary destinations. Optional.

Raises:

ValueError – if the data is of an invalid type.

connect(port, call_from, call_to, via=None, pid=None)

Initiate an AX.25 connected session between the source and destination stations. To send to a destination via one or more intermediaries, specify a list of those intermediaries. Confirmation of the connection is via the connection_received() method of the current receive handler.

Corresponding frame type: ‘C’, ‘c’ or ‘v’

Parameters:

port (int) – Port on which the connection is to be made.
call_from (str) – Callsign of source station.
call_to (str) – Callsign of destination station.
via (list(str) or None) – List of intermediary destinations. Optional.
pid (int) – The PID to use for data on this connection. Optional.

Raises:

ValueError – if the source callsign has not been registered, or if an invalid PID value is specified.

send_data(port, call_from, call_to, data, pid=None)

Send data over an open connection. The connection must have been previously opened with the connect() method.

Corresponding frame type: ‘D’

Parameters:

port (int) – Port on which the data is to be sent.
call_from (str) – Callsign of source station.
call_to (str) – Callsign of destination station.
data (str or bytes or bytearray) – The data to be sent.
pid (int) – The PID to use for data.

Raises:

ValueError – if the source callsign has not been registered, or if an invalid PID value is specified.

disconnect(port, call_from, call_to)

Close a connection previously opened with the connect() method. Confirmation of closing the connection is via the disconnected() method of the current receive handler.

Corresponding frame type: ‘d’

Parameters:

port (int) – Port on which the connection was opened.
call_from (str) – Callsign of source station.
call_to (str) – Callsign of destination station.

Raises:

ValueError – if the source callsign has not been registered.

send_raw(port, call_from, call_to, data)

Send a raw AX.25 frame to the specified port.

Corresponding frame type: ‘K’

Parameters:

port (int) – Port to which the AX.25 frame is to be sent.
call_from (str) – Callsign of sender.
call_to (str) – Callsign of destination.
data (bytes or bytearray) – The AX.25 frame to be sent.

ask_callsigns_heard_on_port(port)

Request a list of recently heard stations on the specified port.

Corresponding frame type: ‘H’

Parameters:: port (int) – Port to query for heard callsigns.

ask_frames_waiting_on_port(port)

Request the number of outstanding frames waiting for transmission on the specified port.

Corresponding frame type: ‘y’

Parameters:: port (int) – Port to query for outstanding frames.

ask_frames_waiting_on_connection(port, call_from, call_to)

Request the number of outstanding frames waiting for transmission on the connection between the specified callsigns on the specified port.

Corresponding frame type: ‘Y’

Parameters:

port (int) – Port on which the connection was opened.
call_from (str) – Callsign of source station.
call_to (str) – Callsign of destination station.

login(userid, password)

Send the user id and password to the server for authentication. There is no response from the server corresponding to this request, so no indication is available of the success or failure of authentication.

For both fields, if a string is specified, it is assumed to be UTF-8 and encoded accordingly. If this is not desirable, then a byte sequence should be specified instead.

Direwolf silently ignores this call.
ldsped accepts userid / password strings, validates them against a config file, and does not honor future requests if that fails.
AGWPE validates the input with Windows authentication.

Corresponding frame type: ‘P’

Parameters:

userid (str or bytes) – Id of user to validate.
password – Password of user to validate.