# xbee_api

Xbee API operaiton library

Author | Sebastien Lelong, Copyright © 2012, all rights reserved.
Adapted-by |
Compiler | 2.4o

Description

    access Xbee in API mode

Sources

    mainly inspired by http://code.google.com/p/xbee-arduino/

Notes

    Xbee series 2 only

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte XBEE_MAX_FRAME_DATA_SIZE = 110`
- `const byte XBEE_REMOTE_AT_COMMAND_RESPONSE = 0x97`
- `var xbee_main xbee`
- `const byte XBEE_ZB_IO_SAMPLE_RESPONSE = 0x92`
- `const byte XBEE_RX_64_RSSI_OFFSET = 8`
- `const byte XBEE_UNEXPECTED_START_BYTE = 3`
- `const byte XBEE_API_ID_INDEX = 3`
- `const byte XBEE_ZB_TX_API_LENGTH = 12`
- `const byte XBEE_NOT_JOINED_TO_NETWORK = 0x22`
- `const byte XBEE_ZB_RX_RESPONSE = 0x90`
- `const byte XBEE_ATAP = 2`
- `const byte XBEE_AT_INVALID_COMMAND = 2`
- `const byte XBEE_ZB_TX_REQUEST = 0x10`
- `const byte XBEE_TX_64_REQUEST = 0x0`
- `const byte XBEE_START_BYTE = 0x7e`
- `const byte XBEE_REMOTE_AT_COMMAND_API_LENGTH = 13`
- `const byte XBEE_NO_ERROR = 0`
- `const byte XBEE_ESCAPE = 0x7d`
- `const byte XBEE_AT_INVALID_PARAMETER = 3`
- `const byte XBEE_TX_64_API_LENGTH = 9`
- `const byte XBEE_AT_OK = 0`
- `const byte XBEE_NETWORK_ACK_FAILURE = 0x21`
- `const byte XBEE_RX_16_IO_RESPONSE = 0x83`
- `const byte XBEE_WATCHDOG_TIMER_RESET = 1`
- `const word XBEE_ZB_BROADCAST_ADDRESS = 0xfffe`
- `const byte XBEE_ZB_EXPLICIT_RX_RESPONSE = 0x91`
- `const byte XBEE_RX_16_RESPONSE = 0x81`
- `const byte XBEE_RX_16_RSSI_OFFSET = 2`
- `const byte XBEE_INVALID_DESTINATION_ENDPOINT_SUCCESS = 0x15`
- `const byte XBEE_CHECKSUM_FAILURE = 1`
- `const byte XBEE_SUCCESS = 0x0`
- `const byte XBEE_XON = 0x11`
- `const byte XBEE_SELF_ADDRESSED = 0x23`
- `const byte XBEE_ZB_EXPLICIT_TX_REQUEST = 0x11`
- `const byte XBEE_AT_COMMAND_RESPONSE = 0x88`
- `const byte XBEE_AT_NO_RESPONSE = 4`
- `const byte XBEE_AT_COMMAND_API_LENGTH = 2`
- `const byte XBEE_AT_COMMAND_QUEUE_REQUEST = 0x09`
- `const byte XBEE_PACKET_OVERHEAD_LENGTH = 6`
- `const byte XBEE_ZB_TX_STATUS_RESPONSE = 0x8b`
- `const byte XBEE_ADDRESS_NOT_FOUND = 0x24`
- `const byte XBEE_ASSOCIATED = 2`
- `const byte XBEE_TX_16_API_LENGTH = 3`
- `const byte XBEE_REMOTE_AT_REQUEST = 0x17`
- `const byte XBEE_ZB_TX_UNICAST = 0`
- `const byte XBEE_ZB_IO_NODE_IDENTIFIER_RESPONSE = 0x95`
- `const byte XBEE_AT_COMMAND_REQUEST = 0x08`
- `const byte XBEE_ZB_BROADCAST_PACKET = 0x02`
- `const byte XBEE_PACKET_EXCEEDS_BYTE_ARRAY_LENGTH = 2`
- `const byte XBEE_PAYLOAD_TOO_LARGE = 0x74`
- `const byte XBEE_SYNCHRONIZATION_LOST = 4`
- `const byte XBEE_MODEM_STATUS_RESPONSE = 0x8a`
- `const byte XBEE_BROADCAST_OPTION = 4`
- `const byte XBEE_COORDINATOR_STARTED = 6`
- `const byte XBEE_XOFF = 0x13`
- `const byte XBEE_ACK_OPTION = 0`
- `const byte XBEE_AT_RESPONSE =0x88`
- `const byte XBEE_AT_ERROR = 1`
- `const byte XBEE_ZB_PACKET_ACKNOWLEDGED = 0x01`
- `const byte XBEE_CCA_FAILURE = 0x2`
- `var xbee_request xbee_req`
- `const byte XBEE_ZB_BROADCAST_RADIUS_MAX_HOPS = 0`
- `const byte XBEE_DISASSOCIATED = 3`
- `const byte XBEE_HARDWARE_RESET = 0`
- `const byte XBEE_TX_STATUS_RESPONSE = 0x89`
- `const byte XBEE_RX_64_IO_RESPONSE = 0x82`
- `const byte XBEE_TX_16_REQUEST= 0x1`
- `const byte XBEE_DISABLE_ACK_OPTION = 1`
- `const byte XBEE_ZB_TX_BROADCAST = 8`
- `const byte XBEE_ROUTE_NOT_FOUND = 0x25`
- `const byte XBEE_NO_RESPONSE_FRAME_ID = 0`
- `const byte XBEE_RX_64_RESPONSE = 0x80`
- `const byte XBEE_COORDINATOR_REALIGNMENT = 5`
- `var xbee_response xbee_res`
- `const byte XBEE_DEFAULT_FRAME_ID = 1`
- `const word XBEE_BROADCAST_ADDRESS = 0xffff`

### Procedures

- `xbee_req_payload'put(byte in data)`
- `print_xbee_response()`
- `xbee_send_byte(byte in b, bit in escape)`
- `xbee_receive()`
- `xbee_write_packet()`
- `xbee_send()`
- `xbee_read_packet()`
- `xbee_init()`

