digi.xbee.packets.factory module

This module provides functionality to build XBee packets from bytearray returning the appropriate XBeePacket subclass.

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.
  • 0x7D - Escape
  • 0x11 - XON
  • 0x13 - XOFF

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 unit_test data integrity, a checksum is calculated and verified on non-escaped data.

digi.xbee.packets.factory.build_frame(packet_bytearray, operating_mode=<OperatingMode.API_MODE: (1, 'API mode')>)[source]

Creates a packet from raw data.

Parameters:
  • packet_bytearray (Bytearray) – the raw data of the packet to build.
  • operating_mode (OperatingMode) – the operating mode in which the raw data has been captured.

See also