org.ka2ddo.yaac.io

Class Transmitter

java.lang.Object

org.ka2ddo.yaac.io.PortManager

org.ka2ddo.yaac.io.Transmitter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Runnable, SetBeaconRatesIfc, Transmitting

public final class Transmitter
extends PortManager
implements java.lang.Runnable, Transmitting, SetBeaconRatesIfc, java.io.Closeable

This class handles scheduling transmit requests to the various ports. It handles retransmissions with backoffs, and reschedulings upon data updates, and caching transmit-related parameters.

Author:

Andrew Pavlin, KA2DDO

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Transmitter.Close Class to shut down the Transmitter as a parallel thread.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ARISS_DIGIPEAT_CHOICE Suggested path for messaging through the International Space Station.
static java.lang.String	OUTNET_CHOICE Suggested path to forward to the Outernet.

Method Summary

Modifier and Type	Method and Description
void	close() Shut down the transmitter.
void	delayedQueue(AX25FrameSource entry, long timeToSend) Queue the specified frame source for transmission over the specified (or all, if not specified) transmit-enabled PortConnectors.
void	flushLog() Force an immediate flush of the transmit log file.
int	getDecayRatio() Get the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).
java.lang.String	getDefaultDigipeatPath() Get the default sequence of digipeat aliases that should be used for locally originated messages (assuming proportional pathing isn't being used).
static java.lang.String	getFarthestReachingDigipeatPathChoice() Return the longest range digipeat alias path configured for the local station.
int	getFastSpeed() Fastest speed of station motion such that position message transmission intervals are maximized to the initial transmission rate, regardless of how fast the station is actually moving.
int	getInitialSendRate() Get the time interval between retransmissions when a message is newly introduced into the system.
static Transmitter	getInstance() Get a reference to the singleton Transmitter object.
PacketExportMode	getLoggerFormat() Get the current format for AX.25 message logging.
int	getMinTurnAngle() Get the minimum amount of turn angle change before YAAC will accelerate reporting beacon position updates ("corner pegging").
int	getRetransmitCount() Get the locally-originated message retransmit count.
int	getSlowSendRate() The slowest rate a message should be sent.
int	getSlowSpeed() Slowest speed of station motion such that position message transmissions are scheduled as if station was not moving.
static java.lang.String[]	getStandardDigipeatPathChoices() Build a sorted list of all the currently registered known choices for digipeat alias paths.
int	getTurnSlope() Get the turn slope, which is the scaling factor for the increase over the minimum turn angle before beacon retransmissions will be accelerated.
boolean	isLocalDest(java.lang.String destCallsign) Test if this callsign is addressed to the local station.
boolean	isUseGpsForPosition() Indicate whether beacon data source can dynamically change its position (latitude/longitude), such as for a mobile station with a GPS.
void	logTransmittedPacket(AX25Frame frame) Log a packet to the transmit log.
void	logTransmittedPacket(AX25Frame frame, long timestamp) Log a packet to the transmit log.
static ConnState	openConnection(AX25Callsign src, AX25Callsign dest, AX25Callsign[] via, ConnectionEstablishmentListener callback, java.lang.Object sessionIdentifier) Attempt to initiate an I-frame connected-mode session from the specified source (usually, the local station) to another station by sending a SABME frame.
void	queue(AX25FrameSource entry) Queue the specified frame source for transmission over the specified (or all, if not specified) transmit-enabled PortConnectors.
void	run() DO NOT CALL.
void	setDecayRatio(int decayRatio) Set the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).
void	setDefaultDigipeatPath(java.lang.String defaultDigipeatPath) Set the default sequence of digipeat aliases that should be used for locally originated messages (assuming proportional pathing isn't being used).
void	setFastSpeed(int fastSpeed) Set fastest speed of station motion such that position message transmission intervals are maximized to the initial transmission rate, regardless of how fast the station is actually moving.
void	setInitialSendRate(int initialSendRate) Set the time interval between retransmissions when a message is newly introduced into the system.
void	setLoggerFormat(PacketExportMode pem) Set the format for AX.25 message logging.
void	setMinTurnAngle(int minTurnAngle) Set the minimum amount of turn angle change before YAAC will accelerate reporting beacon position updates ("corner pegging").
void	setRetransmitCount(int retransmitCount) Set the locally-originated message retransmit count.
void	setSlowSendRate(int slowSendRate) Set the slowest rate a message should be sent.
void	setSlowSpeed(int slowSpeed) Set slowest speed of station motion such that position message transmissions are scheduled as if station was not moving.
void	setTurnSlope(int turnSlope) Set the turn slope, which is the scaling factor for the increase over the minimum turn angle before beacon retransmissions will be accelerated.

Methods inherited from class org.ka2ddo.yaac.io.PortManager

addPortMgmtListener, addPortStatusListener, createPortIfNonexistent, firePortClosed, firePortCreated, firePortDeleted, firePortOpened, firePortStatusChanged, getCallsign, getConnector, getMatchingConnector, getNextAvailablePortNumber, getPortList, getPreferredConnector, getTuneIfc, removePortMgmtListener, removePortStatusListener, setSuggestedLocalCallsign, setTuneIfc

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ARISS_DIGIPEAT_CHOICE

public static final java.lang.String ARISS_DIGIPEAT_CHOICE

Suggested path for messaging through the International Space Station.

See Also:

Constant Field Values

OUTNET_CHOICE

public static final java.lang.String OUTNET_CHOICE

Suggested path to forward to the Outernet.

See Also:

Constant Field Values

Method Detail

getInstance

public static Transmitter getInstance()

Get a reference to the singleton Transmitter object.

Returns:

the Transmitter object

getStandardDigipeatPathChoices

public static java.lang.String[] getStandardDigipeatPathChoices()

Build a sorted list of all the currently registered known choices for digipeat alias paths.

Returns:

array of alias Strings

getFarthestReachingDigipeatPathChoice

public static java.lang.String getFarthestReachingDigipeatPathChoice()

Return the longest range digipeat alias path configured for the local station.

Returns:

digipeat path string

getDecayRatio

public int getDecayRatio()

Get the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).

