Package org.ka2ddo.yaac.io

Class BeaconData

java.lang.Object

org.ka2ddo.yaac.io.BeaconData

All Implemented Interfaces:

Serializable, Cloneable, SetBeaconRatesIfc, AX25FrameSource, SendableMessage, GpsDataListener

public class BeaconData
extends Object
implements AX25FrameSource, GpsDataListener, Cloneable, SendableMessage, Serializable, SetBeaconRatesIfc

This class contains all the data associated with a beacon message.

Author:

Andrew Pavlin, KA2DDO

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	BeaconData.BeaconType	Enum defining the APRS message formats that YAAC can use for position beacons.
static enum	BeaconData.PositionType	Enum specifying the specific APRS Position Report message type code used for BeaconType.POSITION and BeaconType.COMPRESSED beacon messages in APRS.

Field Summary

Fields

Modifier and Type	Field	Description
float	ambiguity	The desired ambiguity of reported location data, in fractions of a degree.
String	beaconName	The human-readable identifier for this particular BeaconData object
XmitEncoding	ctcss	Specification of tone or digital squelch used by this repeater.
int	decayRatio	Decay ratio when slowing down the beacon; should be 2 or 3.
static final double	DEFAULT_FIXED_LATITUDE	The default latitude for new deployments is somewhere in the middle of the USA.
static final double	DEFAULT_FIXED_LONGITUDE	The default longitude for new deployments is somewhere in the middle of the USA.
String[]	digipeaters	Digipeater alias combinations to be used for transmitting this beacon, in proportional pathing preference order.
byte	directionality	PHG for compass octant of antenna directionality.
static final String[]	DIRECTIVITY	Display directionality octant strings for the PHG directionality value.
boolean	enabled	Indicate whether this particular beacon should be transmitted.
float	fixedAltitudeM	The fixed altitude of this station in meters above mean sea level.
String	freeText	Free-text comment to be appended after all standard-formatted beacon fields.
byte	gain	PHG code for antenna gain in dB.
byte	height	PHG code for antenna height about average terrain elevation.
int	initialRateSecs	Initial transmit interval for this beacon in seconds.
double	latitude	Fixed position latitude in fractional degrees North.
double	longitude	Fixed position longitude in fractional degrees East.
double	monitorFreq	The frequency in megaHertz on which this station is doing audio monitoring (zero if no audio monitor).
static final String	MYCALL	Name for default BeaconData record.
static final String	NOCALL	Reserved "callsign" for not-yet-specified callsign.
short	offset	The repeater shift direction and magnitude for the repeater input frequency of this station (+1 or -1 for default shift, + or - with an actual number in kiloHertz for non-standard shift).
BeaconData.PositionType	positionType	The sub-variant of human-readable position report message format to use.
byte	power	PHG code for power level.
boolean	reportAltitude	Specify whether altitude (fixed or GPS-reported) should be reported in position reports.
boolean	reportSpeed	Specify whether local GPS speed should be reported in position reports.
boolean	showDFS	Specifies whether DFS (direction finding signal) information should be reported in the position report's free-text comment.
boolean	showPHG	Specify whether PHG (power-height-gain) should be reported in the position report's free-text comment.
int	slowRateSecs	Slow stable transmit rate for non-changing station, in seconds.
short	status	MicE status to report when generating MicE format position reports.
char	symbolCode	The APRS symbol code for this station's symbol.
char	symTableId	The APRS symbol table ID for this station's symbol; this may be an overlay character.
BeaconData.BeaconType	type	APRS format to use for encoding position beacon packet.
boolean	useGpsForPosition	Specifies whether this beacon should ignore its fixed latitude and longitude and use the current position reported by the local GPS receiver.
boolean	useWeather	Specify whether local weather data should be transmitted in the beacon.

Fields inherited from interface org.ka2ddo.ax25.AX25FrameSource

NO_FRAMES

Constructor Summary

Constructors

Constructor	Description
BeaconData()

Method Summary

