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