XBee.h

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