Modifier and Type	Method	Description
void	addBeaconChangeListener(BeaconChangeListener l)	Register to be informed when the beacon parameters are changed.
void	cancelTransmission()	Cancel all upcoming transmissions of the beacon.
Object	clone()	Creates and returns a copy of this object.
void	copyInto(BeaconData bd, Preferences root, String beaconName)	Copy the contents of this BeaconData object into the specified one, and tell the other one that it was changed if any changes occur.
static void	deleteFromPreferences(Preferences root, String beaconName)	Delete the current beacon settings from Java Preferences.
void	disableForTransmit()	Specify that message should no longer be transmitted.
AX25Message	dup()	Creates and returns a copy of this Message.
byte[]	getBody(boolean countTransmission, ProtocolFamily protocolId, AX25Frame frame)	Get an instance of this message, suitable for transmitting.
Connector	getConnector()	Specify the PortConnector this message should be transmitted through.
int	getDecayRatio()	Get the scaling factor by which the message repeat interval is enlarged (until the default slow send rate is reached).
AX25Frame	getFrame(boolean incrementXmtCount, BeaconData.BeaconType overrideType, ProtocolFamily protocolId)	Get the AX25Frame of the data to transmit.
AX25Frame[]	getFrames(boolean incrementXmtCount, ProtocolFamily protocolId, String senderCallsign)	Get one or more AX25Frames of the data to transmit.
int	getInitialSendRate()	Get the time interval between retransmissions when a message is newly introduced into the system.
long	getLastSendTime()	Get the last time this BeaconData was transmitted.
int	getNumTransmitsBeforeDecay()	Get the number of cycles for a complete iteration over the proportional pathing digipeat path set.
int	getSlowSendRate()	The slowest rate a message should be sent.
void	gpsDataUpdated(GPSDistributor distributor, GpsFix currentFix, boolean isLocal, String source)	Do not call.
boolean	isEnabled()	Test if message should still be transmitted.
boolean	isEquivalent(BeaconData bd)	Compare the contents of this BeaconData object against the specified one, and report if they have the same values (excluding the beacon name).
boolean	isMatchingBeacon(String[] allowedBeacons)	Test whether or not this particular beacon is on the approved list for a given APRS or OpenTRAC transmit port.
boolean	isUseGpsForPosition()	Indicate whether beacon data source can dynamically change its position (latitude/longitude), such as for a mobile station with a GPS.
void	queueForTransmission()	Queue the beacon for transmission after the next transmission interval.
void	queueNow()	Queue the beacon for immediate transmission.
static BeaconData	readFromPreferences(Preferences root, String beaconName)	Load the beacon settings from Java Preferences.
void	removeBeaconChangeListener(BeaconChangeListener l)	Unregister from being informed when the beacon parameters are changed.
void	requeue()	Reschedule the beacon based on its last transmission time and any changes in retransmit interval.
void	resetTransmitCount()	Reinitialize the transmission and backoff counters as if the station was newly on the air.
void	satDataUpdated(GPSDistributor distributor, SatelliteCatalog satCatalog, boolean isLocal, String source)	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	setInitialSendRate(int initialSendRate)	Set the time interval between retransmissions when a message is newly introduced into the system.
void	setSlowSendRate(int slowSendRate)	Set the slowest rate a message should be sent.
String	toString()	Returns a string representation of the object.
void	writeToPreferences(Preferences root, String beaconName)	Store the current beacon settings in Java Preferences.

Methods inherited from class java.lang.Object

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

Field Details

MYCALL

public static final String MYCALL

Name for default BeaconData record.

See Also:

• Constant Field Values

NOCALL

public static final String NOCALL

Reserved "callsign" for not-yet-specified callsign.

See Also:

• Constant Field Values

DEFAULT_FIXED_LATITUDE

public static final double DEFAULT_FIXED_LATITUDE

The default latitude for new deployments is somewhere in the middle of the USA.

See Also:

• Constant Field Values

DEFAULT_FIXED_LONGITUDE

public static final double DEFAULT_FIXED_LONGITUDE

The default longitude for new deployments is somewhere in the middle of the USA.

See Also:

• Constant Field Values

beaconName

public String beaconName

The human-readable identifier for this particular BeaconData object

type

public BeaconData.BeaconType type

APRS format to use for encoding position beacon packet.

positionType

public BeaconData.PositionType positionType

The sub-variant of human-readable position report message format to use.

See Also:

• BeaconData.BeaconType.POSITION

enabled

public boolean enabled

Indicate whether this particular beacon should be transmitted.

useGpsForPosition

public boolean useGpsForPosition

Specifies whether this beacon should ignore its fixed latitude and longitude and use the current position reported by the local GPS receiver.

See Also:

• GpsFix
• GPSDistributor

latitude

public double latitude

Fixed position latitude in fractional degrees North.

longitude

public double longitude

Fixed position longitude in fractional degrees East.

ambiguity

public float ambiguity

The desired ambiguity of reported location data, in fractions of a degree.

reportSpeed

public boolean reportSpeed

Specify whether local GPS speed should be reported in position reports.

See Also:

• useGpsForPosition

reportAltitude

public boolean reportAltitude

Specify whether altitude (fixed or GPS-reported) should be reported in position reports.

See Also:

• fixedAltitudeM
• useGpsForPosition

fixedAltitudeM

public float fixedAltitudeM

The fixed altitude of this station in meters above mean sea level.

See Also:

• reportAltitude

symTableId

public char symTableId

The APRS symbol table ID for this station's symbol; this may be an overlay character.

symbolCode