Specified by:

getDecayRatio in interface SetBeaconRatesIfc

Returns:

int decay ratio

setDecayRatio

public void setDecayRatio(int decayRatio)

Set the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).

Specified by:

setDecayRatio in interface SetBeaconRatesIfc

Parameters:

decayRatio - int decay ratio (should be 2 or 3)

getInitialSendRate

public int getInitialSendRate()

Get the time interval between retransmissions when a message is newly introduced into the system.

Specified by:

getInitialSendRate in interface SetBeaconRatesIfc

Returns:

send interval in seconds

setInitialSendRate

public void setInitialSendRate(int initialSendRate)

Set the time interval between retransmissions when a message is newly introduced into the system.

Specified by:

setInitialSendRate in interface SetBeaconRatesIfc

Parameters:

initialSendRate - send interval in seconds

getSlowSendRate

public int getSlowSendRate()

The slowest rate a message should be sent. For messages to be terminated, they should stop being requeued when the retransmission interval is enlarged to this.

Specified by:

getSlowSendRate in interface SetBeaconRatesIfc

Returns:

transmission interval in seconds

setSlowSendRate

public void setSlowSendRate(int slowSendRate)

Set the slowest rate a message should be sent. For messages to be terminated, they should stop being requeued when the retransmission interval is enlarged to this.

Specified by:

setSlowSendRate in interface SetBeaconRatesIfc

Parameters:

slowSendRate - transmission interval in seconds

isUseGpsForPosition

public boolean isUseGpsForPosition()

Indicate whether beacon data source can dynamically change its position (latitude/longitude), such as for a mobile station with a GPS.

Specified by:

isUseGpsForPosition in interface SetBeaconRatesIfc

Returns:

boolean true if latitude or longitude of beacon can change dynamically (not just through UI)

getSlowSpeed

public int getSlowSpeed()

Slowest speed of station motion such that position message transmissions are scheduled as if station was not moving.

Returns:

slowest speed in current speed units (nm, mi, or km)

See Also:

DistanceUnit

setSlowSpeed

public void setSlowSpeed(int slowSpeed)

Set slowest speed of station motion such that position message transmissions are scheduled as if station was not moving.

Parameters:

slowSpeed - slowest speed in current speed units (nm, mi, or km)

See Also:

DistanceUnit

getFastSpeed

public int getFastSpeed()

Fastest speed of station motion such that position message transmission intervals are maximized to the initial transmission rate, regardless of how fast the station is actually moving.

Returns:

fastest speed in current speed units (nm/hr, mi/hr, or km/hr)

See Also:

DistanceUnit

setFastSpeed

public void setFastSpeed(int fastSpeed)

Set fastest speed of station motion such that position message transmission intervals are maximized to the initial transmission rate, regardless of how fast the station is actually moving.

Parameters:

fastSpeed - fastest speed in current speed units (nm/hr, mi/hr, or km/hr)

See Also:

DistanceUnit

getMinTurnAngle

public int getMinTurnAngle()

Get the minimum amount of turn angle change before YAAC will accelerate reporting beacon position updates ("corner pegging"). This will be adjusted by the speed-specific turn slope.

Returns:

the current minimum turn angle

See Also:

getTurnSlope()

setMinTurnAngle

public void setMinTurnAngle(int minTurnAngle)

Set the minimum amount of turn angle change before YAAC will accelerate reporting beacon position updates ("corner pegging"). This will be adjusted by the speed-specific turn slope.

Parameters:

minTurnAngle - the current minimum turn angle

getTurnSlope

public int getTurnSlope()

