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.

To obtain RadioPackets, call one of getAckPacket(), getBroadcastPacket(), getDataPacket(). Once a packet has been received from the physical radio, clients - such as the MAC layer - should call decodeFrameControl() to decode the MAC header. Until this is done, accessors for addresses, PAN id and other information will not return correct values.

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	copyFrom(RadioPacket otherRP) Make this packet an exact copy of another
void	decodeFrameControl()
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	getMACPayloadBigEndIntAt(int macPayloadOffset) Answer the big end int value corresponding to four bytes at a given offset within the MAC payload.
long	getMACPayloadBigEndLongAt(int macPayloadOffset) Answer the big end long value corresponding to eight bytes at a given offset within the MAC payload.
int	getMACPayloadBigEndShortAt(int macPayloadOffset) Answer the big end short value corresponding to two bytes at a given offset within the MAC payload.
int	getMACPayloadIntAt(int macPayloadOffset) Answer the little end 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 little end long value corresponding to eight bytes at a given offset within the MAC payload.
int	getMACPayloadShortAt(int macPayloadOffset) Answer the little end 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.
long	getTimestamp()
boolean	isAck() Answer whether this packet is an ACK packet (i.e. not data or broadcast)
boolean	isData() Answer whether this packet is a data packet (i.e. not an ack packet)
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(byte[] inputBuffer, int startingOffset)
RadioPacket	readFrom(DataInputStream dataInputStream)
RadioPacket	readWithoutTimestampFrom(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	setMACPayloadBigEndIntAt(int macPayloadOffset, int value) Fill the four bytes at a given offset within the MAC payload with the big end int value provided.
void	setMACPayloadBigEndLongAt(int macPayloadOffset, long value) Fill the eight bytes at a given offset within the MAC payload with the big end long value provided.
void	setMACPayloadBigEndShortAt(int macPayloadOffset, int value) Fill the two bytes at a given offset within the MAC payload with the big end short value provided.
void	setMACPayloadIntAt(int macPayloadOffset, int value) Fill the four bytes at a given offset within the MAC payload with the little end 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 little end 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.
int	writeOnto(byte[] outputBuffer, int startingOffset)
void	writeOnto(DataOutputStream dataOutputStream)
int	writeWithoutTimestampOnto(byte[] outputBuffer, int startingOffset)

Methods inherited from class java.lang.Object

equals, 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)

getMACPayloadLength

public int getMACPayloadLength()

Get length of MACPayload

Returns:

length - max 104 bytes

decodeFrameControl

public void decodeFrameControl()

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

readWithoutTimestampFrom

public RadioPacket readWithoutTimestampFrom(DataInputStream dataInputStream)
                                     throws IOException

Throws:

IOException

writeOnto

public int writeOnto(byte[] outputBuffer,
                     int startingOffset)

writeWithoutTimestampOnto

public int writeWithoutTimestampOnto(byte[] outputBuffer,
                                     int startingOffset)

readFrom

public RadioPacket readFrom(byte[] inputBuffer,
                            int startingOffset)

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 an 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 little end int value corresponding to four bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- int

getMACPayloadBigEndIntAt

public int getMACPayloadBigEndIntAt(int macPayloadOffset)

Answer the big end 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 little end long value corresponding to eight bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- long

getMACPayloadBigEndLongAt

public long getMACPayloadBigEndLongAt(int macPayloadOffset)

Answer the big end 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 little end int value provided.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

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

setMACPayloadBigEndIntAt

public void setMACPayloadBigEndIntAt(int macPayloadOffset,
                                     int value)

Fill the four bytes at a given offset within the MAC payload with the big end 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 little end long value provided.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

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

setMACPayloadBigEndLongAt

public void setMACPayloadBigEndLongAt(int macPayloadOffset,
                                      long value)

Fill the eight bytes at a given offset within the MAC payload with the big end 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 little end short value corresponding to two bytes at a given offset within the MAC payload.

Parameters:

macPayloadOffset - -- the offset within the MAC payload

Returns:

-- short

getMACPayloadBigEndShortAt

public int getMACPayloadBigEndShortAt(int macPayloadOffset)

Answer the big end 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

setMACPayloadBigEndShortAt

public void setMACPayloadBigEndShortAt(int macPayloadOffset,
                                       int value)

Fill the two bytes at a given offset within the MAC payload with the big end 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.

getTimestamp

public long getTimestamp()