public char symbolCode

The APRS symbol code for this station's symbol.

monitorFreq

public double monitorFreq

The frequency in megaHertz on which this station is doing audio monitoring (zero if no audio monitor).

offset

public short offset

The repeater shift direction and magnitude for the repeater input frequency of this station (+1 or -1 for default shift, + or - with an actual number in kiloHertz for non-standard shift).

ctcss

public XmitEncoding ctcss

Specification of tone or digital squelch used by this repeater.

status

public short status

MicE status to report when generating MicE format position reports. 0 through 7 are the standard MicE status codes, 8 through 14 are the custom codes 1 through 7.

showPHG

public boolean showPHG

Specify whether PHG (power-height-gain) should be reported in the position report's free-text comment.

showDFS

public boolean showDFS

Specifies whether DFS (direction finding signal) information should be reported in the position report's free-text comment.

power

public byte power

PHG code for power level.

height

public byte height

PHG code for antenna height about average terrain elevation.

gain

public byte gain

PHG code for antenna gain in dB.

directionality

public byte directionality

PHG for compass octant of antenna directionality.

freeText

public String freeText

Free-text comment to be appended after all standard-formatted beacon fields.

useWeather

public boolean useWeather

Specify whether local weather data should be transmitted in the beacon.

initialRateSecs

public int initialRateSecs

Initial transmit interval for this beacon in seconds.

decayRatio

public int decayRatio

Decay ratio when slowing down the beacon; should be 2 or 3.

slowRateSecs

public int slowRateSecs

Slow stable transmit rate for non-changing station, in seconds.

digipeaters

public String[] digipeaters

Digipeater alias combinations to be used for transmitting this beacon, in proportional pathing preference order.

DIRECTIVITY

public static final String[] DIRECTIVITY

Display directionality octant strings for the PHG directionality value.

See Also:

• directionality

Constructor Details

BeaconData

public BeaconData()

Method Details

getBody

public byte[] getBody(boolean countTransmission,
 ProtocolFamily protocolId,
 AX25Frame frame)

Get an instance of this message, suitable for transmitting.

Specified by:

getBody in interface SendableMessage

Parameters:

countTransmission - number of times the message has been transmitted.

protocolId - ProtocolFamily to generate the message in

frame - AX25Frame into which the message will be placed; the decoded message (as opposed to the byte array encoding) should be stored into the field frame.parsedAX25Msg

Returns:

byte array of message, or null if message body cannot be generated in specified protocol, or retransmission count has been exceeded.

See Also:

• AX25Frame.parsedAX25Msg

getFrames

public AX25Frame[] getFrames(boolean incrementXmtCount,
 ProtocolFamily protocolId,
 String senderCallsign)

Get one or more AX25Frames of the data to transmit.

Specified by:

getFrames in interface AX25FrameSource

Parameters:

incrementXmtCount - indicate whether the transmit counter (used to cycle through proportional pathing) should be incremented

protocolId - indicate the protocol to generate this frame for (not relevant for digipeated frames)

senderCallsign - String of local callsign sending this message (may be ignored if digipeating a message from another station)

Returns:

array of AX25Frame objects to transmit, or null indicating nothing to transmit in the specified protocol

getFrame

public AX25Frame getFrame(boolean incrementXmtCount,
 BeaconData.BeaconType overrideType,
 ProtocolFamily protocolId)

Get the AX25Frame of the data to transmit.

Parameters:

incrementXmtCount - indicate whether the transmit counter (used to cycle through proportional pathing) should be incremented

overrideType - BeaconType to use to encode this beacon position report, or null to use configured format

protocolId - indicate the protocol to generate this frame for (not relevant for digipeated frames)

Returns:

array of AX25Frame objects to transmit, or null indicating nothing to transmit in the specified protocol

getNumTransmitsBeforeDecay

public int getNumTransmitsBeforeDecay()

Get the number of cycles for a complete iteration over the proportional pathing digipeat path set.

Specified by:

getNumTransmitsBeforeDecay in interface AX25FrameSource

Returns:

number of transmissions to do one cycle of proportional pathing (value is 2^(N-1) where N is number of path choices)

resetTransmitCount

public void resetTransmitCount()

Reinitialize the transmission and backoff counters as if the station was newly on the air.

getConnector

public Connector getConnector()

Specify the PortConnector this message should be transmitted through.

Specified by:

getConnector in interface AX25FrameSource

Returns:

null for all applicable ports (PortConnector.CAP_XMT_PACKET_DATA and not rejecting this specific packet)

See Also:

• Connector.CAP_XMT_PACKET_DATA

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)

gpsDataUpdated

public void gpsDataUpdated(GPSDistributor distributor,
 GpsFix currentFix,
 boolean isLocal,
 String source)

