SunSPOT API V3.0


com.sun.spot.peripheral.radio
Class RadioPacket

java.lang.Object
  extended by 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()

SunSPOT API V3.0


Copyright © 2006, 2007 Sun Microsystems, Inc. All Rights Reserved.