Private

- `_xbee_res_reset()`
- `_xbee_res_init()`
- `_xbee_reset_response()`

### Functions

- `xbee_req_get_frame_data(byte in pos) return byte`
- `xbee_res_payload'get() return byte`
- `xbee_req_get_frame_data_length() return byte`

Private

- `_xbee_res_get_packet_length() return byte`

## API details

### Global variables/contants

- `const byte XBEE_MAX_FRAME_DATA_SIZE = 110`

      This value is determined by the largest packet size
      (100 byte payload + 64-bit address + option byte and rssi byte)
      of a series 1 radio

- `const byte XBEE_REMOTE_AT_COMMAND_RESPONSE = 0x97`

  No documentation found

- `var xbee_main xbee`

  No documentation found

- `const byte XBEE_ZB_IO_SAMPLE_RESPONSE = 0x92`

  No documentation found

- `const byte XBEE_RX_64_RSSI_OFFSET = 8`

  No documentation found

- `const byte XBEE_UNEXPECTED_START_BYTE = 3`

  No documentation found

- `const byte XBEE_API_ID_INDEX = 3`

      api is always the third byte in packet

- `const byte XBEE_ZB_TX_API_LENGTH = 12`

      the non-variable length of the frame data (not including frame id or api id
      or variable data size (e.g. payload, at command set value)

- `const byte XBEE_NOT_JOINED_TO_NETWORK = 0x22`

  No documentation found

- `const byte XBEE_ZB_RX_RESPONSE = 0x90`

  No documentation found

- `const byte XBEE_ATAP = 2`

      set to ATAP value of XBee. AP=2 is recommended

- `const byte XBEE_AT_INVALID_COMMAND = 2`

  No documentation found

- `const byte XBEE_ZB_TX_REQUEST = 0x10`

  No documentation found

- `const byte XBEE_TX_64_REQUEST = 0x0`

      Api Id constants

- `const byte XBEE_START_BYTE = 0x7e`

  No documentation found

- `const byte XBEE_REMOTE_AT_COMMAND_API_LENGTH = 13`

  No documentation found

- `const byte XBEE_NO_ERROR = 0`

  No documentation found

- `const byte XBEE_ESCAPE = 0x7d`

  No documentation found

- `const byte XBEE_AT_INVALID_PARAMETER = 3`

  No documentation found

- `const byte XBEE_TX_64_API_LENGTH = 9`

  No documentation found

- `const byte XBEE_AT_OK = 0`

  No documentation found

- `const byte XBEE_NETWORK_ACK_FAILURE = 0x21`

  No documentation found

- `const byte XBEE_RX_16_IO_RESPONSE = 0x83`

  No documentation found

- `const byte XBEE_WATCHDOG_TIMER_RESET = 1`

  No documentation found

- `const word XBEE_ZB_BROADCAST_ADDRESS = 0xfffe`

  No documentation found

- `const byte XBEE_ZB_EXPLICIT_RX_RESPONSE = 0x91`

  No documentation found

- `const byte XBEE_RX_16_RESPONSE = 0x81`

  No documentation found

- `const byte XBEE_RX_16_RSSI_OFFSET = 2`

      frame position of rssi byte

- `const byte XBEE_INVALID_DESTINATION_ENDPOINT_SUCCESS = 0x15`

  No documentation found

- `const byte XBEE_CHECKSUM_FAILURE = 1`

  No documentation found

- `const byte XBEE_SUCCESS = 0x0`

      TX STATUS constants

- `const byte XBEE_XON = 0x11`

  No documentation found

- `const byte XBEE_SELF_ADDRESSED = 0x23`

  No documentation found

- `const byte XBEE_ZB_EXPLICIT_TX_REQUEST = 0x11`

  No documentation found

- `const byte XBEE_AT_COMMAND_RESPONSE = 0x88`

  No documentation found

- `const byte XBEE_AT_NO_RESPONSE = 4`

  No documentation found

- `const byte XBEE_AT_COMMAND_API_LENGTH = 2`

  No documentation found

- `const byte XBEE_AT_COMMAND_QUEUE_REQUEST = 0x09`

  No documentation found

- `const byte XBEE_PACKET_OVERHEAD_LENGTH = 6`

      start/length(2)/api/frameid/checksum bytes

- `const byte XBEE_ZB_TX_STATUS_RESPONSE = 0x8b`

  No documentation found

- `const byte XBEE_ADDRESS_NOT_FOUND = 0x24`

  No documentation found

- `const byte XBEE_ASSOCIATED = 2`

  No documentation found

- `const byte XBEE_TX_16_API_LENGTH = 3`

  No documentation found

- `const byte XBEE_REMOTE_AT_REQUEST = 0x17`

  No documentation found

- `const byte XBEE_ZB_TX_UNICAST = 0`

  No documentation found

- `const byte XBEE_ZB_IO_NODE_IDENTIFIER_RESPONSE = 0x95`

  No documentation found

- `const byte XBEE_AT_COMMAND_REQUEST = 0x08`

  No documentation found

- `const byte XBEE_ZB_BROADCAST_PACKET = 0x02`

  No documentation found

- `const byte XBEE_PACKET_EXCEEDS_BYTE_ARRAY_LENGTH = 2`

  No documentation found

- `const byte XBEE_PAYLOAD_TOO_LARGE = 0x74`

  No documentation found

- `const byte XBEE_SYNCHRONIZATION_LOST = 4`

  No documentation found

- `const byte XBEE_MODEM_STATUS_RESPONSE = 0x8a`

  No documentation found

- `const byte XBEE_BROADCAST_OPTION = 4`

  No documentation found

- `const byte XBEE_COORDINATOR_STARTED = 6`

  No documentation found

- `const byte XBEE_XOFF = 0x13`

  No documentation found

- `const byte XBEE_ACK_OPTION = 0`

      TODO put in tx16 class

- `const byte XBEE_AT_RESPONSE =0x88`

  No documentation found

- `const byte XBEE_AT_ERROR = 1`

  No documentation found

- `const byte XBEE_ZB_PACKET_ACKNOWLEDGED = 0x01`

      RX options

- `const byte XBEE_CCA_FAILURE = 0x2`

  No documentation found

- `var xbee_request xbee_req`

      global var to store one request (save memory, don't pass
      record to proc/func, use global var)

- `const byte XBEE_ZB_BROADCAST_RADIUS_MAX_HOPS = 0`

  No documentation found

- `const byte XBEE_DISASSOCIATED = 3`

  No documentation found

- `const byte XBEE_HARDWARE_RESET = 0`

      modem status

- `const byte XBEE_TX_STATUS_RESPONSE = 0x89`

  No documentation found

- `const byte XBEE_RX_64_IO_RESPONSE = 0x82`

  No documentation found

- `const byte XBEE_TX_16_REQUEST= 0x1`

  No documentation found

- `const byte XBEE_DISABLE_ACK_OPTION = 1`

  No documentation found

- `const byte XBEE_ZB_TX_BROADCAST = 8`

  No documentation found

- `const byte XBEE_ROUTE_NOT_FOUND = 0x25`

  No documentation found

- `const byte XBEE_NO_RESPONSE_FRAME_ID = 0`

  No documentation found

- `const byte XBEE_RX_64_RESPONSE = 0x80`

  No documentation found

- `const byte XBEE_COORDINATOR_REALIGNMENT = 5`

  No documentation found

- `var xbee_response xbee_res`

      global var to store one request (save memory, don't pass
      record to proc/func, use global var)

- `const byte XBEE_DEFAULT_FRAME_ID = 1`

  No documentation found

- `const word XBEE_BROADCAST_ADDRESS = 0xffff`

  No documentation found

### Procedures

- `xbee_req_payload'put(byte in data)`

      Write a byte in request payload, increasing position for next call. There's
      no check whether position remains in payload. See xbee_res_payload'get for
      more.

- `print_xbee_response()`

  No documentation found

- `xbee_send_byte(byte in b, bit in escape)`

      internally used, send a byte through Xbee carrier, honoring escape setting

- `xbee_receive()`

      Wrapper around xbee_read_packet. It actually calls it several time until
      it actually receives a XBEE_ZB_RX_RESPONSE (api_id). This is useful when
      several messages are exchanged between coordinator or router, as, for
      instance, coordinator may reply with a tx_status, then a rx response during
      communication. tx_status are kind of administrative message, while "rx"
      response are the one you may only interested in. If so, use this procedure,
      once called you'll a xbee_res "rx" response containing expecting data
      (hopefully)...

- `xbee_write_packet()`

      send xbee_req request. xbee_req must be fill in first before
      calling this procedure. See xbee_req record definition.

- `xbee_send()`

      Send a request and read tx_status response. If delivery failed, try again
      (until if works...)

- `xbee_read_packet()`

      Read a full packet, fill in xbee_res response. This may be a blocking call
      as underlying data carrier may block until data is read (typically when
      serial_hw_data is involved here).
      Once called, you may check xbee_res.error_code = 0 to make sure everything
      if fine. You may also check xbee_res.api_id value (see constants at the
      beginning) to know what lind of response it is (rx, tx_status, etc...)

- `xbee_init()`

      must be called once lib is included

Private

- `_xbee_res_reset()`

      init/reset xbee_res response.

- `_xbee_res_init()`

      init xbee_res response record.

- `_xbee_reset_response()`

  No documentation found

### Functions

- `xbee_req_get_frame_data(byte in pos) return byte`

      return data byte contained in request according to a give index position

- `xbee_res_payload'get() return byte`

      read one byte from response's payload. Each time it's called, position in
      payload is increased ready to get next byte. There's no check whether
      position is within payload, so be carefull and check how many time you call
      it according to XBEE_PAYLOAD_SIZE.
      (this is somewhat by design, because payload is a buffer, reserved space and
      the actual data of interest, contained in this buffer, may vary so only the
      caller knows how many bytes she wants to get from it).

- `xbee_req_get_frame_data_length() return byte`

  No documentation found

Private

- `_xbee_res_get_packet_length() return byte`

  No documentation found

## Related samples

Here are the list of samples which use this library:

18f27j53 | 18f27j53_xbee_api_rx.jal
18f27j53 | 18f27j53_xbee_api_tx.jal