Hiroshi Yamaguchi / XBee 1.0

XBee API mode library 1.0

XBee.h@0:ea8459db49ef, 2011-11-01 (annotated)

Committer:
yamaguch
Date:
Tue Nov 01 09:04:12 2011 +0000
Revision:
0:ea8459db49ef
Child:
1:58a1c083cf8d
0.9

Who changed what in which revision?

UserRevisionLine numberNew contents of line
yamaguch 0:ea8459db49ef 1 /*
yamaguch 0:ea8459db49ef 2 Copyright (c) 2011, Senio Networks, Inc.
yamaguch 0:ea8459db49ef 3
yamaguch 0:ea8459db49ef 4 Permission is hereby granted, free of charge, to any person obtaining a copy
yamaguch 0:ea8459db49ef 5 of this software and associated documentation files (the "Software"), to deal
yamaguch 0:ea8459db49ef 6 in the Software without restriction, including without limitation the rights
yamaguch 0:ea8459db49ef 7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
yamaguch 0:ea8459db49ef 8 copies of the Software, and to permit persons to whom the Software is
yamaguch 0:ea8459db49ef 9 furnished to do so, subject to the following conditions:
yamaguch 0:ea8459db49ef 10
yamaguch 0:ea8459db49ef 11 The above copyright notice and this permission notice shall be included in
yamaguch 0:ea8459db49ef 12 all copies or substantial portions of the Software.
yamaguch 0:ea8459db49ef 13
yamaguch 0:ea8459db49ef 14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
yamaguch 0:ea8459db49ef 15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
yamaguch 0:ea8459db49ef 16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
yamaguch 0:ea8459db49ef 17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
yamaguch 0:ea8459db49ef 18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
yamaguch 0:ea8459db49ef 19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
yamaguch 0:ea8459db49ef 20 THE SOFTWARE.
yamaguch 0:ea8459db49ef 21 */
yamaguch 0:ea8459db49ef 22
yamaguch 0:ea8459db49ef 23 #ifndef XBEE_H
yamaguch 0:ea8459db49ef 24 #define XBEE_H
yamaguch 0:ea8459db49ef 25
yamaguch 0:ea8459db49ef 26 #include "mbed.h"
yamaguch 0:ea8459db49ef 27 #include "IOSample.h"
yamaguch 0:ea8459db49ef 28
yamaguch 0:ea8459db49ef 29 const int BUFSIZE = 512;
yamaguch 0:ea8459db49ef 30 const char ESCAPE = 0x7D;
yamaguch 0:ea8459db49ef 31 const char PREAMBLE = 0x7E;
yamaguch 0:ea8459db49ef 32
yamaguch 0:ea8459db49ef 33 /**
yamaguch 0:ea8459db49ef 34 * class for XBee module API mode interface
yamaguch 0:ea8459db49ef 35 */
yamaguch 0:ea8459db49ef 36 class XBee : public Serial {
yamaguch 0:ea8459db49ef 37 public:
yamaguch 0:ea8459db49ef 38 /***/
yamaguch 0:ea8459db49ef 39 enum FrameType {
yamaguch 0:ea8459db49ef 40 None = 0,
yamaguch 0:ea8459db49ef 41 ATCommandResponse,
yamaguch 0:ea8459db49ef 42 ModemStatus,
yamaguch 0:ea8459db49ef 43 ZigBeeTransmitStatus,
yamaguch 0:ea8459db49ef 44 ZigBeeReceivePacket,
yamaguch 0:ea8459db49ef 45 ZigBeeExplicitRxIndicator,
yamaguch 0:ea8459db49ef 46 ZigBeeIODataSampleRxIndicator,
yamaguch 0:ea8459db49ef 47 XBeeSensorReadIndicator,
yamaguch 0:ea8459db49ef 48 NodeIdentificationIndicator,
yamaguch 0:ea8459db49ef 49 RemoteCommandResponse,
yamaguch 0:ea8459db49ef 50 Other
yamaguch 0:ea8459db49ef 51 };
yamaguch 0:ea8459db49ef 52 /***/
yamaguch 0:ea8459db49ef 53 enum ValueType {
yamaguch 0:ea8459db49ef 54 FrameID,
yamaguch 0:ea8459db49ef 55 ATCommand,
yamaguch 0:ea8459db49ef 56 Status,
yamaguch 0:ea8459db49ef 57 CommandData,
yamaguch 0:ea8459db49ef 58 Address16,
yamaguch 0:ea8459db49ef 59 Address64,
yamaguch 0:ea8459db49ef 60 RetryCount,
yamaguch 0:ea8459db49ef 61 DeliveryStatus,
yamaguch 0:ea8459db49ef 62 DiscoveryStatus,
yamaguch 0:ea8459db49ef 63 ReceiveOptions,
yamaguch 0:ea8459db49ef 64 ReceivedData,
yamaguch 0:ea8459db49ef 65 RawData
yamaguch 0:ea8459db49ef 66 };
yamaguch 0:ea8459db49ef 67
yamaguch 0:ea8459db49ef 68 /**
yamaguch 0:ea8459db49ef 69 * creates an XBee interface object.
yamaguch 0:ea8459db49ef 70 *
yamaguch 0:ea8459db49ef 71 * @param ser Serial object through which XBee module is connected to mbed
yamaguch 0:ea8459db49ef 72 * @param apiMode API mode either 1 or 2 (use escape; default)
yamaguch 0:ea8459db49ef 73 * @param debug display debugging (I/O state) information through LEDs
yamaguch 0:ea8459db49ef 74 */
yamaguch 0:ea8459db49ef 75 XBee(Serial& ser, int apiMode = 2, bool debug = false);
yamaguch 0:ea8459db49ef 76
yamaguch 0:ea8459db49ef 77 /**
yamaguch 0:ea8459db49ef 78 * creates an XBee interface object.
yamaguch 0:ea8459db49ef 79 *
yamaguch 0:ea8459db49ef 80 * @param ser Serial object through which XBee module is connected to mbed
yamaguch 0:ea8459db49ef 81 * @param mon alternate Serial object for monitoring (use serial ports other than USBTX/USBRX)
yamaguch 0:ea8459db49ef 82 * @param apiMode API mode either 1 or 2 (use escape; default)
yamaguch 0:ea8459db49ef 83 * @param debug display debugging (I/O state) information through LEDs
yamaguch 0:ea8459db49ef 84 */
yamaguch 0:ea8459db49ef 85 XBee(Serial& ser, Serial& mon, int apiMode = 2, bool debug = false);
yamaguch 0:ea8459db49ef 86
yamaguch 0:ea8459db49ef 87 /**
yamaguch 0:ea8459db49ef 88 * initializes XBee module.
yamaguch 0:ea8459db49ef 89 *
yamaguch 0:ea8459db49ef 90 * issues VR command to test XBee modem connection
yamaguch 0:ea8459db49ef 91 *
yamaguch 0:ea8459db49ef 92 * @returns true if initialization succeeded, false otherwise
yamaguch 0:ea8459db49ef 93 */
yamaguch 0:ea8459db49ef 94 bool init(float timeout = 15.0);
yamaguch 0:ea8459db49ef 95
yamaguch 0:ea8459db49ef 96 /**
yamaguch 0:ea8459db49ef 97 * sets destination addresses.
yamaguch 0:ea8459db49ef 98 *
yamaguch 0:ea8459db49ef 99 * @param address64 64-bit destination address in unsigned long long
yamaguch 0:ea8459db49ef 100 * @param address16 16-bit destination address in unsigned short
yamaguch 0:ea8459db49ef 101 */
yamaguch 0:ea8459db49ef 102 void setDestination(unsigned long long address64, unsigned short address16 = 0xFFFE);
yamaguch 0:ea8459db49ef 103
yamaguch 0:ea8459db49ef 104 /**
yamaguch 0:ea8459db49ef 105 * sets destination addresses.
yamaguch 0:ea8459db49ef 106 *
yamaguch 0:ea8459db49ef 107 * @param address64 64-bit destination address in bytes (big endian)
yamaguch 0:ea8459db49ef 108 * @param address16 16-bit destination address in bytes
yamaguch 0:ea8459db49ef 109 */
yamaguch 0:ea8459db49ef 110 void setDestination(char address64[], char address16[]);
yamaguch 0:ea8459db49ef 111
yamaguch 0:ea8459db49ef 112 /**
yamaguch 0:ea8459db49ef 113 * sets 64-bit destination address.
yamaguch 0:ea8459db49ef 114 *
yamaguch 0:ea8459db49ef 115 * this function is used when 16-bit address is unknown
yamaguch 0:ea8459db49ef 116 * @param address64 64-bit destination address in bytes (big endian)
yamaguch 0:ea8459db49ef 117 */
yamaguch 0:ea8459db49ef 118 void setDestination(char address64[]);
yamaguch 0:ea8459db49ef 119
yamaguch 0:ea8459db49ef 120 /**
yamaguch 0:ea8459db49ef 121 * sends an AT command.
yamaguch 0:ea8459db49ef 122 *
yamaguch 0:ea8459db49ef 123 * @param command AT command char string
yamaguch 0:ea8459db49ef 124 * @param param parameter to the AT command (pointer to byte array)
yamaguch 0:ea8459db49ef 125 * @param param_length parameter length in bytes
yamaguch 0:ea8459db49ef 126 * @param queue true if command paramter is to be queued
yamaguch 0:ea8459db49ef 127 */
yamaguch 0:ea8459db49ef 128 void sendCommand(char* command, char* param = 0, int param_length = 0, bool queue = false);
yamaguch 0:ea8459db49ef 129
yamaguch 0:ea8459db49ef 130 /**
yamaguch 0:ea8459db49ef 131 * sends a remote AT command.
yamaguch 0:ea8459db49ef 132 *
yamaguch 0:ea8459db49ef 133 * sends an AT command to the XBee(s) at the destination address
yamaguch 0:ea8459db49ef 134 *
yamaguch 0:ea8459db49ef 135 * @param command AT command char string
yamaguch 0:ea8459db49ef 136 * @param param parameter to the AT command (pointer to byte array)
yamaguch 0:ea8459db49ef 137 * @param param_length parameter length in bytes
yamaguch 0:ea8459db49ef 138 * @param options remote command options
yamaguch 0:ea8459db49ef 139 */
yamaguch 0:ea8459db49ef 140 void sendRemoteCommand(char* command, char* param = 0, int param_length = 0, char options = 0x02);
yamaguch 0:ea8459db49ef 141
yamaguch 0:ea8459db49ef 142
yamaguch 0:ea8459db49ef 143 /**
yamaguch 0:ea8459db49ef 144 * executes an AT command then gets its result.
yamaguch 0:ea8459db49ef 145 *
yamaguch 0:ea8459db49ef 146 * @param command AT command char string
yamaguch 0:ea8459db49ef 147 * @param param parameter to the AT command (pointer to byte array)
yamaguch 0:ea8459db49ef 148 * @param param_length parameter length in bytes
yamaguch 0:ea8459db49ef 149 *
yamaguch 0:ea8459db49ef 150 * @returns pointer to the command result, if the result is a number (char, short, long, long long),
yamaguch 0:ea8459db49ef 151 * the address to the number will be returned; otherwise the address to the byte array
yamaguch 0:ea8459db49ef 152 * containing the command response will be returned.
yamaguch 0:ea8459db49ef 153 */
yamaguch 0:ea8459db49ef 154 void *executeCommand(char *command, char* param = 0, int laram_length = 0);
yamaguch 0:ea8459db49ef 155
yamaguch 0:ea8459db49ef 156 /**
yamaguch 0:ea8459db49ef 157 * sends data to the XBee(s) at the destination address.
yamaguch 0:ea8459db49ef 158 *
yamaguch 0:ea8459db49ef 159 * @param data address to the data (byte array)
yamaguch 0:ea8459db49ef 160 * @param length data length in bytes
yamaguch 0:ea8459db49ef 161 */
yamaguch 0:ea8459db49ef 162 void send(char *data, int length);
yamaguch 0:ea8459db49ef 163
yamaguch 0:ea8459db49ef 164 /**
yamaguch 0:ea8459db49ef 165 * sends data and confirm the transmit status.
yamaguch 0:ea8459db49ef 166 *
yamaguch 0:ea8459db49ef 167 * @param data address to the data (byte array)
yamaguch 0:ea8459db49ef 168 * @param length data length in bytes
yamaguch 0:ea8459db49ef 169 *
yamaguch 0:ea8459db49ef 170 * @returns true if sent successfully, false otherwise (either timeout or send error occurred)
yamaguch 0:ea8459db49ef 171 */
yamaguch 0:ea8459db49ef 172 bool sendConfirm(char *data, int length);
yamaguch 0:ea8459db49ef 173
yamaguch 0:ea8459db49ef 174 /**
yamaguch 0:ea8459db49ef 175 * sends data to the destination using printf format.
yamaguch 0:ea8459db49ef 176 *
yamaguch 0:ea8459db49ef 177 * @param format printf format string, followed by corresponding arguments
yamaguch 0:ea8459db49ef 178 *
yamaguch 0:ea8459db49ef 179 * @returns the number of charancters sent, or negative if error occurred
yamaguch 0:ea8459db49ef 180 */
yamaguch 0:ea8459db49ef 181 int printf(const char *format, ...);
yamaguch 0:ea8459db49ef 182
yamaguch 0:ea8459db49ef 183 /**
yamaguch 0:ea8459db49ef 184 * receives data frame from the XBee module.
yamaguch 0:ea8459db49ef 185 *
yamaguch 0:ea8459db49ef 186 * @param timeout seconds bofer time out
yamaguch 0:ea8459db49ef 187 *
yamaguch 0:ea8459db49ef 188 * @returns FrameType of the received frame data
yamaguch 0:ea8459db49ef 189 */
yamaguch 0:ea8459db49ef 190 FrameType receive(float timeout = 3.0);
yamaguch 0:ea8459db49ef 191
yamaguch 0:ea8459db49ef 192 /**
yamaguch 0:ea8459db49ef 193 * scan received data according to the specified format.
yamaguch 0:ea8459db49ef 194 *
yamaguch 0:ea8459db49ef 195 * @param type ValueType of the data to be scanned
yamaguch 0:ea8459db49ef 196 * @param value pointer to the byte array to store the scanned value
yamaguch 0:ea8459db49ef 197 * @param maxlength max size of the value in bytes
yamaguch 0:ea8459db49ef 198 * @param length pointer to an int to receive the actual data length
yamaguch 0:ea8459db49ef 199 *
yamaguch 0:ea8459db49ef 200 * @param true if scan succeeded, false otherwise
yamaguch 0:ea8459db49ef 201 */
yamaguch 0:ea8459db49ef 202 bool scan(ValueType type, char *value, int maxlength = 1, int *length = 0);
yamaguch 0:ea8459db49ef 203
yamaguch 0:ea8459db49ef 204 /**
yamaguch 0:ea8459db49ef 205 * gets the XBee firmware version.
yamaguch 0:ea8459db49ef 206 *
yamaguch 0:ea8459db49ef 207 * @returns XBee firmwre version in int (unsigned short value)
yamaguch 0:ea8459db49ef 208 */
yamaguch 0:ea8459db49ef 209 int getFirmwareVersion();
yamaguch 0:ea8459db49ef 210
yamaguch 0:ea8459db49ef 211 /**
yamaguch 0:ea8459db49ef 212 * gets the current frame ID.
yamaguch 0:ea8459db49ef 213 *
yamaguch 0:ea8459db49ef 214 * @returns frame ID number being used in the next send request
yamaguch 0:ea8459db49ef 215 */
yamaguch 0:ea8459db49ef 216 char getFrameID();
yamaguch 0:ea8459db49ef 217
yamaguch 0:ea8459db49ef 218 /**
yamaguch 0:ea8459db49ef 219 * sets to run in debug mode.
yamaguch 0:ea8459db49ef 220 *
yamaguch 0:ea8459db49ef 221 * @param debug true to display debugging information
yamaguch 0:ea8459db49ef 222 */
yamaguch 0:ea8459db49ef 223 void setDebug(bool debug);
yamaguch 0:ea8459db49ef 224
yamaguch 0:ea8459db49ef 225 /**
yamaguch 0:ea8459db49ef 226 * displays received data in dump format.
yamaguch 0:ea8459db49ef 227 */
yamaguch 0:ea8459db49ef 228 void dump();
yamaguch 0:ea8459db49ef 229
yamaguch 0:ea8459db49ef 230 /**
yamaguch 0:ea8459db49ef 231 * displays the internal data fields and receive buffer in dump format.
yamaguch 0:ea8459db49ef 232 */
yamaguch 0:ea8459db49ef 233 void dumpAll();
yamaguch 0:ea8459db49ef 234
yamaguch 0:ea8459db49ef 235 /**
yamaguch 0:ea8459db49ef 236 * operator overloading for testing XBee modem connection status.
yamaguch 0:ea8459db49ef 237 *
yamaguch 0:ea8459db49ef 238 * @returns false if XBee modem connection has an error
yamaguch 0:ea8459db49ef 239 */
yamaguch 0:ea8459db49ef 240 operator bool();
yamaguch 0:ea8459db49ef 241
yamaguch 0:ea8459db49ef 242 private:
yamaguch 0:ea8459db49ef 243 Serial mon;
yamaguch 0:ea8459db49ef 244 BusOut leds;
yamaguch 0:ea8459db49ef 245 int apiMode;
yamaguch 0:ea8459db49ef 246 volatile enum {UNKNOWN, LENGTH1, LENGTH2, DATA, SUMCHECK} state;
yamaguch 0:ea8459db49ef 247 volatile int cur, in, out, received, free;
yamaguch 0:ea8459db49ef 248 char frame_id;
yamaguch 0:ea8459db49ef 249 char destination64[8];
yamaguch 0:ea8459db49ef 250 char destination16[2];
yamaguch 0:ea8459db49ef 251 char buf[BUFSIZE];
yamaguch 0:ea8459db49ef 252 bool debug;
yamaguch 0:ea8459db49ef 253
yamaguch 0:ea8459db49ef 254 void send(char c);
yamaguch 0:ea8459db49ef 255 void send2(char c);
yamaguch 0:ea8459db49ef 256 void sendFrame(char* frame, int length);
yamaguch 0:ea8459db49ef 257 int createTxRequest(char frame_id, char* data, int data_length, char* buf, int buf_size);
yamaguch 0:ea8459db49ef 258 int createAtRequest(char frame_id, char* command, char* param, int param_length, bool queue, char* buf, int buf_size);
yamaguch 0:ea8459db49ef 259 int createRemoteAtRequest(char frame_id, char* command, char* param, int param_length, char options, char* buf, int buf_size);
yamaguch 0:ea8459db49ef 260 int seekFor(FrameType type, float timeout);
yamaguch 0:ea8459db49ef 261 FrameType getFrameType(char c);
yamaguch 0:ea8459db49ef 262 bool scan(int i, ValueType type, char *value, int maxlength = 1, int *length = 0);
yamaguch 0:ea8459db49ef 263 void flush();
yamaguch 0:ea8459db49ef 264 void rxInterruptHandler();
yamaguch 0:ea8459db49ef 265 void rxInterruptHandler2();
yamaguch 0:ea8459db49ef 266
yamaguch 0:ea8459db49ef 267 void dump(char* data, int length);
yamaguch 0:ea8459db49ef 268 void dumpIOSample(char *data, int length);
yamaguch 0:ea8459db49ef 269 void copy(char *toBuf, int fromIndex, int length);
yamaguch 0:ea8459db49ef 270 };
yamaguch 0:ea8459db49ef 271
yamaguch 0:ea8459db49ef 272 #endif