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

    Methods
    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`

© Copyright 2014–2014 Digi International Inc. All rights reserved.