XBee.h

00001 /**
00002  * XBee-mbed library
00003  * Modified for mbed, 2011 Suga.
00004  *
00005  *
00006  * Copyright (c) 2009 Andrew Rapp. All rights reserved.
00007  *
00008  * This file is part of XBee-Arduino.
00009  *
00010  * XBee-Arduino is free software: you can redistribute it and/or modify
00011  * it under the terms of the GNU General Public License as published by
00012  * the Free Software Foundation, either version 3 of the License, or
00013  * (at your option) any later version.
00014  *
00015  * XBee-Arduino is distributed in the hope that it will be useful,
00016  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00017  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018  * GNU General Public License for more details.
00019  *
00020  * You should have received a copy of the GNU General Public License
00021  * along with XBee-Arduino.  If not, see <http://www.gnu.org/licenses/>.
00022  */
00023 
00024 /** @file
00025  * @brief XBee library for mbed
00026  */
00027 
00028 #include "XBee_conf.h"
00029 
00030 #ifndef XBee_h
00031 #define XBee_h
00032 
00033 #include "mbed.h"
00034 #include <inttypes.h>
00035 #include <iostream>
00036 
00037 #define SERIES_1
00038 #define SERIES_2
00039 #define WIFI
00040 
00041 // set to ATAP value of XBee. AP=2 is recommended
00042 #define ATAP 2
00043 
00044 #define START_BYTE 0x7e
00045 #define ESCAPE 0x7d
00046 #define XON 0x11
00047 #define XOFF 0x13
00048 
00049 // This value determines the size of the byte array for receiving RX packets
00050 // Most users won't be dealing with packets this large so you can adjust this
00051 // value to reduce memory consumption. But, remember that
00052 // if a RX packet exceeds this size, it cannot be parsed!
00053 
00054 // 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
00055 //#define MAX_FRAME_DATA_SIZE 110
00056 #define MAX_FRAME_DATA_SIZE 1520
00057 #define MAX_RXBUF_SIZE 32
00058 
00059 #define BROADCAST_ADDRESS 0xffff
00060 #define ZB_BROADCAST_ADDRESS 0xfffe
00061 
00062 // 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)
00063 #define ZB_TX_API_LENGTH 12
00064 #define TX_16_API_LENGTH 3
00065 #define TX_64_API_LENGTH 9
00066 #define AT_COMMAND_API_LENGTH 2
00067 #define REMOTE_AT_COMMAND_API_LENGTH 13
00068 // start/length(2)/api/frameid/checksum bytes
00069 #define PACKET_OVERHEAD_LENGTH 6
00070 // api is always the third byte in packet
00071 #define API_ID_INDEX 3
00072 
00073 // frame position of rssi byte
00074 #define RX_16_RSSI_OFFSET 2
00075 #define RX_64_RSSI_OFFSET 8
00076 
00077 #define DEFAULT_FRAME_ID 1
00078 #define NO_RESPONSE_FRAME_ID 0
00079 
00080 // TODO put in tx16 class
00081 #define ACK_OPTION 0
00082 #define DISABLE_ACK_OPTION 1
00083 #define BROADCAST_OPTION 4
00084 
00085 // RX options
00086 #define ZB_PACKET_ACKNOWLEDGED 0x01
00087 #define ZB_BROADCAST_PACKET 0x02
00088 
00089 // not everything is implemented!
00090 /**
00091  * Api Id constants
00092  */
00093 #define TX_64_REQUEST 0x0
00094 #define TX_16_REQUEST 0x1
00095 #define AT_COMMAND_REQUEST 0x08
00096 #define AT_COMMAND_QUEUE_REQUEST 0x09
00097 #define REMOTE_AT_REQUEST 0x17
00098 #define ZB_TX_REQUEST 0x10
00099 #define ZB_EXPLICIT_TX_REQUEST 0x11
00100 #define RX_64_RESPONSE 0x80
00101 #define RX_16_RESPONSE 0x81
00102 #define RX_64_IO_RESPONSE 0x82
00103 #define RX_16_IO_RESPONSE 0x83
00104 #define AT_RESPONSE 0x88
00105 #define TX_STATUS_RESPONSE 0x89
00106 #define MODEM_STATUS_RESPONSE 0x8a
00107 #define ZB_RX_RESPONSE 0x90
00108 #define ZB_EXPLICIT_RX_RESPONSE 0x91
00109 #define ZB_TX_STATUS_RESPONSE 0x8b
00110 #define ZB_IO_SAMPLE_RESPONSE 0x92
00111 #define ZB_IO_NODE_IDENTIFIER_RESPONSE 0x95
00112 #define AT_COMMAND_RESPONSE 0x88
00113 #define REMOTE_AT_COMMAND_RESPONSE 0x97
00114 
00115 
00116 /**
00117  * TX STATUS constants
00118  */
00119 #define    SUCCESS 0x0
00120 #define CCA_FAILURE 0x2
00121 #define INVALID_DESTINATION_ENDPOINT_SUCCESS 0x15
00122 #define    NETWORK_ACK_FAILURE 0x21
00123 #define NOT_JOINED_TO_NETWORK 0x22
00124 #define    SELF_ADDRESSED 0x23
00125 #define ADDRESS_NOT_FOUND 0x24
00126 #define ROUTE_NOT_FOUND 0x25
00127 #define PAYLOAD_TOO_LARGE 0x74
00128 
00129 // modem status
00130 #define HARDWARE_RESET 0
00131 #define WATCHDOG_TIMER_RESET 1
00132 #define ASSOCIATED 2
00133 #define DISASSOCIATED 3
00134 #define SYNCHRONIZATION_LOST 4
00135 #define COORDINATOR_REALIGNMENT 5
00136 #define COORDINATOR_STARTED 6
00137 
00138 #define ZB_BROADCAST_RADIUS_MAX_HOPS 0
00139 
00140 #define ZB_TX_UNICAST 0
00141 #define ZB_TX_BROADCAST 8
00142 
00143 #define AT_OK 0
00144 #define AT_ERROR  1
00145 #define AT_INVALID_COMMAND 2
00146 #define AT_INVALID_PARAMETER 3
00147 #define AT_NO_RESPONSE 4
00148 
00149 #define NO_ERROR 0
00150 #define CHECKSUM_FAILURE 1
00151 #define PACKET_EXCEEDS_BYTE_ARRAY_LENGTH 2
00152 #define UNEXPECTED_START_BYTE 3
00153 
00154 /**
00155  * The super class of all XBee responses (RX packets)
00156  * Users should never attempt to create an instance of this class; instead
00157  * create an instance of a subclass
00158  * It is recommend to reuse subclasses to conserve memory
00159  */
00160 class XBeeResponse {
00161 public:
00162     //static const int MODEM_STATUS = 0x8a;
00163     /**
00164      * Default constructor
00165      */
00166     XBeeResponse();
00167     /**
00168      * Returns Api Id of the response
00169      */
00170     uint8_t getApiId();
00171     void setApiId(uint8_t apiId);
00172     /**
00173      * Returns the MSB length of the packet
00174      */
00175     uint8_t getMsbLength();
00176     void setMsbLength(uint8_t msbLength);
00177     /**
00178      * Returns the LSB length of the packet
00179      */
00180     uint8_t getLsbLength();
00181     void setLsbLength(uint8_t lsbLength);
00182     /**
00183      * Returns the packet checksum
00184      */
00185     uint8_t getChecksum();
00186     void setChecksum(uint8_t checksum);
00187     /**
00188      * Returns the length of the frame data: all bytes after the api id, and prior to the checksum
00189      * Note up to release 0.1.2, this was incorrectly including the checksum in the length.
00190      */
00191     uint16_t getFrameDataLength();
00192     void setFrameData(uint8_t* frameDataPtr);
00193     /**
00194      * Returns the buffer that contains the response.
00195      * Starts with byte that follows API ID and includes all bytes prior to the checksum
00196      * Length is specified by getFrameDataLength()
00197      * Note: Unlike Digi's definition of the frame data, this does not start with the API ID..
00198      * The reason for this is all responses include an API ID, whereas my frame data
00199      * includes only the API specific data.
00200      */
00201     uint8_t* getFrameData();
00202 
00203     void setFrameLength(uint16_t frameLength);
00204     // to support future 65535 byte packets I guess
00205     /**
00206      * Returns the length of the packet
00207      */
00208     uint16_t getPacketLength();
00209     /**
00210      * Resets the response to default values
00211      */
00212     void reset();
00213     /**
00214      * Initializes the response
00215      */
00216     void init();
00217 #ifdef SERIES_2
00218     /**
00219      * Call with instance of ZBTxStatusResponse class only if getApiId() == ZB_TX_STATUS_RESPONSE
00220      * to populate response
00221      */
00222     void getZBTxStatusResponse(XBeeResponse &response);
00223     /**
00224      * Call with instance of ZBRxResponse class only if getApiId() == ZB_RX_RESPONSE
00225      * to populate response
00226      */
00227     void getZBRxResponse(XBeeResponse &response);
00228     /**
00229      * Call with instance of ZBRxIoSampleResponse class only if getApiId() == ZB_IO_SAMPLE_RESPONSE
00230      * to populate response
00231      */
00232     void getZBRxIoSampleResponse(XBeeResponse &response);
00233 #endif
00234 #ifdef SERIES_1
00235     /**
00236      * Call with instance of TxStatusResponse only if getApiId() == TX_STATUS_RESPONSE
00237      */
00238     void getTxStatusResponse(XBeeResponse &response);
00239     /**
00240      * Call with instance of Rx16Response only if getApiId() == RX_16_RESPONSE
00241      */
00242     void getRx16Response(XBeeResponse &response);
00243     /**
00244      * Call with instance of Rx64Response only if getApiId() == RX_64_RESPONSE
00245      */
00246     void getRx64Response(XBeeResponse &response);
00247     /**
00248      * Call with instance of Rx16IoSampleResponse only if getApiId() == RX_16_IO_RESPONSE
00249      */
00250     void getRx16IoSampleResponse(XBeeResponse &response);
00251     /**
00252      * Call with instance of Rx64IoSampleResponse only if getApiId() == RX_64_IO_RESPONSE
00253      */
00254     void getRx64IoSampleResponse(XBeeResponse &response);
00255 #endif
00256     /**
00257      * Call with instance of AtCommandResponse only if getApiId() == AT_COMMAND_RESPONSE
00258      */
00259     void getAtCommandResponse(XBeeResponse &responses);
00260     /**
00261      * Call with instance of RemoteAtCommandResponse only if getApiId() == REMOTE_AT_COMMAND_RESPONSE
00262      */
00263     void getRemoteAtCommandResponse(XBeeResponse &response);
00264     /**
00265      * Call with instance of ModemStatusResponse only if getApiId() == MODEM_STATUS_RESPONSE
00266      */
00267     void getModemStatusResponse(XBeeResponse &response);
00268     /**
00269      * Returns true if the response has been successfully parsed and is complete and ready for use
00270      */
00271     bool isAvailable();
00272     void setAvailable(bool complete);
00273     /**
00274      * Returns true if the response contains errors
00275      */
00276     bool isError();
00277     /**
00278      * Returns an error code, or zero, if successful.
00279      * Error codes include: CHECKSUM_FAILURE, PACKET_EXCEEDS_BYTE_ARRAY_LENGTH, UNEXPECTED_START_BYTE
00280      */
00281     uint8_t getErrorCode();
00282     void setErrorCode(uint8_t errorCode);
00283 protected:
00284     // pointer to frameData
00285     uint8_t* _frameDataPtr;
00286 private:
00287     void setCommon(XBeeResponse &target);
00288     uint8_t _apiId;
00289     uint8_t _msbLength;
00290     uint8_t _lsbLength;
00291     uint8_t _checksum;
00292     uint16_t _frameLength;
00293     bool _complete;
00294     uint8_t _errorCode;
00295 };
00296 
00297 class XBeeAddress {
00298 public:
00299     XBeeAddress();
00300 };
00301 
00302 /**
00303  * Represents a 64-bit XBee Address
00304  */
00305 class XBeeAddress64 : public XBeeAddress {
00306 public:
00307     XBeeAddress64(uint32_t msb, uint32_t lsb);
00308     XBeeAddress64();
00309     uint32_t getMsb();
00310     uint32_t getLsb();
00311     void setMsb(uint32_t msb);
00312     void setLsb(uint32_t lsb);
00313 private:
00314     uint32_t _msb;
00315     uint32_t _lsb;
00316 };
00317 
00318 //class XBeeAddress16 : public XBeeAddress {
00319 //public:
00320 //    XBeeAddress16(uint16_t addr);
00321 //    XBeeAddress16();
00322 //    uint16_t getAddress();
00323 //    void setAddress(uint16_t addr);
00324 //private:
00325 //    uint16_t _addr;
00326 //};
00327 
00328 /**
00329  * This class is extended by all Responses that include a frame id
00330  */
00331 class FrameIdResponse : public XBeeResponse {
00332 public:
00333     FrameIdResponse();
00334     uint8_t getFrameId();
00335 private:
00336     uint8_t _frameId;
00337 };
00338 
00339 /**
00340  * Common functionality for both Series 1 and 2 data RX data packets
00341  */
00342 class RxDataResponse : public XBeeResponse {
00343 public:
00344     RxDataResponse();
00345     /**
00346      * Returns the specified index of the payload.  The index may be 0 to getDataLength() - 1
00347      * This method is deprecated; use uint8_t* getData()
00348      */
00349     uint8_t getData(int index);
00350     /**
00351      * Returns the payload array.  This may be accessed from index 0 to getDataLength() - 1
00352      */
00353     uint8_t* getData();
00354     /**
00355      * Returns the length of the payload
00356      */
00357     virtual uint16_t getDataLength() = 0;
00358     /**
00359      * Returns the position in the frame data where the data begins
00360      */
00361     virtual uint8_t getDataOffset() = 0;
00362 };
00363 
00364 // getResponse to return the proper subclass:
00365 // we maintain a pointer to each type of response, when a response is parsed, it is allocated only if NULL
00366 // can we allocate an object in a function?
00367 
00368 #ifdef SERIES_2
00369 /**
00370  * Represents a Series 2 TX status packet
00371  */
00372 class ZBTxStatusResponse : public FrameIdResponse {
00373     public:
00374         ZBTxStatusResponse();
00375         uint16_t getRemoteAddress();
00376         uint8_t getTxRetryCount();
00377         uint8_t getDeliveryStatus();
00378         uint8_t getDiscoveryStatus();
00379         bool isSuccess();
00380 };
00381 
00382 /**
00383  * Represents a Series 2 RX packet
00384  */
00385 class ZBRxResponse : public RxDataResponse {
00386 public:
00387     ZBRxResponse();
00388     XBeeAddress64& getRemoteAddress64();
00389     uint16_t getRemoteAddress16();
00390     uint8_t getOption();
00391     virtual uint16_t getDataLength();
00392     // frame position where data starts
00393     virtual uint8_t getDataOffset();
00394 private:
00395     XBeeAddress64 _remoteAddress64;
00396 };
00397 
00398 /**
00399  * Represents a Series 2 RX I/O Sample packet
00400  */
00401 class ZBRxIoSampleResponse : public ZBRxResponse {
00402 public:
00403     ZBRxIoSampleResponse();
00404     bool containsAnalog();
00405     bool containsDigital();
00406     /**
00407      * Returns true if the pin is enabled
00408      */
00409     bool isAnalogEnabled(uint8_t pin);
00410     /**
00411      * Returns true if the pin is enabled
00412      */
00413     bool isDigitalEnabled(uint8_t pin);
00414     /**
00415      * Returns the 10-bit analog reading of the specified pin.
00416      * Valid pins include ADC:xxx.
00417      */
00418     uint16_t getAnalog(uint8_t pin);
00419     /**
00420      * Returns true if the specified pin is high/on.
00421      * Valid pins include DIO:xxx.
00422      */
00423     bool isDigitalOn(uint8_t pin);
00424     uint8_t getDigitalMaskMsb();
00425     uint8_t getDigitalMaskLsb();
00426     uint8_t getAnalogMask();
00427 };
00428 
00429 #endif
00430 
00431 #ifdef SERIES_1
00432 /**
00433  * Represents a Series 1 TX Status packet
00434  */
00435 class TxStatusResponse : public FrameIdResponse {
00436     public:
00437         TxStatusResponse();
00438         uint8_t getStatus();
00439         bool isSuccess();
00440 };
00441 
00442 /**
00443  * Represents a Series 1 RX packet
00444  */
00445 class RxResponse : public RxDataResponse {
00446 public:
00447     RxResponse();
00448     // remember rssi is negative but this is unsigned byte so it's up to you to convert
00449     uint8_t getRssi();
00450     uint8_t getOption();
00451     bool isAddressBroadcast();
00452     bool isPanBroadcast();
00453     virtual uint16_t getDataLength();
00454     virtual uint8_t getDataOffset();
00455     virtual uint8_t getRssiOffset() = 0;
00456 };
00457 
00458 /**
00459  * Represents a Series 1 16-bit address RX packet
00460  */
00461 class Rx16Response : public RxResponse {
00462 public:
00463     Rx16Response();
00464     virtual uint8_t getRssiOffset();
00465     uint16_t getRemoteAddress16();
00466 protected:
00467     uint16_t _remoteAddress;
00468 };
00469 
00470 /**
00471  * Represents a Series 1 64-bit address RX packet
00472  */
00473 class Rx64Response : public RxResponse {
00474 public:
00475     Rx64Response();
00476     virtual uint8_t getRssiOffset();
00477     XBeeAddress64& getRemoteAddress64();
00478 private:
00479     XBeeAddress64 _remoteAddress;
00480 };
00481 
00482 /**
00483  * Represents a Series 1 RX I/O Sample packet
00484  */
00485 class RxIoSampleBaseResponse : public RxResponse {
00486     public:
00487         RxIoSampleBaseResponse();
00488         /**
00489          * Returns the number of samples in this packet
00490          */
00491         uint8_t getSampleSize();
00492         bool containsAnalog();
00493         bool containsDigital();
00494         /**
00495          * Returns true if the specified analog pin is enabled
00496          */
00497         bool isAnalogEnabled(uint8_t pin);
00498         /**
00499          * Returns true if the specified digital pin is enabled
00500          */
00501         bool isDigitalEnabled(uint8_t pin);
00502         /**
00503          * Returns the 10-bit analog reading of the specified pin.
00504          * Valid pins include ADC:0-5.  Sample index starts at 0
00505          */
00506         uint16_t getAnalog(uint8_t pin, uint8_t sample);
00507         /**
00508          * Returns true if the specified pin is high/on.
00509          * Valid pins include DIO:0-8.  Sample index starts at 0
00510          */
00511         bool isDigitalOn(uint8_t pin, uint8_t sample);
00512         uint8_t getSampleOffset();
00513     private:
00514 };
00515 
00516 class Rx16IoSampleResponse : public RxIoSampleBaseResponse {
00517 public:
00518     Rx16IoSampleResponse();
00519     uint16_t getRemoteAddress16();
00520     virtual uint8_t getRssiOffset();
00521 
00522 };
00523 
00524 class Rx64IoSampleResponse : public RxIoSampleBaseResponse {
00525 public:
00526     Rx64IoSampleResponse();
00527     XBeeAddress64& getRemoteAddress64();
00528     virtual uint8_t getRssiOffset();
00529 private:
00530     XBeeAddress64 _remoteAddress;
00531 };
00532 
00533 #endif
00534 
00535 /**
00536  * Represents a Modem Status RX packet
00537  */
00538 class ModemStatusResponse : public XBeeResponse {
00539 public:
00540     ModemStatusResponse();
00541     uint8_t getStatus();
00542 };
00543 
00544 /**
00545  * Represents an AT Command RX packet
00546  */
00547 class AtCommandResponse : public FrameIdResponse {
00548     public:
00549         AtCommandResponse();
00550         /**
00551          * Returns an array containing the two character command
00552          */
00553         uint8_t* getCommand();
00554         /**
00555          * Returns the command status code.
00556          * Zero represents a successful command
00557          */
00558         uint8_t getStatus();
00559         /**
00560          * Returns an array containing the command value.
00561          * This is only applicable to query commands.
00562          */
00563         uint8_t* getValue();
00564         /**
00565          * Returns the length of the command value array.
00566          */
00567         uint16_t getValueLength();
00568         /**
00569          * Returns true if status equals AT_OK
00570          */
00571         bool isOk();
00572 };
00573 
00574 /**
00575  * Represents a Remote AT Command RX packet
00576  */
00577 class RemoteAtCommandResponse : public AtCommandResponse {
00578     public:
00579         RemoteAtCommandResponse();
00580         /**
00581          * Returns an array containing the two character command
00582          */
00583         uint8_t* getCommand();
00584         /**
00585          * Returns the command status code.
00586          * Zero represents a successful command
00587          */
00588         uint8_t getStatus();
00589         /**
00590          * Returns an array containing the command value.
00591          * This is only applicable to query commands.
00592          */
00593         uint8_t* getValue();
00594         /**
00595          * Returns the length of the command value array.
00596          */
00597         uint16_t getValueLength();
00598         /**
00599          * Returns the 16-bit address of the remote radio
00600          */
00601         uint16_t getRemoteAddress16();
00602         /**
00603          * Returns the 64-bit address of the remote radio
00604          */
00605         XBeeAddress64& getRemoteAddress64();
00606         /**
00607          * Returns true if command was successful
00608          */
00609         bool isOk();
00610     private:
00611         XBeeAddress64 _remoteAddress64;
00612 };
00613 
00614 
00615 /**
00616  * Super class of all XBee requests (TX packets)
00617  * Users should never create an instance of this class; instead use an subclass of this class
00618  * It is recommended to reuse Subclasses of the class to conserve memory
00619  * <p/>
00620  * This class allocates a buffer to
00621  */
00622 class XBeeRequest {
00623 public:
00624     /**
00625      * Constructor
00626      * TODO make protected
00627      */
00628     XBeeRequest(uint8_t apiId, uint8_t frameId);
00629     /**
00630      * Sets the frame id.  Must be between 1 and 255 inclusive to get a TX status response.
00631      */
00632     void setFrameId(uint8_t frameId);
00633     /**
00634      * Returns the frame id
00635      */
00636     uint8_t getFrameId();
00637     /**
00638      * Returns the API id
00639      */
00640     uint8_t getApiId();
00641     // setting = 0 makes this a pure virtual function, meaning the subclass must implement, like abstract in java
00642     /**
00643      * Starting after the frame id (pos = 0) and up to but not including the checksum
00644      * Note: Unlike Digi's definition of the frame data, this does not start with the API ID.
00645      * The reason for this is the API ID and Frame ID are common to all requests, whereas my definition of
00646      * frame data is only the API specific data.
00647      */
00648     virtual uint8_t getFrameData(uint16_t pos) = 0;
00649     /**
00650      * Returns the size of the api frame (not including frame id or api id or checksum).
00651      */
00652     virtual uint16_t getFrameDataLength() = 0;
00653     //void reset();
00654 protected:
00655     void setApiId(uint8_t apiId);
00656 private:
00657     uint8_t _apiId;
00658     uint8_t _frameId;
00659 };
00660 
00661 // TODO add reset/clear method since responses are often reused
00662 /**
00663  * Primary interface for communicating with an XBee Radio.
00664  * This class provides methods for sending and receiving packets with an XBee radio via the serial port.
00665  * The XBee radio must be configured in API (packet) mode (AP=2)
00666  * in order to use this software.
00667  * <p/>
00668  * Since this code is designed to run on a microcontroller, with only one thread, you are responsible for reading the
00669  * data off the serial buffer in a timely manner.  This involves a call to a variant of readPacket(...).
00670  * If your serial port is receiving data faster than you are reading, you can expect to lose packets.
00671  * Arduino only has a 128 byte serial buffer so it can easily overflow if two or more packets arrive
00672  * without a call to readPacket(...)
00673  * <p/>
00674  * In order to conserve resources, this class only supports storing one response packet in memory at a time.
00675  * This means that you must fully consume the packet prior to calling readPacket(...), because calling
00676  * readPacket(...) overwrites the previous response.
00677  * <p/>
00678  * This class creates an array of size MAX_FRAME_DATA_SIZE for storing the response packet.  You may want
00679  * to adjust this value to conserve memory.
00680  *
00681  * \author Andrew Rapp
00682  */
00683 class XBee {
00684 public:
00685     XBee(PinName p_tx, PinName p_rx);
00686     XBee(PinName p_tx, PinName p_rx, PinName p_cts, PinName p_rts);
00687     // for eclipse dev only
00688 //    void setSerial(HardwareSerial serial);
00689     /**
00690      * Reads all available serial bytes until a packet is parsed, an error occurs, or the buffer is empty.
00691      * You may call <i>xbee</i>.getResponse().isAvailable() after calling this method to determine if
00692      * a packet is ready, or <i>xbee</i>.getResponse().isError() to determine if
00693      * a error occurred.
00694      * <p/>
00695      * This method should always return quickly since it does not wait for serial data to arrive.
00696      * You will want to use this method if you are doing other timely stuff in your loop, where
00697      * a delay would cause problems.
00698      * NOTE: calling this method resets the current response, so make sure you first consume the
00699      * current response
00700      */
00701     void readPacket();
00702     /**
00703      * Waits a maximum of <i>timeout</i> milliseconds for a response packet before timing out; returns true if packet is read.
00704      * Returns false if timeout or error occurs.
00705      */
00706     bool readPacket(int timeout);
00707     /**
00708      * Reads until a packet is received or an error occurs.
00709      * Caution: use this carefully since if you don't get a response, your Arduino code will hang on this
00710      * call forever!! often it's better to use a timeout: readPacket(int)
00711      */
00712     void readPacketUntilAvailable();
00713     /**
00714      * Starts the serial connection at the supplied baud rate
00715      */
00716     void begin(long baud);
00717     void getResponse(XBeeResponse &response);
00718     /**
00719      * Returns a reference to the current response
00720      * Note: once readPacket is called again this response will be overwritten!
00721      */
00722     XBeeResponse& getResponse();
00723     /**
00724      * Sends a XBeeRequest (TX packet) out the serial port
00725      */
00726     void send(XBeeRequest &request);
00727     //uint8_t sendAndWaitForResponse(XBeeRequest &request, int timeout);
00728     /**
00729      * Returns a sequential frame id between 1 and 255
00730      */
00731     uint8_t getNextFrameId();
00732     
00733     void isr_recv ();
00734     int getbuf ();
00735     int bufreadable ();
00736 private:
00737     void sendByte(uint8_t b, bool escape);
00738     void resetResponse();
00739     XBeeResponse _response;
00740     bool _escape;
00741     // current packet position for response.  just a state variable for packet parsing and has no relevance for the response otherwise
00742     uint16_t _pos, _epos;
00743     // last byte read
00744     uint8_t b;
00745     uint16_t _checksumTotal;
00746     uint8_t _nextFrameId;
00747     // buffer for incoming RX packets.  holds only the api specific frame data, starting after the api id byte and prior to checksum
00748     uint8_t _responseFrameData[MAX_FRAME_DATA_SIZE];
00749     Serial _xbee;
00750     char _rxbuf[MAX_RXBUF_SIZE];
00751     int _rxaddr_w, _rxaddr_r;
00752     bool _rts;
00753 };
00754 
00755 /**
00756  * All TX packets that support payloads extend this class
00757  */
00758 class PayloadRequest : public XBeeRequest {
00759 public:
00760     PayloadRequest(uint8_t apiId, uint8_t frameId, uint8_t *payload, uint16_t payloadLength);
00761     /**
00762      * Returns the payload of the packet, if not null
00763      */
00764     uint8_t* getPayload();
00765     /**
00766      * Sets the payload array
00767      */
00768     void setPayload(uint8_t* payloadPtr);
00769     /**
00770      * Returns the length of the payload array, as specified by the user.
00771      */
00772     uint16_t getPayloadLength();
00773     /**
00774      * Sets the length of the payload to include in the request.  For example if the payload array
00775      * is 50 bytes and you only want the first 10 to be included in the packet, set the length to 10.
00776      * Length must be <= to the array length.
00777      */
00778     void setPayloadLength(uint16_t payloadLength);
00779 private:
00780     uint8_t* _payloadPtr;
00781     uint16_t _payloadLength;
00782 };
00783 
00784 #ifdef SERIES_1
00785 
00786 /**
00787  * Represents a Series 1 TX packet that corresponds to Api Id: TX_16_REQUEST
00788  * <p/>
00789  * Be careful not to send a data array larger than the max packet size of your radio.
00790  * This class does not perform any validation of packet size and there will be no indication
00791  * if the packet is too large, other than you will not get a TX Status response.
00792  * The datasheet says 100 bytes is the maximum, although that could change in future firmware.
00793  */
00794 class Tx16Request : public PayloadRequest {
00795 public:
00796     Tx16Request(uint16_t addr16, uint8_t option, uint8_t *payload, uint16_t payloadLength, uint8_t frameId);
00797     /**
00798      * Creates a Unicast Tx16Request with the ACK option and DEFAULT_FRAME_ID
00799      */
00800     Tx16Request(uint16_t addr16, uint8_t *payload, uint16_t payloadLength);
00801     /**
00802      * Creates a default instance of this class.  At a minimum you must specify
00803      * a payload, payload length and a destination address before sending this request.
00804      */
00805     Tx16Request();
00806     uint16_t getAddress16();
00807     void setAddress16(uint16_t addr16);
00808     uint8_t getOption();
00809     void setOption(uint8_t option);
00810     virtual uint8_t getFrameData(uint16_t pos);
00811     virtual uint16_t getFrameDataLength();
00812 protected:
00813 private:
00814     uint16_t _addr16;
00815     uint8_t _option;
00816 };
00817 
00818 /**
00819  * Represents a Series 1 TX packet that corresponds to Api Id: TX_64_REQUEST
00820  *
00821  * Be careful not to send a data array larger than the max packet size of your radio.
00822  * This class does not perform any validation of packet size and there will be no indication
00823  * if the packet is too large, other than you will not get a TX Status response.
00824  * The datasheet says 100 bytes is the maximum, although that could change in future firmware.
00825  */
00826 class Tx64Request : public PayloadRequest {
00827 public:
00828     Tx64Request(XBeeAddress64 &addr64, uint8_t option, uint8_t *payload, uint16_t payloadLength, uint8_t frameId);
00829     /**
00830      * Creates a unicast Tx64Request with the ACK option and DEFAULT_FRAME_ID
00831      */
00832     Tx64Request(XBeeAddress64 &addr64, uint8_t *payload, uint16_t payloadLength);
00833     /**
00834      * Creates a default instance of this class.  At a minimum you must specify
00835      * a payload, payload length and a destination address before sending this request.
00836      */
00837     Tx64Request();
00838     XBeeAddress64& getAddress64();
00839     void setAddress64(XBeeAddress64& addr64);
00840     // TODO move option to superclass
00841     uint8_t getOption();
00842     void setOption(uint8_t option);
00843     virtual uint8_t getFrameData(uint16_t pos);
00844     virtual uint16_t getFrameDataLength();
00845 private:
00846     XBeeAddress64 _addr64;
00847     uint8_t _option;
00848 };
00849 
00850 #endif
00851 
00852 
00853 #ifdef SERIES_2
00854 
00855 /**
00856  * Represents a Series 2 TX packet that corresponds to Api Id: ZB_TX_REQUEST
00857  *
00858  * Be careful not to send a data array larger than the max packet size of your radio.
00859  * This class does not perform any validation of packet size and there will be no indication
00860  * if the packet is too large, other than you will not get a TX Status response.
00861  * The datasheet says 72 bytes is the maximum for ZNet firmware and ZB Pro firmware provides
00862  * the ATNP command to get the max supported payload size.  This command is useful since the
00863  * maximum payload size varies according to certain settings, such as encryption.
00864  * ZB Pro firmware provides a PAYLOAD_TOO_LARGE that is returned if payload size
00865  * exceeds the maximum.
00866  */
00867 class ZBTxRequest : public PayloadRequest {
00868 public:
00869     /**
00870      * Creates a unicast ZBTxRequest with the ACK option and DEFAULT_FRAME_ID
00871      */
00872     ZBTxRequest(XBeeAddress64 &addr64, uint8_t *payload, uint16_t payloadLength);
00873     ZBTxRequest(XBeeAddress64 &addr64, uint16_t addr16, uint8_t broadcastRadius, uint8_t option, uint8_t *payload, uint16_t payloadLength, uint8_t frameId);
00874     /**
00875      * Creates a default instance of this class.  At a minimum you must specify
00876      * a payload, payload length and a destination address before sending this request.
00877      */
00878     ZBTxRequest();
00879     XBeeAddress64& getAddress64();
00880     uint16_t getAddress16();
00881     uint8_t getBroadcastRadius();
00882     uint8_t getOption();
00883     void setAddress64(XBeeAddress64& addr64);
00884     void setAddress16(uint16_t addr16);
00885     void setBroadcastRadius(uint8_t broadcastRadius);
00886     void setOption(uint8_t option);
00887 protected:
00888     // declare virtual functions
00889     virtual uint8_t getFrameData(uint16_t pos);
00890     virtual uint16_t getFrameDataLength();
00891 private:
00892     XBeeAddress64 _addr64;
00893     uint16_t _addr16;
00894     uint8_t _broadcastRadius;
00895     uint8_t _option;
00896 };
00897 
00898 #endif
00899 
00900 /**
00901  * Represents an AT Command TX packet
00902  * The command is used to configure the serially connected XBee radio
00903  */
00904 class AtCommandRequest : public XBeeRequest {
00905 public:
00906     AtCommandRequest();
00907     AtCommandRequest(uint8_t *command);
00908     AtCommandRequest(uint8_t *command, uint8_t *commandValue, uint8_t commandValueLength);
00909     virtual uint8_t getFrameData(uint16_t pos);
00910     virtual uint16_t getFrameDataLength();
00911     uint8_t* getCommand();
00912     void setCommand(uint8_t* command);
00913     uint8_t* getCommandValue();
00914     void setCommandValue(uint8_t* command);
00915     uint8_t getCommandValueLength();
00916     void setCommandValueLength(uint8_t length);
00917     /**
00918      * Clears the optional commandValue and commandValueLength so that a query may be sent
00919      */
00920     void clearCommandValue();
00921     //void reset();
00922 private:
00923     uint8_t *_command;
00924     uint8_t *_commandValue;
00925     uint8_t _commandValueLength;
00926 };
00927 
00928 /**
00929  * Represents an Remote AT Command TX packet
00930  * The command is used to configure a remote XBee radio
00931  */
00932 class RemoteAtCommandRequest : public AtCommandRequest {
00933 public:
00934     RemoteAtCommandRequest();
00935     /**
00936      * Creates a RemoteAtCommandRequest with 16-bit address to set a command.
00937      * 64-bit address defaults to broadcast and applyChanges is true.
00938      */
00939     RemoteAtCommandRequest(uint16_t remoteAddress16, uint8_t *command, uint8_t *commandValue, uint8_t commandValueLength);
00940     /**
00941      * Creates a RemoteAtCommandRequest with 16-bit address to query a command.
00942      * 64-bit address defaults to broadcast and applyChanges is true.
00943      */
00944     RemoteAtCommandRequest(uint16_t remoteAddress16, uint8_t *command);
00945     /**
00946      * Creates a RemoteAtCommandRequest with 64-bit address to set a command.
00947      * 16-bit address defaults to broadcast and applyChanges is true.
00948      */
00949     RemoteAtCommandRequest(XBeeAddress64 &remoteAddress64, uint8_t *command, uint8_t *commandValue, uint8_t commandValueLength);
00950     /**
00951      * Creates a RemoteAtCommandRequest with 16-bit address to query a command.
00952      * 16-bit address defaults to broadcast and applyChanges is true.
00953      */
00954     RemoteAtCommandRequest(XBeeAddress64 &remoteAddress64, uint8_t *command);
00955     uint16_t getRemoteAddress16();
00956     void setRemoteAddress16(uint16_t remoteAddress16);
00957     XBeeAddress64& getRemoteAddress64();
00958     void setRemoteAddress64(XBeeAddress64 &remoteAddress64);
00959     bool getApplyChanges();
00960     void setApplyChanges(bool applyChanges);
00961     virtual uint8_t getFrameData(uint16_t pos);
00962     virtual uint16_t getFrameDataLength();
00963     static XBeeAddress64 broadcastAddress64;
00964 //    static uint16_t broadcast16Address;
00965 private:
00966     XBeeAddress64 _remoteAddress64;
00967     uint16_t _remoteAddress16;
00968     bool _applyChanges;
00969 };
00970 
00971 
00972 
00973 #endif //XBee_h