com.digi.xbee.api.packet

Class XBeePacketParser

java.lang.Object

com.digi.xbee.api.packet.XBeePacketParser

public class XBeePacketParser
extends Object

This class reads and parses XBee packets from the input stream returning a generic XBeePacket which can be casted later to the corresponding high level specific API packet.

All the API and API2 logic is already included so all packet reads are independent of the XBee operating mode.

Two API modes are supported and both can be enabled using the AP (API Enable) command:

• API1 - API Without Escapes

  The data frame structure is defined as follows:

    
     Start Delimiter          Length                   Frame Data                   Checksum
         (Byte 1)            (Bytes 2-3)               (Bytes 4-n)                (Byte n + 1)
   +----------------+  +-------------------+  +--------------------------- +  +----------------+
   |      0x7E      |  |   MSB   |   LSB   |  |   API-specific Structure   |  |     1 Byte     |
   +----------------+  +-------------------+  +----------------------------+  +----------------+
                  MSB = Most Significant Byte, LSB = Least Significant Byte
   
   

• API2 - API With Escapes

  The data frame structure is defined as follows:

    
     Start Delimiter          Length                   Frame Data                   Checksum
         (Byte 1)            (Bytes 2-3)               (Bytes 4-n)                (Byte n + 1)
   +----------------+  +-------------------+  +--------------------------- +  +----------------+
   |      0x7E      |  |   MSB   |   LSB   |  |   API-specific Structure   |  |     1 Byte     |
   +----------------+  +-------------------+  +----------------------------+  +----------------+
                       \___________________________________  _________________________________/
                                                           \/
                                               Characters Escaped If Needed
                                               
                  MSB = Most Significant Byte, LSB = Least Significant Byte
   
   

  When sending or receiving an API2 frame, specific data values must be escaped (flagged) so they do not interfere with the data frame sequencing. To escape an interfering data byte, the byte 0x7D is inserted before the byte to be escaped XOR'd with 0x20.

  The data bytes that need to be escaped:

  • 0x7E - Frame Delimiter (SpecialByte.HEADER_BYTE)
  • 0x7D - Escape (SpecialByte.ESCAPE_BYTE)
  • 0x11 - XON (SpecialByte.XON_BYTE)
  • 0x13 - XOFF (SpecialByte.XOFF_BYTE)

The length field has a two-byte value that specifies the number of bytes that will be contained in the frame data field. It does not include the checksum field.

The frame data forms an API-specific structure as follows:

  
   Start Delimiter          Length                   Frame Data                   Checksum
       (Byte 1)            (Bytes 2-3)               (Bytes 4-n)                (Byte n + 1)
 +----------------+  +-------------------+  +--------------------------- +  +----------------+
 |      0x7E      |  |   MSB   |   LSB   |  |   API-specific Structure   |  |     1 Byte     |
 +----------------+  +-------------------+  +----------------------------+  +----------------+
                                            /                                                 \
                                           /  API Identifier        Identifier specific data   \
                                           +------------------+  +------------------------------+
                                           |       cmdID      |  |           cmdData            |
                                           +------------------+  +------------------------------+
 
 

The cmdID frame (API-identifier) indicates which API messages will be contained in the cmdData frame (Identifier-specific data).

To test data integrity, a checksum is calculated and verified on non-escaped data.

See Also:

APIFrameType, XBeePacket, OperatingMode

Constructor Summary

Constructors

Constructor and Description
XBeePacketParser()

Method Summary

Modifier and Type	Method and Description
XBeePacket	parsePacket(byte[] packetByteArray, OperatingMode mode) Parses the bytes from the given array depending on the provided operating mode and returns the API packet.
XBeePacket	parsePacket(InputStream inputStream, OperatingMode mode) Parses the bytes from the given input stream depending on the provided operating mode and returns the API packet.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XBeePacketParser

public XBeePacketParser()

Method Detail

parsePacket

public XBeePacket parsePacket(byte[] packetByteArray,
                              OperatingMode mode)
                       throws InvalidPacketException

Parses the bytes from the given array depending on the provided operating mode and returns the API packet.

The operating mode must be OperatingMode.API or OperatingMode.API_ESCAPE.

Parameters:

packetByteArray - Byte array with the complete frame, starting from the header and ending in the checksum.

mode - XBee device operating mode.

Returns:

Parsed packet from the given byte array.

Throws:

InvalidPacketException - if there is not enough data in the array or if there is an error verifying the checksum or if the payload is invalid for the specified frame type.

IllegalArgumentException - if mode != OperatingMode.API and if mode != OperatingMode.API_ESCAPE.

NullPointerException - if packetByteArray == null or if mode == null.

See Also:

XBeePacket, OperatingMode.API, OperatingMode.API_ESCAPE

parsePacket

public XBeePacket parsePacket(InputStream inputStream,
                              OperatingMode mode)
                       throws InvalidPacketException

Parses the bytes from the given input stream depending on the provided operating mode and returns the API packet.

The operating mode must be OperatingMode.API or OperatingMode.API_ESCAPE.

Parameters:

inputStream - Input stream to read bytes from.

mode - XBee device operating mode.

Returns:

Parsed packet from the input stream.

Throws:

IllegalArgumentException - if mode != OperatingMode.API and if mode != OperatingMode.API_ESCAPE.

InvalidPacketException - if there is not enough data in the stream or if there is an error verifying the checksum or if the payload is invalid for the specified frame type.

NullPointerException - if inputStream == null or if mode == null.

See Also:

XBeePacket, OperatingMode.API, OperatingMode.API_ESCAPE