com.sun.spot.peripheral.radio
Class RadioPacket

java.lang.Object
  com.sun.spot.peripheral.radio.RadioPacket

public class RadioPacket
extends Object

Represents an I802.15.4 radio packet.

Because the standard allows variable length and format packets according to the purpose and data content of the packet, this class's apparent length and contents varies also. For more details about the packet formats, see the first reference below.

RadioPackets are managed - that is, they are reused rather than garbage collected - for efficiency. For this reason, applications must free packets when done with them - see #free().

To obtain RadioPackets, call one of getAckPacket(), getBroadcastPacket(), getDataPacket().

See Also:

http://standards.ieee.org/getieee802/index.html

Field Summary

static int

MIN_PAYLOAD_LENGTH The maximum number of bytes of data that will fit into this packet after allowing for the MAC layer header.

Method Summary

boolean	ackRequest() Check whether this packet wants an acknowledgement
void	calculateAndSetFCS() Calculate a frame check sequence for this packet -- not normally required for the CC2420 radio.
void	checkSequenceNumber() Checks the sequence number and throws a SequenceNumberException if it is incorrect (usually indicating missed packets).
void	copyFrom(RadioPacket otherRP) Make this packet an exact copy of another
static RadioPacket	getAckPacket() Answer a radio packet preformatted for sending ACKs.
static RadioPacket	getBroadcastPacket() Answer a radio packet preformatted for broadcasting intra-PAN.
int	getCorr() CORR measures the average correlation value of the first 4 bytes of the packet header.
static RadioPacket	getDataPacket() Answer a radio packet preformatted for sending data.
byte	getDataSequenceNumber() Answer the DSN (as defined by the I802.15.4 standard) of this packet.
long	getDestinationAddress() Answer the destination address of this packet.
int	getDestinationPanID() Answer the destination pan ID of this packet.
short	getFCS() Answer the frame check sequence for this radio packet.
int	getFrameControl() Answer the frame control field (16 bits) of this packet.
int	getLinkQuality() Link Quality Indication (LQI) is a characterization of the quality of a received packet.
byte	getMACPayloadAt(int offset) Get byte from MAC payload
int	getMACPayloadIntAt(int macPayloadOffset) Answer the int value corresponding to four bytes at a given offset within the MAC payload.
int	getMACPayloadLength() Get length of MACPayload
long	getMACPayloadLongAt(int macPayloadOffset) Answer the long value corresponding to eight bytes at a given offset within the MAC payload.
int	getMACPayloadShortAt(int macPayloadOffset) Answer the short value corresponding to two bytes at a given offset within the MAC payload.
int	getMaxMacPayloadSize() Answer the size of the payload in this packet.
int	getRssi() RSSI (received signal strength indicator) measures the strength (power) of the signal for the packet.
long	getSourceAddress() Answer the source address of this packet.
int	getSourcePanID() Answer the source pan ID of this packet.
boolean	isAck() Answer whether this packet is an ACK packet (i.e.
boolean	isData() Answer whether this packet is a data packet (i.e.
boolean	isFCSValid() Answer whether this packet was received with a correct FCS
boolean	isSeqOK() Answer whether the DSN received implies that packets were missed
RadioPacket	readFrom(DataInputStream dataInputStream)
void	setDestinationAddress(long addr) Set the destination address for the packet.
void	setDestinationPanID(int id) Set the destination pan ID of this packet.
void	setMACPayloadAt(int offset, byte value) Set byte in MAC payload
void	setMACPayloadIntAt(int macPayloadOffset, int value) Fill the four bytes at a given offset within the MAC payload with the int value provided.
void	setMACPayloadLength(int macPayloadLength) Set length of MACPayload
void	setMACPayloadLongAt(int macPayloadOffset, long value) Fill the eight bytes at a given offset within the MAC payload with the long value provided.
void	setMACPayloadShortAt(int macPayloadOffset, int value) Fill the two bytes at a given offset within the MAC payload with the short value provided.
void	setSeqOK(boolean dsnOK)
void	setSourceAddress(long addr) Set the source address for the packet.
String	toString() Returns a string representation of the object.
void	writeOnto(DataOutputStream dataOutputStream)

Methods inherited from class java.lang.Object

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

Field Detail

MIN_PAYLOAD_LENGTH

public static final int MIN_PAYLOAD_LENGTH

The maximum number of bytes of data that will fit into this packet after allowing for the MAC layer header.

See Also:

Constant Field Values

Method Detail

getDataPacket

public static RadioPacket getDataPacket()

Answer a radio packet preformatted for sending data.

Returns:

-- the RadioPacket.

getAckPacket

public static RadioPacket getAckPacket()

Answer a radio packet preformatted for sending ACKs.

Returns:

-- the RadioPacket.

getBroadcastPacket

public static RadioPacket getBroadcastPacket()

Answer a radio packet preformatted for broadcasting intra-PAN. Extra-PAN broadcasting is not currently formatted.

Returns:

-- the RadioPacket.

getDestinationAddress

public long getDestinationAddress()

Answer the destination address of this packet. Will throw an IllegalStateException if this is an ACK packet and therefore has no destination. Will answer 0xFFFF (as per the I802.15.4 spec) for a broadcast packet.

Returns:

-- the address

setDestinationAddress

public void setDestinationAddress(long addr)

Set the destination address for the packet. If the packet can't have a destination, for example an ACK packet, throw IllegalStateException.

Parameters:

addr - - the address to set

getSourceAddress

public long getSourceAddress()

Answer the source address of this packet. Will throw an IllegalStateException if this is an ACK packet and therefore has no source.

Returns:

-- the address

setSourceAddress

public void setSourceAddress(long addr)

Set the source address for the packet. If the packet can't have a source, for example an ACK packet, throw IllegalStateException.

Parameters:

addr - - the address to set

getSourcePanID

public int getSourcePanID()

Answer the source pan ID of this packet. Throw an IllegalStateException if the receiver is an ACK packet and cannot have a pan ID.

Returns:

-- the pan ID

getDestinationPanID

public int getDestinationPanID()

Answer the destination pan ID of this packet. Throw an IllegalStateException if the receiver is an ACK packet and cannot have a pan ID.

Returns:

-- the pan ID

setDestinationPanID

public void setDestinationPanID(int id)

Set the destination pan ID of this packet. Throw an IllegalStateException if the receiver is an ACK packet and cannot have a pan ID.

Parameters:

id - the pan id to set

getDataSequenceNumber

public byte getDataSequenceNumber()

Answer the DSN (as defined by the I802.15.4 standard) of this packet.

Returns:

-- the DSN

getFrameControl

public int getFrameControl()

Answer the frame control field (16 bits) of this packet.

Returns:

- the FCF

getMACPayloadAt

public byte getMACPayloadAt(int offset)

Get byte from MAC payload

Parameters:

offset - -- relative to bottom of MAC payload

Returns:

-- the byte value

setMACPayloadAt

public void setMACPayloadAt(int offset,
                            byte value)

Set byte in MAC payload

Parameters:

offset - - relative to bottom of MAC payload

value - the value to set in the payload

setMACPayloadLength

public void setMACPayloadLength(int macPayloadLength)

Set length of MACPayload

Parameters:

macPayloadLength - - max 104 bytes

Throws:

IOException

getLinkQuality

public int getLinkQuality()

Link Quality Indication (LQI) is a characterization of the quality of a received packet. Its value is computed from the CORR, correlation value. The LQI ranges from 0 (bad) to 255 (good).

Returns:

linkQuality - range 0 to 0xFF

getCorr

public int getCorr()

CORR measures the average correlation value of the first 4 bytes of the packet header. A correlation value of ~110 indicates a maximum quality packet while a value of ~50 is typically the lowest quality packet detectable by the SPOT's receiver.

Returns:

- correlation value

See Also:

getRssi(), getLinkQuality()

getRssi

public int getRssi()

RSSI (received signal strength indicator) measures the strength (power) of the signal for the packet. It ranges from +60 (strong) to -60 (weak). To convert it to decibels relative to 1 mW (= 0 dBm) subtract 45 from it, e.g. for an RSSI of -20 the RF input power is approximately -65 dBm.

Returns:

- RSSI value

See Also:

getCorr(), getLinkQuality()

isSeqOK

public boolean isSeqOK()

Answer whether the DSN received implies that packets were missed

Returns:

true if the sequence number is correct, false if packets were missed (incorrect sequence number)

setSeqOK

public void setSeqOK(boolean dsnOK)

checkSequenceNumber

public void checkSequenceNumber()
                         throws SequenceNumberException

Checks the sequence number and throws a SequenceNumberException if it is incorrect (usually indicating missed packets).

Throws:

SequenceNumberException

getMACPayloadLength

public int getMACPayloadLength()

Get length of MACPayload

Returns:

length - max 104 bytes

copyFrom

public void copyFrom(RadioPacket otherRP)

Make this packet an exact copy of another

Parameters:

otherRP - the packet to copy from

writeOnto

public void writeOnto(DataOutputStream dataOutputStream)
               throws IOException

Throws:

IOException

readFrom

public RadioPacket readFrom(DataInputStream dataInputStream)
                     throws IOException

Throws:

IOException

isAck

public boolean isAck()

Answer whether this packet is an ACK packet (i.e. not data or broadcast)

Returns:

-- boolean

isData

public boolean isData()

Answer whether this packet is a data packet (i.e. not a broadcast or ack packet)

Returns:

-- boolean

ackRequest

public boolean ackRequest()

Check whether this packet wants an acknowledgement

Returns:

-- true if ack required

getMACPayloadIntAt

public int getMACPayloadIntAt(int macPayloadOffset)

Answer the int value corresponding to four bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- int

getMACPayloadLongAt

public long getMACPayloadLongAt(int macPayloadOffset)

Answer the long value corresponding to eight bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- long

setMACPayloadIntAt

public void setMACPayloadIntAt(int macPayloadOffset,
                               int value)

Fill the four bytes at a given offset within the MAC payload with the int value provided.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

value - -- the int value to store in four bytes

setMACPayloadLongAt

public void setMACPayloadLongAt(int macPayloadOffset,
                                long value)

Fill the eight bytes at a given offset within the MAC payload with the long value provided.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

value - -- the long value to store in eight bytes

getMACPayloadShortAt

public int getMACPayloadShortAt(int macPayloadOffset)

Answer the short value corresponding to two bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- short

setMACPayloadShortAt

public void setMACPayloadShortAt(int macPayloadOffset,
                                 int value)

Fill the two bytes at a given offset within the MAC payload with the short value provided.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

value - -- the short value to store in two bytes

getFCS

public short getFCS()

Answer the frame check sequence for this radio packet.

Returns:

-- short value

calculateAndSetFCS

public void calculateAndSetFCS()

Calculate a frame check sequence for this packet -- not normally required for the CC2420 radio. This exists here to support MAC operation over devices that don't calculate the FCS in hardware (for example, the serial line)

isFCSValid

public boolean isFCSValid()

Answer whether this packet was received with a correct FCS

Returns:

-- boolean

getMaxMacPayloadSize

public int getMaxMacPayloadSize()

Answer the size of the payload in this packet.

Returns:

-- number of bytes

toString

public String toString()

Description copied from class: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.