XBee.h

00001 
00002 #ifndef XBEE_H
00003 #define XBEE_H
00004 
00005 #define RX_BUF_SIZE (512)
00006 #define XBEE_BUF_SZ (200)
00007 
00008 #define XBEE_ADDRLO_BROADCAST (0x0000FFFF)
00009 #define XBEE_ADDRHI_BROADCAST (0x00000000)
00010 
00011 /**
00012  * Interface to Digi International's XBee module. The XBee S1 module has
00013  * been used during testing of this interface.
00014  */
00015 class XBee {
00016 public:
00017 
00018     /** Error codes returned from public methods */
00019     enum XBeeError {
00020         Ok = 0,
00021         ReadError = -1,
00022         CmdError = -2,
00023         BufTooSmallError = -3,
00024         TimeOutError = -4,
00025         NotInitializedError = -5,
00026         ArgumentError = -6
00027 
00028     };
00029 
00030     /** Callback function/method types. See registerCallback() */
00031     enum CallbackType {
00032         /** Device is up and ready */
00033         CbDeviceUp = 0,
00034         /** Device is down (disconnected) */
00035         CbDeviceDown,
00036         /** A node has been found */
00037         CbNodeFound,
00038         /** Transmit status */
00039         CbTxStat,
00040         /** Data is available */
00041         CbDataAvailable,
00042         CbNum // must be last
00043 
00044     };
00045 
00046     /** Xbee types */
00047     enum XBeeType {
00048         EndDevice = 0,
00049         Coordinator
00050     };
00051 
00052     /** Transmit status */
00053     enum XBeeTxStatus {
00054         TxStatusOk = 0,
00055         TxStatusNoAck,
00056         TxStatusCCA,
00057         TxStatusPurged
00058     };
00059 
00060     /**
00061      * Create an interface to an XBee module.
00062      *
00063      * @param tx UART TX line
00064      * @param tx UART rx line
00065      * @param reset reset pin
00066      * @param sleep sleep request pin
00067      */
00068     XBee(PinName tx, PinName rx, PinName reset, PinName sleep);
00069 
00070     /**
00071      * Initialize the XBee module and configure it to be of a
00072      * specific type.
00073      *
00074      * Note: This implementation will always configure the XBee module to
00075      * work in API mode.
00076      *
00077      * @param type the type of this XBee node
00078      * @param panId the PAN ID to use for the XBee network. This  argument
00079      * must contain 4 characters representing hexadecimal values
00080      * (e.g. "A1E0" means the hexadecimal value 0xA1E0);
00081      */
00082     XBeeError init(XBeeType type, const char* panId);
00083 
00084     /**
00085      * Register a callback function
00086      *
00087      * @param fptr Callback function to register
00088      * @param type The type of event that will trigger a call to the function.
00089      */
00090     void registerCallback(void (*fptr)(void), CallbackType type) {
00091         if (fptr) {
00092             _callbacks[type].attach(fptr);
00093         }
00094     }
00095 
00096     /**
00097      * Register a callback method
00098      *
00099      * @param tptr pointer to the object to call the member function on
00100      * @param mptr pointer to the member function to be called
00101      * @param type The type of event that will trigger a call to the method.
00102      */
00103     template<typename T>
00104     void registerCallback(T* tptr, void (T::*mptr)(void), CallbackType type) {
00105         if((mptr != NULL) && (tptr != NULL)) {
00106             _callbacks[type].attach(tptr, mptr);
00107         }
00108     }
00109 
00110     /**
00111      * Call this method repeatedly to process incoming data.
00112      */
00113     void process();
00114 
00115     /**
00116      * Get address of remote node. This method will only return valid data
00117      * when called in the context of the CbDataAvailable and CbNodeFound
00118      * callbacks
00119      *
00120      * @param addrHi Top 32 bits of address will be written to this argument
00121      * @param addrLo Bottom 32 bits of address will be written to this argument
00122      */
00123     XBeeError getRemoteAddress(uint32_t* addrHi, uint32_t* addrLo);
00124 
00125     /**
00126      * Get signal strength indicator value (RSSI). This method will only
00127      * return valid data when called in the context of the
00128      * CbDataAvailable and CbNodeFound callbacks
00129      *
00130      * @param rssi RSSI value will be written to this argument
00131      */
00132     XBeeError getRssi(uint8_t* rssi );
00133 
00134     /**
00135      * Get the transmit status. This method will only return valid data when
00136      * called in the context of the CbTxStat callback.
00137      *
00138      * @param frameId the frame ID will be written to this argument
00139      * @param status the status will be written to this argument
00140      */
00141     XBeeError getTxStatus(uint8_t* frameId, XBeeTxStatus* status);
00142 
00143     /**
00144      * Get received data. This method will only return valid data when called
00145      * in the context of the CbDataAvailable callback
00146      *
00147      * @param data will point to a buffer with received data
00148      * @param len will contain the length of the received data
00149      */
00150     XBeeError getData(char** data, uint8_t* len);
00151 
00152     /**
00153      * Send data to a node with specified address. It is also possible to
00154      * broadcast a message using broadcast address (XBEE_ADDRHI_BROADCAST,
00155      * XBEE_ADDRLO_BROADCAST).
00156      *
00157      * @param addrHi Top 32 bits of address
00158      * @param addrLo Bottom 32 bits of address
00159      * @param data buffer containing data to send
00160      * @param len number of bytes to send
00161      * @param frameId the ID of the frame will be written to this argument.
00162      * The ID can then be used to match this request with the status returned
00163      * in the CbTxStat callback.
00164      */
00165     XBeeError send(uint32_t addrHi, uint32_t addrLo, char* data,
00166         uint8_t len, uint8_t* frameId);
00167 
00168     /**
00169      * Send a Node Discover request. All modules on the operating channel and
00170      * PAN ID should respond. The responses will be reported in the CbNodeFound
00171      * callback.
00172      */
00173     XBeeError discoverNodes();
00174 
00175     /**
00176      * Request the module to enter sleep mode.
00177      */
00178     XBeeError enterSleep();
00179 
00180     /**
00181      * Request the module to exit sleep mode.
00182      */
00183     XBeeError exitSleep();
00184 
00185 
00186 protected:
00187 
00188 
00189 private:
00190 
00191     enum RfState {
00192         RfStateFrame = 0,
00193         RfStateLength,
00194         RfStateData
00195     };
00196 
00197 
00198     bool _initialized;
00199     Serial _serial;
00200     XBeeType _type;
00201     DigitalOut _reset;
00202     DigitalOut _sleep;
00203 
00204     uint8_t rxqIn;
00205     uint8_t rxqOut;
00206     uint8_t rxq[RX_BUF_SIZE];
00207 
00208     uint32_t _rfFrameTimeout;
00209     Timer _rfFrameTimer;
00210 
00211     RfState _rfState;
00212     uint32_t _rfPos;
00213     uint32_t _rfFrameLen;
00214     char _rfBuf[XBEE_BUF_SZ];
00215     uint8_t _rfFrameId;
00216 
00217     uint32_t _addrHi;
00218     uint32_t _addrLo;
00219     uint8_t _rssi;
00220     uint8_t _frameId;
00221     XBeeTxStatus _txStatus;
00222     char* _recvData;
00223     uint8_t _recvLen;
00224 
00225 
00226     FunctionPointer _callbacks[CbNum];
00227 
00228 
00229     void uartRxIrq();
00230     void uartRxQPut(uint8_t data);
00231     uint8_t uartRxQGet();
00232     bool uartRxQIsEmpty();
00233     uint32_t uartReceive(char *buf, uint32_t buflen);
00234     int32_t uartReadLine(char* buf, uint32_t bufLen, uint32_t timeout);
00235 
00236     void resetModule();
00237     XBeeError commandMode();
00238     XBeeError atGet(const char* atCmd, char* resp, uint32_t respLen);
00239     XBeeError atSet(const char* atCmd);
00240 
00241     void processByte(char data);
00242     void processFrame(char* buf, uint32_t len);
00243 
00244     void handleAtResponse(uint8_t frameId, char* atBuf, uint8_t status,
00245         char* valueBuf, uint32_t valueLen);
00246 
00247     void handleDiscovery(uint8_t status, char* buf, uint32_t len);
00248     void handleTxStatus(uint8_t frameId, uint8_t status);
00249     void processData(uint32_t addrHi, uint32_t addrLo, uint8_t rssi,
00250         uint8_t opt, char* buf, uint32_t len);
00251     void handleModemStatus(uint8_t status);
00252 
00253     char checksum(char* buf, uint32_t len);
00254     uint32_t bufTo32bitInt(const char* buf);
00255     void int32bitToBuf(uint32_t v, char* buf);
00256 
00257     XBeeError apiTx64(uint32_t addrHi, uint32_t addrLo, char* data,
00258         uint32_t len, uint8_t* frameId);
00259     XBeeError apiAtCmd(const char* atCmd, uint32_t param, bool useParameter);
00260 
00261     uint8_t getFrameId();
00262 
00263 
00264 };
00265 
00266 #endif