Get the turn slope, which is the scaling factor for the increase over the minimum turn angle before beacon retransmissions will be accelerated. The actual amount of turn needed to cause a beacon retransmission is getMinTurnAngle() + GPSDistributor.getInstance().getCurrentFix().speed / getTurnSlope()

Returns:

the turn slope scaling factor

See Also:

getMinTurnAngle()

setTurnSlope

public void setTurnSlope(int turnSlope)

Set the turn slope, which is the scaling factor for the increase over the minimum turn angle before beacon retransmissions will be accelerated. The actual amount of turn needed to cause a beacon retransmission is getMinTurnAngle() + GPSDistributor.getInstance().getCurrentFix().speed / getTurnSlope()

Parameters:

turnSlope - the turn slope scaling factor

getRetransmitCount

public int getRetransmitCount()

Get the locally-originated message retransmit count.

Specified by:

getRetransmitCount in interface Transmitting

Returns:

retransmit count

setRetransmitCount

public void setRetransmitCount(int retransmitCount)

Set the locally-originated message retransmit count.

Parameters:

retransmitCount - number of times to retransmit a locally transmitted message when not acknowledged

getDefaultDigipeatPath

public java.lang.String getDefaultDigipeatPath()

Get the default sequence of digipeat aliases that should be used for locally originated messages (assuming proportional pathing isn't being used).

Returns:

comma-separated ordered list of digipeat aliases

setDefaultDigipeatPath

public void setDefaultDigipeatPath(java.lang.String defaultDigipeatPath)

Set the default sequence of digipeat aliases that should be used for locally originated messages (assuming proportional pathing isn't being used).

Parameters:

defaultDigipeatPath - comma-separated ordered list of digipeat aliases

getLoggerFormat

public PacketExportMode getLoggerFormat()

Get the current format for AX.25 message logging.

Returns:

PacketExportMode in use

setLoggerFormat

public void setLoggerFormat(PacketExportMode pem)

Set the format for AX.25 message logging.

Parameters:

pem - PacketExportMode to use

queue

public void queue(AX25FrameSource entry)

Queue the specified frame source for transmission over the specified (or all, if not specified) transmit-enabled PortConnectors.

Specified by:

queue in interface Transmitting

Parameters:

entry - AX25FrameSource of the frame to be transmitted

delayedQueue

public void delayedQueue(AX25FrameSource entry,
                         long timeToSend)

Queue the specified frame source for transmission over the specified (or all, if not specified) transmit-enabled PortConnectors.

Specified by:

delayedQueue in interface Transmitting

Parameters:

entry - AX25FrameSource of the frame to be transmitted

timeToSend - long time in milliseconds since Unix epoch when packet is to be dequeued and transmitted

run

public void run()

DO NOT CALL. Internal transmit dispatch queue reader.

Specified by:

run in interface java.lang.Runnable

isLocalDest

public boolean isLocalDest(java.lang.String destCallsign)

Test if this callsign is addressed to the local station.

Specified by:

isLocalDest in interface Transmitting

Parameters:

destCallsign - String of AX.25 callsign-SSID to test as a destination

Returns:

boolean true if this callsign is for the local station

openConnection

public static ConnState openConnection(AX25Callsign src,
                                       AX25Callsign dest,
                                       AX25Callsign[] via,
                                       ConnectionEstablishmentListener callback,
                                       java.lang.Object sessionIdentifier)
                                throws java.net.UnknownServiceException,
                                       java.io.IOException

Attempt to initiate an I-frame connected-mode session from the specified source (usually, the local station) to another station by sending a SABME frame.

Parameters:

src - AX25Callsign of originating station (should be a local callsign)

dest - AX25Callsign of destination for connection

via - digipeater path (may be null)

callback - ConnectionEstablishmentListener to be notified of changes in state of the connection

sessionIdentifier - arbitrary unique identifier for the connection, so that the ConnectionEstablishmentListener can tell which connection is being reported about

Returns:

ConnState for opened connection, or null if connection initiating transmission could not be made

Throws:

java.net.UnknownServiceException - if station configured to not support connected-mode packet protocol

java.io.IOException - if connection initiation (SABM frame) could not be sent

close

public void close()

Shut down the transmitter.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

flushLog

public void flushLog()

Force an immediate flush of the transmit log file.

logTransmittedPacket

public void logTransmittedPacket(AX25Frame frame)

Log a packet to the transmit log. Should only be called by AX25-capable port drivers when a packet is actually sent out the port.

Parameters:

frame - already-timestamped AX25Frame that was just transmitted

logTransmittedPacket

public void logTransmittedPacket(AX25Frame frame,
                                 long timestamp)

Log a packet to the transmit log. Should only be called by AX25-capable port drivers when a packet is actually sent out the port.

Parameters:

frame - AX25Frame that was just transmitted

timestamp - long time in milliseconds since UTC epoch when packet was transmitted