jwo.landserf.process.gps.garmin
Class GarminPacket

java.lang.Object
  jwo.landserf.process.gps.garmin.GarminPacket

Direct Known Subclasses:

PositionDataPacket, ProductDataPacket, ProtocolDataPacket, PVTDataPacket, RecordsPacket, RouteDataPacket, RouteHeaderPacket, TimeDataPacket, TrackDataPacket, TransferCompletedPacket, WaypointDataPacket

public class GarminPacket

extends Object

Represents a packet of information sent to or from Garmin GPS. See Garmin Protocol Specification at www.garmin.com/support/commProtocol.html

Version:

2.2, 9th July, 2004

Author:

Jo Wood, based on the design by Henrik Sorensen (haas@itu.dk).

Field Summary

static int	Cmnd_Abort_Transfer Abort current transfer.
static int	Cmnd_Start_Pvt_Data Start transmitting PVT (Position, velocity, time) Data.
static int	Cmnd_Stop_Pvt_Data Stop transmitting PVT (Position, velocity, time) Data.
static int	Cmnd_Transfer_Alm Transfer almanac.
static int	Cmnd_Transfer_Posn Transfer position.
static int	Cmnd_Transfer_Prx Transfer proximity waypoints.
static int	Cmnd_Transfer_Rte Transfer routes.
static int	Cmnd_Transfer_Time Transfer time.
static int	Cmnd_Transfer_Trk Transfer track log.
static int	Cmnd_Transfer_Wpt Transfer waypoints.
static int	Cmnd_Turn_Off_Pwr Turn off power.
static int	DLE Data link escape.
static int	ETX End of text.
protected int[]	packet The packet in byte form.
static int	Pid_Ack_Byte
static int	Pid_Almanac_Data
static int	Pid_Command_Data
static int	Pid_Date_Time_Data
static int	Pid_Nak_Byte
static int	Pid_Position_Data
static int	Pid_Product_Data
static int	Pid_Product_Rqst
static int	Pid_Protocol_Array
static int	Pid_Prx_Wpt_Data
static int	Pid_Pvt_Data
static int	Pid_Records
static int	Pid_Rte_Hdr
static int	Pid_Rte_Link_Data
static int	Pid_Rte_Wpt_Data
static int	Pid_Trk_Data
static int	Pid_Trk_Hdr
static int	Pid_Wpt_Data
static int	Pid_Xfer_Cmplt

Constructor Summary

GarminPacket()
Creates an empty packet.

GarminPacket(int[] packet)
Creates a new GarminPacket with the given contents.

GarminPacket(int[] packet, boolean calcChecksum)
Creates a new GarminPacket with the given contents.

Method Summary

int	calcChecksum() Calculates the checksum for the packet.
static String	commandToString(int command) Reports the name of the given command ID.
static GarminPacket	createBasicPacket(int type, int[] data) Factory method to create an instance of a basic packets from L000 (basic link protocol).
static GarminPacket	createCommandPacket(int type) Factory method to create an instance of a command packets from A010 (Device Command Protocol 1).
protected int	getByte(int pos) Reports the packet byte at the given position.
int	getDataLength() Reports the number of bytes in the data field of this packet.
int	getID() Reports the ID (ie type) of the packet.
protected int	getLength() Reports the length of the entire packet in bytes.
protected int[]	getPacket() Reports the packet in its original byte form.
String	getRawPacket() Reports a text representation of the bytes in the packet.
static String	idToString(int id) Reports the name of the given packet ID.
int	isLegal() Checks if the packet is valid with regards to header, footer, data field length and checksum.
protected short	readByte(int pos) Reads a single byte in the packet and returns it as a short.
protected double	readDouble(int pos) Reads a Garmin 8-byte double value from the packet.
protected float	readFloat(int pos) Reads a Garmin 4-byte float value from the packet.
protected int	readLong(int pos) Reads a Garmin 4-byte word in the packet and returns it as an int.
protected String	readNullTerminatedString(int pos) Reads a null-terminated string at the given offset in the packet.
protected int	readWord(int pos) Reads a Garmin 2-byte word in the packet and returns it as an integer.
void	setPacket(int[] packet, boolean calcChecksum) Sets the packet contents to the given given content.
String	toString() Reports a summary of the packet's type.

Methods inherited from class java.lang.Object

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

Field Detail

Pid_Ack_Byte

public static final int Pid_Ack_Byte

See Also:

Constant Field Values

Pid_Nak_Byte

