XBee.h

00001 /*
00002 Copyright (c) 2011, Senio Networks, Inc.
00003 
00004 Permission is hereby granted, free of charge, to any person obtaining a copy
00005 of this software and associated documentation files (the "Software"), to deal
00006 in the Software without restriction, including without limitation the rights
00007 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008 copies of the Software, and to permit persons to whom the Software is
00009 furnished to do so, subject to the following conditions:
00010 
00011 The above copyright notice and this permission notice shall be included in
00012 all copies or substantial portions of the Software.
00013 
00014 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00020 THE SOFTWARE.
00021 */
00022 
00023 #ifndef XBEE_H
00024 #define XBEE_H
00025 
00026 #include "mbed.h"
00027 #include "XBeeDataTypes.h"
00028 
00029 #define min(x, y)       ((x) < (y) ? (x) : (y))
00030 #define INDEX(n)        ((n) % BUFSIZE)
00031 #define SIZE(b, i)      (b[i] << 8 | b[INDEX(i + 1)])
00032 
00033 const int BUFSIZE = 512;
00034 const char ESCAPE = 0x7D;
00035 const char PREAMBLE = 0x7E;
00036 
00037 /**
00038  * class for XBee module API mode interface
00039  */
00040 class XBee : public Serial {
00041 public:
00042 
00043     /**
00044      * Frame type declaration for XBee API frames
00045      */
00046     enum FrameType {
00047         /**
00048         * Empty data
00049         */
00050         None = 0,
00051         
00052         /**
00053          *  AT Command Response API frame
00054          */
00055         ATCommandResponse,
00056         
00057         /**
00058          * Modem Status API frame
00059          */
00060         ModemStatus,
00061         
00062         /**
00063          * ZigBee Transmit Status API frame
00064          */
00065         ZigBeeTransmitStatus,
00066         
00067         /**
00068          * ZigBee Receive Packet API frame
00069          */
00070         ZigBeeReceivePacket,
00071 
00072         /**
00073          *  ZigBee Explicit Rx Indicator API frame
00074          */
00075         ZigBeeExplicitRxIndicator,
00076 
00077         /**
00078          * ZigBee I/O Data Sample Rx Indicator API frame
00079          */
00080         ZigBeeIODataSampleRxIndicator,
00081 
00082         /**
00083          * XBee Sensor Read Indicator API frame
00084          */
00085         XBeeSensorReadIndicator,
00086 
00087         /**
00088          * Node Identification Indicator API frame
00089          */
00090         NodeIdentificationIndicator,
00091 
00092         /**
00093          * Remote Command Response API frame
00094          */
00095         RemoteCommandResponse,
00096 
00097         /**
00098          * Unknown API frame
00099          */
00100         Other
00101     };
00102     
00103     /**
00104      * Value type declarations for retrieving frame data contents
00105      */
00106     enum ValueType {
00107         /**
00108          * Frame ID
00109          */
00110         FrameID,
00111         
00112         /**
00113          *AT command name
00114          */
00115         ATCommand,
00116         
00117         /**
00118          * Status
00119          */       
00120         Status,
00121         
00122         /**
00123          * Command data
00124          */
00125         CommandData,
00126         
00127         /**
00128          * 16 bit address
00129          */
00130         Address16,
00131         
00132         /**
00133          * 64 bit address
00134          */
00135         Address64,
00136         
00137         /**
00138          * Retry count
00139          */
00140         RetryCount,
00141         
00142         /**
00143          * Delivery status
00144          */
00145         DeliveryStatus,
00146         
00147         /**
00148          * Discovery status
00149          */
00150         DiscoveryStatus,
00151         
00152         /**
00153          * Receive option
00154          */
00155         ReceiveOptions,
00156         
00157         /**
00158          * Received data
00159          */
00160         ReceivedData,
00161         
00162         /**
00163          * Raw data
00164          */
00165         RawData
00166     };
00167 
00168 
00169     /**
00170      * creates an XBee interface object.
00171      *
00172      * @param ser Serial object through which XBee module is connected to mbed
00173      * @param apiMode API mode either 1 or 2 (use escape; default)
00174      * @param debug display debugging (I/O state) information through LEDs
00175      */
00176     XBee(Serial& ser, int apiMode = 2, bool debug = false);
00177 
00178 
00179     /**
00180      * creates an XBee interface object.
00181      *
00182      * @param tx TX pin connected to XBee
00183      * @param rx RX pin connected to XBee
00184      * @param apiMode API mode either 1 or 2 (use escape; default)
00185      * @param debug display debugging (I/O state) information through LEDs
00186      */
00187     XBee(PinName tx, PinName rx, int apiMode = 2, bool debug = false);
00188 
00189     /**
00190      * creates an XBee interface object.
00191      *
00192      * @param ser Serial object through which XBee module is connected to mbed
00193      * @param mon alternate Serial object for monitoring (use serial ports other than USBTX/USBRX)
00194      * @param apiMode API mode either 1 or 2 (use escape; default)
00195      * @param debug display debugging (I/O state) information through LEDs
00196      */
00197     XBee(Serial& ser, Serial& mon, int apiMode = 2, bool debug = false);
00198 
00199     /**
00200      * creates an XBee interface object.
00201      *
00202      * @param tx TX pin connected to XBee
00203      * @param rx RX pin connected to XBee
00204      * @param mon alternate Serial object for monitoring (use serial ports other than USBTX/USBRX)
00205      * @param apiMode API mode either 1 or 2 (use escape; default)
00206      * @param debug display debugging (I/O state) information through LEDs
00207      */
00208     XBee(PinName tx, PinName rx, Serial& mon, int apiMode = 2, bool debug = false);
00209     
00210     /**
00211      * initializes XBee module.
00212      *
00213      * issues VR command to test XBee modem connection
00214      *
00215      * @returns true if initialization succeeded, false otherwise
00216      */
00217     bool init(float timeout = 15.0);
00218 
00219     /**
00220      * sets destination addresses.
00221      *
00222      * @param address64 XBeeAddress64 type address
00223      * @param address16 XBeeAddress16 type address (optional)
00224      */
00225     void setDestination(XBeeAddress64 address64, XBeeAddress16 address16 = 0xFFFE);
00226     
00227     /**
00228      * sets destination addresses.
00229      *
00230      * @param address64 64-bit destination address in uint64_t
00231      * @param address16 16-bit destination address in uint16_t
00232      */
00233     void setDestination(uint64_t address64, uint16_t address16 = 0xFFFE);
00234 
00235     /**
00236       * sets destination addresses.
00237       *
00238       * @param address64 64-bit destination address in bytes (big endian)
00239       * @param address16 16-bit destination address in bytes
00240       */
00241     void setDestination(char address64[], char address16[]);
00242     
00243     /**
00244      * sends an AT command.
00245      *
00246      * @param command AT command char string
00247      * @param param parameter to the AT command
00248      */
00249     void sendCommand(const char *command, int8_t param, bool queue = false);
00250     void sendCommand(const char *command, int16_t param, bool queue = false);
00251     void sendCommand(const char *command, int32_t param, bool queue = false);
00252     void sendCommand(const char *command, int64_t param, bool queue = false);
00253     void sendCommand(const char *command, uint8_t param, bool queue = false);
00254     void sendCommand(const char *command, uint16_t param, bool queue = false);
00255     void sendCommand(const char *command, uint32_t param, bool queue = false);
00256     void sendCommand(const char *command, uint64_t param, bool queue = false);
00257     void sendCommand(const char *command, const char *param, bool queue = false);
00258     
00259     /**
00260      * sends an AT command.
00261      *
00262      * @param command AT command char string
00263      * @param param parameter to the AT command (pointer to byte array)
00264      * @param param_length parameter length in bytes
00265      * @param queue true if command paramter is to be queued
00266      */
00267     void sendCommand(const char *command, const uint8_t *param = 0, int param_length = 0, bool queue = false);
00268 
00269     /**
00270      * sends a remote AT command.
00271      *
00272      * sends an AT command to the XBee(s) at the destination address
00273      *
00274      * @param command AT command char string
00275      * @param param parameter to the AT command (pointer to byte array)
00276      * @param param_length parameter length in bytes
00277      * @param options remote command options
00278      */
00279     void sendRemoteCommand(const char *command, int8_t param);
00280     void sendRemoteCommand(const char *command, int16_t param);
00281     void sendRemoteCommand(const char *command, int32_t param);
00282     void sendRemoteCommand(const char *command, int64_t param);
00283     void sendRemoteCommand(const char *command, uint8_t param);
00284     void sendRemoteCommand(const char *command, uint16_t param);
00285     void sendRemoteCommand(const char *command, uint32_t param);
00286     void sendRemoteCommand(const char *command, uint64_t param);
00287     void sendRemoteCommand(const char *command, const char *param);
00288     
00289     /**
00290      * sends a remote AT command.
00291      *
00292      * sends an AT command to the XBee(s) at the destination address
00293      *
00294      * @param command AT command char string
00295      * @param param parameter to the AT command (pointer to byte array)
00296      * @param param_length parameter length in bytes
00297      * @param options remote command options
00298      */
00299     void sendRemoteCommand(const char *command, const uint8_t *param = 0, int param_length = 0, char options = 0x02);
00300 
00301     /**
00302      * executes an AT command and gets the result.
00303      *
00304      * @param command AT command char string
00305      * @param param parameter to the AT command
00306      *
00307      * @returns pointer to the command result, if the result is a number (char, short, long, int64_t),
00308      *          the address to the number will be returned; otherwise the address to the byte array
00309      *          containing the command response will be returned.
00310      */
00311     void *executeCommand(const char *command, int8_t param);
00312     void *executeCommand(const char *command, int16_t param);
00313     void *executeCommand(const char *command, int32_t param);
00314     void *executeCommand(const char *command, int64_t param);
00315     void *executeCommand(const char *command, uint8_t param);
00316     void *executeCommand(const char *command, uint16_t param);
00317     void *executeCommand(const char *command, uint32_t param);
00318     void *executeCommand(const char *command, uint64_t param);
00319     void *executeCommand(const char *command, const char *param);
00320 
00321     /**
00322      * executes an AT command and gets the result.
00323      *
00324      * @param command AT command char string
00325      * @param param parameter to the AT command (pointer to byte array)
00326      * @param param_length parameter length in bytes
00327      *
00328      * @returns pointer to the command result, if the result is a number (char, short, long, long long),
00329      *          the address to the number will be returned; otherwise the address to the byte array
00330      *          containing the command response will be returned.
00331      */
00332     void *executeCommand(const char *command, const uint8_t *param = 0, int laram_length = 0);
00333 
00334     /**
00335      * sends data to the XBee(s) at the destination address.
00336      *
00337      * @param data address to the data (byte array)
00338      * @param length data length in bytes
00339      * @param confirm if true, checks the transmission status frame and returns the result
00340      */
00341     bool send(const char *data, int length, bool confirm);
00342 
00343     /**
00344      * sends data and confirm the transmit status.
00345      *
00346      * @param data address to the data (byte array)
00347      * @param length data length in bytes
00348      *
00349      * @returns true if sent successfully, false otherwise (either timeout or send error occurred)
00350      */
00351     bool sendConfirm(const char *data, int length);
00352 
00353     /**
00354      * sends data to the destination using printf format.
00355      *
00356      * @param format printf format string, followed by corresponding arguments
00357      *
00358      * @returns the number of charancters sent, or negative if error occurred
00359      */
00360     int printf(const char *format, ...);
00361 
00362     /**
00363      * receives data frame from the XBee module.
00364      *
00365      * @param timeout seconds bofer time out
00366      *
00367      * @returns FrameType of the received frame data
00368      */
00369     FrameType receive(float timeout = 3.0);
00370 
00371     /**
00372      * scan received data
00373      *
00374      * @param data XBeeDataType data to be scanned
00375      *
00376      * @param true if scan succeeded, false otherwise
00377      */
00378     bool scan(XBeeFrameID& id) { return scan(XBee::FrameID, id.raw_address(), 1); }
00379     bool scan(XBeeRetryCount& count) { return scan(XBee::RetryCount, count.raw_address(), 1); }
00380     bool scan(XBeeStatus& status) { return scan(XBee::Status, status.raw_address(), 1); }
00381     bool scan(XBeeDeliveryStatus& status) { return scan(XBee::DeliveryStatus, status.raw_address(), 1); }
00382     bool scan(XBeeDiscoveryStatus& status) { return scan(XBee::DiscoveryStatus, status.raw_address(), 1); }
00383     bool scan(XBeeReceiveOptions& options) { return scan(XBee::ReceiveOptions, options.raw_address(), 1); }
00384     bool scan(XBeeAddress64& address64) { return scan(XBee::Address64, address64.raw_address(), 8); }
00385     bool scan(XBeeAddress16& address16) { return scan(XBee::Address16, address16.raw_address(), 2); }
00386     bool scan(XBeeATCommand& command) { return scan(XBee::ATCommand, command.raw_address(), 3); }
00387     bool scan(XBeeCommandData& data) { return scan(XBee::CommandData, data.raw_address(), data.capacity, &data.size); }
00388     bool scan(XBeeReceivedData& data) { return scan(XBee::ReceivedData, data.raw_address(), data.capacity, &data.size); }
00389     bool scan(XBeeRawData& data) { return scan(XBee::RawData, data.raw_address(), data.capacity, &data.size); }
00390     
00391     /**
00392      * scan received data according to the specified format.
00393      *
00394      * @param type ValueType of the data to be scanned
00395      * @param value pointer to the byte array to store the scanned value
00396      * @param maxlength max size of the value in bytes
00397      * @param length pointer to an int to receive the actual data length
00398      *
00399      * @param true if scan succeeded, false otherwise
00400      */
00401     bool scan(ValueType type, char *value, int maxlength = 1, int *length = 0);
00402 
00403     /**
00404      * gets the XBee firmware version.
00405      *
00406      * @returns XBee firmwre version in int (unsigned short value)
00407      */
00408     int getFirmwareVersion();
00409 
00410     /**
00411      * gets the current frame ID.
00412      *
00413      * @returns frame ID number being used in the next send request
00414      */
00415     char getFrameID();
00416 
00417     /**
00418     * sets to run in debug mode.
00419     *
00420     * @param debug true to display debugging information
00421     */
00422     void setDebug(bool debug);
00423 
00424     /**
00425     * displays received data in dump format.
00426     */
00427     void dump();
00428 
00429     /**
00430      * displays the internal data fields and receive buffer in dump format.
00431      */
00432     void dumpAll();
00433 
00434     /**
00435      * operator overloading for testing XBee modem connection status.
00436      *
00437      * @returns false if XBee modem connection has an error
00438      */
00439     operator bool();
00440 
00441 private:
00442     Serial mon;
00443     BusOut leds;
00444     int apiMode;
00445     volatile enum {UNKNOWN, LENGTH1, LENGTH2, DATA, SUMCHECK} state;
00446     volatile int cur, in, out, received, free;
00447     char frame_id;
00448     char destination64[8];
00449     char destination16[2];
00450     char buf[BUFSIZE];
00451     bool debug;
00452 
00453     void send(char c);
00454     void send2(char c);
00455     void sendFrame(const char *frame, int length);
00456     int createTxRequest(char frame_id, const char *data, int data_length, char *buf, int buf_size);
00457     int createAtRequest(char frame_id, const char *command, const uint8_t *param, int param_length, bool queue, char *buf, int buf_size);
00458     int createRemoteAtRequest(char frame_id, const char *command, const uint8_t *param, int param_length, char options, char *buf, int buf_size);
00459     int seekFor(FrameType type, float timeout);
00460     FrameType getFrameType(char c);
00461     bool scan(int i, ValueType type, char *value, int maxlength = 1, int *length = 0);
00462     void flush();
00463     void rxInterruptHandler();
00464     void rxInterruptHandler2();
00465 
00466     void dump(const char *data, int length);
00467     void dumpIOSample(const char *data, int length);
00468     void copy(char *toBuf, int fromIndex, int length);
00469 };
00470 
00471 #endif