Do not call. Listener that is called by the GPSDistributor when the GPS data has been updated.

Specified by:

gpsDataUpdated in interface GpsDataListener

Parameters:

distributor - instance of the GPSDistributor

currentFix - current position data reported by the local GPS

isLocal - boolean true if this is GPS data for the local station, false if for a remote GPS receiver

source - String name assigned to remote GPS receiver, or null if for the local receiver

satDataUpdated

public void satDataUpdated(GPSDistributor distributor,
 SatelliteCatalog satCatalog,
 boolean isLocal,
 String source)

Do not call. Listener that is called when the satellite constellation in use changes.

Specified by:

satDataUpdated in interface GpsDataListener

Parameters:

distributor - instance of the GPSDistributor

satCatalog - updated SatelliteCatalog instance

isLocal - boolean true if this is GPS data for the local station, false if for a remote GPS receiver

source - String name assigned to remote GPS receiver, or null if for the local receiver

addBeaconChangeListener

public void addBeaconChangeListener(BeaconChangeListener l)

Register to be informed when the beacon parameters are changed.

Parameters:

l - BeaconChangeListener to register

removeBeaconChangeListener

public void removeBeaconChangeListener(BeaconChangeListener l)

Unregister from being informed when the beacon parameters are changed.

Parameters:

l - BeaconChangeListener to unregister

writeToPreferences

public void writeToPreferences(Preferences root,
 String beaconName)
                        throws BackingStoreException

Store the current beacon settings in Java Preferences.

Parameters:

root - the Preferences node that is the base for YAAC configuration data

beaconName - String name of this beacon instance

Throws:

BackingStoreException - if Preferences could not be updated

readFromPreferences

public static BeaconData readFromPreferences(Preferences root,
 String beaconName)
                                      throws BackingStoreException

Load the beacon settings from Java Preferences.

Parameters:

root - the Preferences node that is the base for YAAC configuration data

beaconName - the String name of the beacon instance to load

Returns:

a filled-in BeaconData structure

Throws:

BackingStoreException - if the beacon Preferences could not be read

deleteFromPreferences

public static void deleteFromPreferences(Preferences root,
 String beaconName)
                                  throws BackingStoreException

Delete the current beacon settings from Java Preferences.

Parameters:

root - the Preferences node that is the base for YAAC configuration data

beaconName - String name of this beacon instance

Throws:

BackingStoreException - if Preferences could not be updated

queueNow

public void queueNow()

Queue the beacon for immediate transmission.

requeue

public void requeue()

Reschedule the beacon based on its last transmission time and any changes in retransmit interval.

queueForTransmission

public void queueForTransmission()

Queue the beacon for transmission after the next transmission interval.

cancelTransmission

public void cancelTransmission()

Cancel all upcoming transmissions of the beacon.

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

a string representation of the object.

isEnabled

public boolean isEnabled()

Test if message should still be transmitted.

Specified by:

isEnabled in interface SendableMessage

Returns:

boolean true if message should still be transmitted

disableForTransmit

public void disableForTransmit()

Specify that message should no longer be transmitted.

Specified by:

disableForTransmit in interface SendableMessage

clone

public Object clone()

Creates and returns a copy of this object. Note this overrides the default clone() only to change the access control and remove the exception.

Overrides:

clone in class Object

Returns:

a clone of this instance.

copyInto

public void copyInto(BeaconData bd,
 Preferences root,
 String beaconName)

Copy the contents of this BeaconData object into the specified one, and tell the other one that it was changed if any changes occur.

Parameters:

bd - target BeaconData to copy into

root - base Preferences object into which updated BeaconData should be saved (or null to not save)

beaconName - String name of the target BeaconData instance

isEquivalent

public boolean isEquivalent(BeaconData bd)

Compare the contents of this BeaconData object against the specified one, and report if they have the same values (excluding the beacon name).

Parameters:

bd - target BeaconData to copy into

Returns:

boolean true if this BeaconData and the other have identical values

dup

public AX25Message dup()

Creates and returns a copy of this Message. Since BeaconData is not actually a message, this returns the message type that would be used to transmit the beacon. Not very efficient, but implemented to meet the interface specification.

Specified by:

dup in interface SendableMessage

Returns:

the AX25Message used to transmit this beacon

isMatchingBeacon

public boolean isMatchingBeacon(String[] allowedBeacons)

Test whether or not this particular beacon is on the approved list for a given APRS or OpenTRAC transmit port. Note that an empty beacon name list matches the default beacon (MYCALL).

Parameters:

allowedBeacons - String array of acceptable beacon names for the port

Returns:

boolean true if this beacon can be transmitted through the requesting port

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

getLastSendTime

public long getLastSendTime()

Get the last time this BeaconData was transmitted.

Returns:

long time in Java milliseconds since Unix epoch