pe.connect

Packet Engine Connection Handling

Connection handling layer that sits on top of the Packet Engine Client and provides a simplified connection-oriented interface, avoiding the need for direct interaction with the packet engine interface.

To use this layer, the following steps are required:

  • Define a subclass of the Connection base class that will handle interactions with a connection.

  • Create an instance of the Connections class that will manage all of the connections for the specified Packet Engine instance.

  • Obtain the request handler from the Connections instance and add it to the chain of request handlers for your engine instance.

  • Use the open() function of your Connections instance to create new connected-mode connections.

Exceptions

ConnectionClassNotFoundError

Raised when an attempt is made to open a connection but no subclass of

ConnectionError

Raised when a connection attempt fails or a connection is terminated

Classes

ConnectionState

The current state of a connection.

Connection

An AX.25 connected session between two stations.

Connections

Focal point for all connected-mode connections.

Module Contents

exception pe.connect.ConnectionClassNotFoundError

Bases: Exception

Raised when an attempt is made to open a connection but no subclass of Connection has been defined.

exception pe.connect.ConnectionError

Bases: Exception

Raised when a connection attempt fails or a connection is terminated unexpectedly.

class pe.connect.ConnectionState(*args, **kwds)

Bases: enum.Enum

The current state of a connection.

This is updated as the state progresses, from initiation through connection to completion.

CONNECTING

Attempting to connect

CONNECTED

Successfully connected

DISCONNECTING

Attempting to disconnect

DISCONNECTED

Not yet, or no longer, connected

TIMEDOUT

Connection attempt timed out

class pe.connect.Connection(port, call_from, call_to, incoming=False)

An AX.25 connected session between two stations.

This may be a connection initiated by the client, or an incoming connection from a remote station.

This is a base class that is intended to be subclassed so that action may be taken on events such as connection status changes or receipt of incoming data.

Parameters:

  • port (int) – Port on which the connection is established.

  • 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 the remote station; False otherwise.

property port
Port on which the connection was established. Readonly.
Returns:

Port for this connection.

Return type:

int

property call_from
Callsign of station initiating the connection. Readonly.
Returns:

Callsign of initiating station.

Return type:

str

property call_to
Callsign of station receiving the connection. Readonly.
Returns:

Callsign of receiving station.

Return type:

str

property incoming
Whether or not the connection is incoming, i.e. initiated by a remote
station. Readonly.
Returns:

True if the connection was initiated by the remote station; False otherwise.

Return type:

bool

property state
Current state of the connection. Readonly.
Returns:

Connection state.

Return type:

ConnectionState

classmethod query_accept(port, call_from, call_to)

Determine whether or not an incoming connection on the specified port, from the specified source and to the specified destination, should be accepted.

The default implementation always returns False, but this method may be overridden in a subclass in order to control which incoming connections are accepted.

Parameters:

  • port (int) – Port for incoming connection.

  • call_from (str) – Callsign of station initiating the connection.

  • call_to (str) – Callsign of station receiving the connection.

Returns:

True if the connection should be accepted; False otherwise.

Return type:

bool

send_data(data)

Send data on the currently open connection.

Parameters:

data (bytes or bytearray) – Data to be sent.

close()

Close the currently open connection.

connected()

Called when a connection has been successfully opened. This method should be implemented by a subclass in order to detect connection initiation and act on it appropriately.

disconnected()

Called when a connection has been closed. This method should be implemented by a subclass in order to detect connection completion and act on it appropriately.

data_received(pid, data)

Called when data has been received on an open connection. This method should be implemented by a subclass in order to receive and process incoming data.

Parameters:

  • pid (int) – The PID corresponding to the incoming data.

  • data (bytearray) – The incoming data.

class pe.connect.Connections(engine)

Focal point for all connected-mode connections.

Create an instance of this class to work with connected sessions for the provided packet engine instance. The corresponding request handler must be added to the engine’s request handler chain. An instance of your defined Connection subclass will be created for each connection.

Parameters:

engine (PacketEngine) – Packet engine client instance.

property receive_handler
Retrieve the receive handler that will be used to create and invoke
methods on connection instances.
Type:

ReceiveHandler

open(port, call_from, call_to, via=None)

Open a new connected-mode connection.

Parameters:

  • port (int) – Port to use for new connection.

  • call_from (str) – Source for new connection.

  • call_to (str) – Destination for new connection.

  • via (list(str) or None) – List of intermediary destinations. Optional.

Returns:

A new Connection instance.

Return type:

Connection

Raises:

ConnectionClassNotFoundError – when no Connection subclass has been defined.