public static final int Pid_Nak_Byte

See Also:

Constant Field Values

Pid_Protocol_Array

public static final int Pid_Protocol_Array

See Also:

Constant Field Values

Pid_Product_Rqst

public static final int Pid_Product_Rqst

See Also:

Constant Field Values

Pid_Product_Data

public static final int Pid_Product_Data

See Also:

Constant Field Values

Pid_Command_Data

public static final int Pid_Command_Data

See Also:

Constant Field Values

Pid_Xfer_Cmplt

public static final int Pid_Xfer_Cmplt

See Also:

Constant Field Values

Pid_Date_Time_Data

public static final int Pid_Date_Time_Data

See Also:

Constant Field Values

Pid_Position_Data

public static final int Pid_Position_Data

See Also:

Constant Field Values

Pid_Prx_Wpt_Data

public static final int Pid_Prx_Wpt_Data

See Also:

Constant Field Values

Pid_Records

public static final int Pid_Records

See Also:

Constant Field Values

Pid_Rte_Hdr

public static final int Pid_Rte_Hdr

See Also:

Constant Field Values

Pid_Rte_Wpt_Data

public static final int Pid_Rte_Wpt_Data

See Also:

Constant Field Values

Pid_Almanac_Data

public static final int Pid_Almanac_Data

See Also:

Constant Field Values

Pid_Trk_Data

public static final int Pid_Trk_Data

See Also:

Constant Field Values

Pid_Wpt_Data

public static final int Pid_Wpt_Data

See Also:

Constant Field Values

Pid_Pvt_Data

public static final int Pid_Pvt_Data

See Also:

Constant Field Values

Pid_Rte_Link_Data

public static final int Pid_Rte_Link_Data

See Also:

Constant Field Values

Pid_Trk_Hdr

public static final int Pid_Trk_Hdr

See Also:

Constant Field Values

Cmnd_Abort_Transfer

public static final int Cmnd_Abort_Transfer

Abort current transfer.

See Also:

Constant Field Values

Cmnd_Transfer_Alm

public static final int Cmnd_Transfer_Alm

Transfer almanac.

See Also:

Constant Field Values

Cmnd_Transfer_Posn

public static final int Cmnd_Transfer_Posn

Transfer position.

See Also:

Constant Field Values

Cmnd_Transfer_Prx

public static final int Cmnd_Transfer_Prx

Transfer proximity waypoints.

See Also:

Constant Field Values

Cmnd_Transfer_Rte

public static final int Cmnd_Transfer_Rte

Transfer routes.

See Also:

Constant Field Values

Cmnd_Transfer_Time

public static final int Cmnd_Transfer_Time

Transfer time.

See Also:

Constant Field Values

Cmnd_Transfer_Trk

public static final int Cmnd_Transfer_Trk

Transfer track log.

See Also:

Constant Field Values

Cmnd_Transfer_Wpt

public static final int Cmnd_Transfer_Wpt

Transfer waypoints.

See Also:

Constant Field Values

Cmnd_Turn_Off_Pwr

public static final int Cmnd_Turn_Off_Pwr

Turn off power.

See Also:

Constant Field Values

Cmnd_Start_Pvt_Data

public static final int Cmnd_Start_Pvt_Data

Start transmitting PVT (Position, velocity, time) Data.

See Also:

Constant Field Values

Cmnd_Stop_Pvt_Data

public static final int Cmnd_Stop_Pvt_Data

Stop transmitting PVT (Position, velocity, time) Data.

See Also:

Constant Field Values

DLE

public static final int DLE

Data link escape. Packet boundary.

See Also:

Constant Field Values

ETX

public static final int ETX

End of text. Packet boundary.

See Also:

Constant Field Values

packet

protected int[] packet

The packet in byte form. It is required that the array-length is trimmed to the size of the packet.

Constructor Detail

GarminPacket

public GarminPacket()

Creates an empty packet. Is not normally called directly, but allows subclasses to create their own constructor with calling parent.

GarminPacket

public GarminPacket(int[] packet)

Creates a new GarminPacket with the given contents. Does not recalculate checksum.

Parameters:

packet - Contents to be placed in packet.

Throws:

InvalidPacketException - if packet is malformed.

GarminPacket

public GarminPacket(int[] packet,
                    boolean calcChecksum)

Creates a new GarminPacket with the given contents. If calcChecksum is true, the packet will have its checksum recalculated.

Parameters:

packet - Contents to be placed in packet.

calcChecksum - Calculates checksum if true.

Throws:

InvalidPacketException - if packet is malformed.

Method Detail

setPacket

public void setPacket(int[] packet,
                      boolean calcChecksum)

Sets the packet contents to the given given content. If calcChecksum is true, the packet will have its checksum recalculated.

Parameters:

packet - Contents to be placed in packet.

calcChecksum - Calculates checksum if true.

Throws:

InvalidPacketException - if packet is malformed.

calcChecksum

public int calcChecksum()

Calculates the checksum for the packet. Does not insert it into the correct position of the int[] packet array. The method assumes that the packet is a valid Garmin-packet with all values containing their final values.

getID

public int getID()

Reports the ID (ie type) of the packet.

Returns:

Packet ID.

getDataLength

public int getDataLength()

Reports the number of bytes in the data field of this packet.

Returns:

Size of data field in packet.

getByte

protected int getByte(int pos)

Reports the packet byte at the given position.

Parameters:

pos - Offset position in packet.

Returns:

Byte value at the given position.

getPacket

protected int[] getPacket()

Reports the packet in its original byte form. Note: The array returned is a clone of the array contained in the class. Changing the values in the array will not affect the contents of the class.

Returns:

Clone of the packet contents.

getLength

protected int getLength()

Reports the length of the entire packet in bytes.

Returns:

Packet length.

readWord

protected int readWord(int pos)

Reads a Garmin 2-byte word in the packet and returns it as an integer. This method can be used to read both int and word from a Garmin-packet.

Parameters:

pos - Offset position in packet.

Returns:

Word at the given offset.

readLong

protected int readLong(int pos)

Reads a Garmin 4-byte word in the packet and returns it as an int.

Parameters:

pos - Offset position in packet.

Returns:

Long value at the given offset.

readByte

protected short readByte(int pos)

Reads a single byte in the packet and returns it as a short.

Parameters:

pos - Offset position in packet.

Returns:

Byte value at the given offset.

readFloat

protected float readFloat(int pos)

Reads a Garmin 4-byte float value from the packet.

Parameters:

pos - Offset position in packet.

Returns:

Float value at the given offset.

readDouble

protected double readDouble(int pos)

Reads a Garmin 8-byte double value from the packet.

Parameters:

pos - Offset position in packet.

Returns:

Double value at the given offset.

readNullTerminatedString

protected String readNullTerminatedString(int pos)

Reads a null-terminated string at the given offset in the packet.

Parameters:

pos - Offset position in packet.

Returns:

String found at given offset.

idToString

public static String idToString(int id)

Reports the name of the given packet ID.

Parameters:

id - ID to tranlate.

Returns:

Name of the given ID.

commandToString

public static String commandToString(int command)

Reports the name of the given command ID.

Parameters:

command - Command ID to tranlate.

Returns:

Name of the given command ID.

getRawPacket

public String getRawPacket()

Reports a text representation of the bytes in the packet. Used for debugging purposes only.

Returns:

text representation of the packet.

createCommandPacket

public static GarminPacket createCommandPacket(int type)

Factory method to create an instance of a command packets from A010 (Device Command Protocol 1). type can be one of the following constants:

• Cmnd_Turn_Off_Pwr
• Cmnd_Transfer_Posn
• Cmnd_Transfer_Time
• Cmnd_Abort_Transfer
• Cmnd_Transfer_Alm
• Cmnd_Transfer_Prx
• Cmnd_Transfer_Rte
• Cmnd_Transfer_Trk
• Cmnd_Transfer_Wpt
• Cmnd_Start_Pvt_Data
• Cmnd_Stop_Pvt_Data

Parameters:

type - Type of packet to create.

Returns:

A Garmin packet of the given type or null if type not recognised.

createBasicPacket

public static GarminPacket createBasicPacket(int type,
                                             int[] data)

Factory method to create an instance of a basic packets from L000 (basic link protocol). type can be one of the following constants:

• Pid_Ack_Byte
• Pid_Nak_Byte
• Pid_Protocol_Array
• Pid_Product_Rqst
• Pid_Product_Data

Parameters:

type - Type of packet to create.

data - Data that will be put in the data field of the packet.

Returns:

A Garmin packet of the given type or null if type not recognised.

isLegal

public int isLegal()

Checks if the packet is valid with regards to header, footer, data field length and checksum.

Returns:

The index of the illegal byte or -1 if the packet is well formed.

toString

public String toString()

Reports a summary of the packet's type.

Returns:

Text representation of the type of packet.