Johannes Stratmann / WeeESP8266

Provide an easy-to-use way to manipulate ESP8266.

Dependencies:   ArduinoAPI

Fork of WeeESP8266 by ITEAD STUDIO

ESP8266.h@3:9f745022331a, 2015-02-06 (annotated)

Committer:
itead
Date:
Fri Feb 06 04:01:50 2015 +0000
Revision:
3:9f745022331a
Parent:
2:fb209f93f3f1
Child:
4:c8e2381d34d2
All API Defined!

Who changed what in which revision?

UserRevisionLine numberNew contents of line
itead 1:edc634cad906 1 /**
itead 2:fb209f93f3f1 2 * @file ESP8266.h
itead 2:fb209f93f3f1 3 * @brief The definition of class ESP8266.
itead 1:edc634cad906 4 * @author Wu Pengfei<pengfei.wu@itead.cc>
itead 1:edc634cad906 5 * @date 2015.02
itead 1:edc634cad906 6 *
itead 1:edc634cad906 7 * @par Copyright:
itead 1:edc634cad906 8 * Copyright (c) 2015 ITEAD Intelligent Systems Co., Ltd. \n\n
itead 1:edc634cad906 9 * This program is free software; you can redistribute it and/or
itead 1:edc634cad906 10 * modify it under the terms of the GNU General Public License as
itead 1:edc634cad906 11 * published by the Free Software Foundation; either version 2 of
itead 1:edc634cad906 12 * the License, or (at your option) any later version. \n\n
itead 1:edc634cad906 13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
itead 1:edc634cad906 14 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
itead 1:edc634cad906 15 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
itead 1:edc634cad906 16 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
itead 1:edc634cad906 17 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
itead 1:edc634cad906 18 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
itead 1:edc634cad906 19 * THE SOFTWARE.
itead 1:edc634cad906 20 */
itead 2:fb209f93f3f1 21 #ifndef __ESP8266_H__
itead 2:fb209f93f3f1 22 #define __ESP8266_H__
itead 0:d3b93948c925 23
itead 1:edc634cad906 24 #include "ArduinoAPI.h"
itead 0:d3b93948c925 25
itead 1:edc634cad906 26 /**
itead 1:edc634cad906 27 * Provide an easy-to-use way to manipulate ESP8266.
itead 1:edc634cad906 28 */
itead 2:fb209f93f3f1 29 class ESP8266 {
itead 1:edc634cad906 30 public:
itead 1:edc634cad906 31
itead 3:9f745022331a 32 /**
itead 3:9f745022331a 33 * Constuctor.
itead 3:9f745022331a 34 *
itead 3:9f745022331a 35 * @param uart - an reference of ArduinoSerial object with baud 9600.
itead 3:9f745022331a 36 */
itead 3:9f745022331a 37 ESP8266(ArduinoSerial &uart); /* baud rate is 9600 */
itead 1:edc634cad906 38
itead 1:edc634cad906 39 /**
itead 3:9f745022331a 40 * Verify ESP8266 whether live or not.
itead 1:edc634cad906 41 *
itead 1:edc634cad906 42 * Actually, this method will send command "AT" to ESP8266 and waiting for "OK".
itead 1:edc634cad906 43 *
itead 1:edc634cad906 44 * @retval true - alive.
itead 1:edc634cad906 45 * @retval false - dead.
itead 1:edc634cad906 46 */
itead 1:edc634cad906 47 bool kick(void);
itead 1:edc634cad906 48
itead 1:edc634cad906 49 /**
itead 1:edc634cad906 50 * Restart ESP8266 by "AT+RST".
itead 1:edc634cad906 51 *
itead 1:edc634cad906 52 * This method will take 3 seconds or more.
itead 1:edc634cad906 53 *
itead 1:edc634cad906 54 * @retval true - success.
itead 1:edc634cad906 55 * @retval false - failure.
itead 1:edc634cad906 56 */
itead 1:edc634cad906 57 bool restart(void);
itead 1:edc634cad906 58
itead 1:edc634cad906 59 /**
itead 1:edc634cad906 60 * Get the version of AT Command Set.
itead 1:edc634cad906 61 *
itead 1:edc634cad906 62 * @return the string of version.
itead 1:edc634cad906 63 */
itead 1:edc634cad906 64 String getVersion(void);
itead 1:edc634cad906 65
itead 1:edc634cad906 66 /**
itead 1:edc634cad906 67 * Set operation mode to staion.
itead 1:edc634cad906 68 *
itead 1:edc634cad906 69 * @retval true - success.
itead 1:edc634cad906 70 * @retval false - failure.
itead 1:edc634cad906 71 */
itead 1:edc634cad906 72 bool setOprToStation(void);
itead 1:edc634cad906 73
itead 1:edc634cad906 74 /**
itead 1:edc634cad906 75 * Set operation mode to softap.
itead 1:edc634cad906 76 *
itead 1:edc634cad906 77 * @retval true - success.
itead 1:edc634cad906 78 * @retval false - failure.
itead 1:edc634cad906 79 */
itead 1:edc634cad906 80 bool setOprToSoftAP(void);
itead 1:edc634cad906 81
itead 1:edc634cad906 82 /**
itead 1:edc634cad906 83 * Set operation mode to station + softap.
itead 1:edc634cad906 84 *
itead 1:edc634cad906 85 * @retval true - success.
itead 1:edc634cad906 86 * @retval false - failure.
itead 1:edc634cad906 87 */
itead 1:edc634cad906 88 bool setOprToStationSoftAP(void);
itead 1:edc634cad906 89
itead 1:edc634cad906 90 /**
itead 1:edc634cad906 91 * Search available AP list and return it.
itead 1:edc634cad906 92 *
itead 1:edc634cad906 93 * @return the list of available APs.
itead 1:edc634cad906 94 * @note This method will occupy a lot of memeory(hundreds of Bytes to a couple of KBytes).
itead 1:edc634cad906 95 * Do not call this method unless you must and ensure that your board has enough memery left.
itead 1:edc634cad906 96 */
itead 1:edc634cad906 97 String getAPList(void);
itead 1:edc634cad906 98
itead 1:edc634cad906 99 /**
itead 1:edc634cad906 100 * Join in AP.
itead 1:edc634cad906 101 *
itead 1:edc634cad906 102 * @param ssid - SSID of AP to join in.
itead 1:edc634cad906 103 * @param pwd - Password of AP to join in.
itead 1:edc634cad906 104 * @retval true - success.
itead 1:edc634cad906 105 * @retval false - failure.
itead 1:edc634cad906 106 * @note This method will take a couple of seconds.
itead 1:edc634cad906 107 */
itead 1:edc634cad906 108 bool joinAP(String ssid, String pwd);
itead 1:edc634cad906 109
itead 1:edc634cad906 110 /**
itead 1:edc634cad906 111 * Leave AP joined before.
itead 1:edc634cad906 112 *
itead 1:edc634cad906 113 * @retval true - success.
itead 1:edc634cad906 114 * @retval false - failure.
itead 1:edc634cad906 115 */
itead 1:edc634cad906 116 bool leaveAP(void);
itead 1:edc634cad906 117
itead 1:edc634cad906 118 /**
itead 1:edc634cad906 119 * Set SoftAP parameters.
itead 1:edc634cad906 120 *
itead 1:edc634cad906 121 * @param ssid - SSID of SoftAP.
itead 1:edc634cad906 122 * @param pwd - PASSWORD of SoftAP.
itead 1:edc634cad906 123 * @param chl - the channel (1 - 13, default: 7).
itead 1:edc634cad906 124 * @param ecn - the way of encrypstion (0 - OPEN, 1 - WEP,
itead 1:edc634cad906 125 * 2 - WPA_PSK, 3 - WPA2_PSK, 4 - WPA_WPA2_PSK, default: 0).
itead 1:edc634cad906 126 * @note This method should not be called when station mode.
itead 1:edc634cad906 127 */
itead 1:edc634cad906 128 bool setSoftAPParam(String ssid, String pwd, uint8_t chl = 7, uint8_t ecn = 0);
itead 1:edc634cad906 129
itead 1:edc634cad906 130 /**
itead 1:edc634cad906 131 * Get the IP list of devices connected to SoftAP.
itead 1:edc634cad906 132 *
itead 1:edc634cad906 133 * @return the list of IP.
itead 1:edc634cad906 134 * @note This method should not be called when station mode.
itead 1:edc634cad906 135 */
itead 3:9f745022331a 136 String getJoinedDeviceIP(void);
itead 3:9f745022331a 137
itead 3:9f745022331a 138 /**
itead 3:9f745022331a 139 * Get the current status of connection(UDP and TCP).
itead 3:9f745022331a 140 *
itead 3:9f745022331a 141 * @return the status.
itead 3:9f745022331a 142 */
itead 3:9f745022331a 143 String getIPStatus(void);
itead 3:9f745022331a 144
itead 3:9f745022331a 145 /**
itead 3:9f745022331a 146 * Get the IP address of ESP8266.
itead 3:9f745022331a 147 *
itead 3:9f745022331a 148 * @return the IP list.
itead 3:9f745022331a 149 */
itead 3:9f745022331a 150 String getLocalIP(void);
itead 3:9f745022331a 151
itead 3:9f745022331a 152 /**
itead 3:9f745022331a 153 * Enable IP MUX(multiple connection mode).
itead 3:9f745022331a 154 *
itead 3:9f745022331a 155 * In multiple connection mode, a couple of TCP and UDP communication can be builded.
itead 3:9f745022331a 156 * They can be distinguished by the identifier of TCP or UDP named mux_id.
itead 3:9f745022331a 157 *
itead 3:9f745022331a 158 * @retval true - success.
itead 3:9f745022331a 159 * @retval false - failure.
itead 3:9f745022331a 160 */
itead 3:9f745022331a 161 bool enableMUX(void);
itead 3:9f745022331a 162
itead 3:9f745022331a 163 /**
itead 3:9f745022331a 164 * Disable IP MUX(single connection mode).
itead 3:9f745022331a 165 *
itead 3:9f745022331a 166 * In single connection mode, only one TCP or UDP communication can be builded.
itead 3:9f745022331a 167 *
itead 3:9f745022331a 168 * @retval true - success.
itead 3:9f745022331a 169 * @retval false - failure.
itead 3:9f745022331a 170 */
itead 3:9f745022331a 171 bool disableMUX(void);
itead 3:9f745022331a 172
itead 3:9f745022331a 173 /*
itead 3:9f745022331a 174 * Single connection mode methods
itead 3:9f745022331a 175 */
itead 3:9f745022331a 176
itead 3:9f745022331a 177 /**
itead 3:9f745022331a 178 * Create TCP connection in single mode.
itead 3:9f745022331a 179 *
itead 3:9f745022331a 180 * @param addr - the IP or domain name of the target host.
itead 3:9f745022331a 181 * @param port - the port number of the target host.
itead 3:9f745022331a 182 * @retval true - success.
itead 3:9f745022331a 183 * @retval false - failure.
itead 3:9f745022331a 184 */
itead 3:9f745022331a 185 bool createTCP(String addr, uint32_t port);
itead 3:9f745022331a 186
itead 3:9f745022331a 187 /**
itead 3:9f745022331a 188 * Release TCP connection in single mode.
itead 3:9f745022331a 189 *
itead 3:9f745022331a 190 * @retval true - success.
itead 3:9f745022331a 191 * @retval false - failure.
itead 3:9f745022331a 192 */
itead 3:9f745022331a 193 bool releaseTCP(void);
itead 3:9f745022331a 194
itead 3:9f745022331a 195 /**
itead 3:9f745022331a 196 * Register UDP port number in single mode.
itead 3:9f745022331a 197 *
itead 3:9f745022331a 198 * @param addr - the IP or domain name of the target host.
itead 3:9f745022331a 199 * @param port - the port number of the target host.
itead 3:9f745022331a 200 * @retval true - success.
itead 3:9f745022331a 201 * @retval false - failure.
itead 3:9f745022331a 202 */
itead 3:9f745022331a 203 bool registerUDP(String addr, uint32_t port);
itead 3:9f745022331a 204
itead 3:9f745022331a 205 /**
itead 3:9f745022331a 206 * Unregister UDP port number in single mode.
itead 3:9f745022331a 207 *
itead 3:9f745022331a 208 * @retval true - success.
itead 3:9f745022331a 209 * @retval false - failure.
itead 3:9f745022331a 210 */
itead 3:9f745022331a 211 bool unregisterUDP(void);
itead 3:9f745022331a 212
itead 3:9f745022331a 213 /**
itead 3:9f745022331a 214 * Send data based on TCP or UDP builded already in single mode.
itead 3:9f745022331a 215 *
itead 3:9f745022331a 216 * @param buffer - the buffer of data to send.
itead 3:9f745022331a 217 * @param len - the length of data to send.
itead 3:9f745022331a 218 * @retval true - success.
itead 3:9f745022331a 219 * @retval false - failure.
itead 3:9f745022331a 220 */
itead 3:9f745022331a 221 bool send(const uint8_t *buffer, uint32_t len);
itead 3:9f745022331a 222
itead 3:9f745022331a 223 /**
itead 3:9f745022331a 224 * Receive data from TCP or UDP builded already in single mode.
itead 3:9f745022331a 225 *
itead 3:9f745022331a 226 * @param buffer - the buffer for storing data.
itead 3:9f745022331a 227 * @param len - the length of the buffer.
itead 3:9f745022331a 228 * @param timeout - the time waiting data.
itead 3:9f745022331a 229 * @return the length of data received actually.
itead 3:9f745022331a 230 */
itead 3:9f745022331a 231 uint32_t recv(uint8_t *buffer, uint32_t len, uint32_t timeout = 1000);
itead 3:9f745022331a 232
itead 3:9f745022331a 233 /*
itead 3:9f745022331a 234 * Multiple connection mode methods
itead 3:9f745022331a 235 */
itead 3:9f745022331a 236
itead 3:9f745022331a 237 /**
itead 3:9f745022331a 238 * Create TCP connection in multiple mode.
itead 3:9f745022331a 239 *
itead 3:9f745022331a 240 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 241 * @param addr - the IP or domain name of the target host.
itead 3:9f745022331a 242 * @param port - the port number of the target host.
itead 3:9f745022331a 243 * @retval true - success.
itead 3:9f745022331a 244 * @retval false - failure.
itead 3:9f745022331a 245 */
itead 3:9f745022331a 246 bool createTCP(uint8_t mux_id, String addr, uint32_t port);
itead 3:9f745022331a 247
itead 3:9f745022331a 248 /**
itead 3:9f745022331a 249 * Release TCP connection in multiple mode.
itead 3:9f745022331a 250 *
itead 3:9f745022331a 251 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 252 * @retval true - success.
itead 3:9f745022331a 253 * @retval false - failure.
itead 3:9f745022331a 254 */
itead 3:9f745022331a 255 bool releaseTCP(uint8_t mux_id);
itead 3:9f745022331a 256
itead 3:9f745022331a 257 /**
itead 3:9f745022331a 258 * Register UDP port number in multiple mode.
itead 3:9f745022331a 259 *
itead 3:9f745022331a 260 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 261 * @param addr - the IP or domain name of the target host.
itead 3:9f745022331a 262 * @param port - the port number of the target host.
itead 3:9f745022331a 263 * @retval true - success.
itead 3:9f745022331a 264 * @retval false - failure.
itead 3:9f745022331a 265 */
itead 3:9f745022331a 266 bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
itead 3:9f745022331a 267
itead 3:9f745022331a 268 /**
itead 3:9f745022331a 269 * Unregister UDP port number in multiple mode.
itead 3:9f745022331a 270 *
itead 3:9f745022331a 271 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 272 * @retval true - success.
itead 3:9f745022331a 273 * @retval false - failure.
itead 3:9f745022331a 274 */
itead 3:9f745022331a 275 bool unregisterUDP(uint8_t mux_id);
itead 3:9f745022331a 276
itead 3:9f745022331a 277 /**
itead 3:9f745022331a 278 * Send data based on one of TCP or UDP builded already in multiple mode.
itead 3:9f745022331a 279 *
itead 3:9f745022331a 280 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 281 * @param buffer - the buffer of data to send.
itead 3:9f745022331a 282 * @param len - the length of data to send.
itead 3:9f745022331a 283 * @retval true - success.
itead 3:9f745022331a 284 * @retval false - failure.
itead 3:9f745022331a 285 */
itead 3:9f745022331a 286 bool send(uint8_t mux_id, const char *buffer, uint32_t len);
itead 3:9f745022331a 287
itead 3:9f745022331a 288 /**
itead 3:9f745022331a 289 * Receive data from one of TCP or UDP builded already in multiple mode.
itead 3:9f745022331a 290 *
itead 3:9f745022331a 291 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
itead 3:9f745022331a 292 * @param buffer - the buffer for storing data.
itead 3:9f745022331a 293 * @param len - the length of the buffer.
itead 3:9f745022331a 294 * @param timeout - the time waiting data.
itead 3:9f745022331a 295 * @return the length of data received actually.
itead 3:9f745022331a 296 */
itead 3:9f745022331a 297 uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout = 1000);
itead 3:9f745022331a 298
itead 3:9f745022331a 299 /**
itead 3:9f745022331a 300 * Receive data from all of TCP or UDP builded already in multiple mode.
itead 3:9f745022331a 301 *
itead 3:9f745022331a 302 * After return, coming_mux_id store the id of TCP or UDP from which data coming.
itead 3:9f745022331a 303 * User should read the value of coming_mux_id and decide what next to do.
itead 3:9f745022331a 304 *
itead 3:9f745022331a 305 * @param coming_mux_id - the identifier of TCP or UDP.
itead 3:9f745022331a 306 * @param buffer - the buffer for storing data.
itead 3:9f745022331a 307 * @param len - the length of the buffer.
itead 3:9f745022331a 308 * @param timeout - the time waiting data.
itead 3:9f745022331a 309 * @return the length of data received actually.
itead 3:9f745022331a 310 */
itead 3:9f745022331a 311 uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout = 1000);
itead 3:9f745022331a 312
itead 3:9f745022331a 313 /*
itead 3:9f745022331a 314 * Server
itead 3:9f745022331a 315 */
itead 3:9f745022331a 316
itead 3:9f745022331a 317 /**
itead 3:9f745022331a 318 * Set the timeout of TCP Server.
itead 3:9f745022331a 319 *
itead 3:9f745022331a 320 * @param timeout - the duration for timeout by second(0 ~ 28800, default:180).
itead 3:9f745022331a 321 * @retval true - success.
itead 3:9f745022331a 322 * @retval false - failure.
itead 3:9f745022331a 323 */
itead 3:9f745022331a 324 bool setTCPServerTimeout(uint32_t timeout = 180);
itead 3:9f745022331a 325
itead 3:9f745022331a 326 /**
itead 3:9f745022331a 327 * Start TCP Server(Only in multiple mode).
itead 3:9f745022331a 328 *
itead 3:9f745022331a 329 * After started, user should call method: getIPStatus to know the status of TCP connections.
itead 3:9f745022331a 330 * The methods of receiving data can be called for user's any purpose. After communication,
itead 3:9f745022331a 331 * release the TCP connection is needed by calling method: releaseTCP with mux_id.
itead 3:9f745022331a 332 *
itead 3:9f745022331a 333 * @param port - the port number to listen(default: 333).
itead 3:9f745022331a 334 * @retval true - success.
itead 3:9f745022331a 335 * @retval false - failure.
itead 3:9f745022331a 336 *
itead 3:9f745022331a 337 * @see String getIPStatus(void);
itead 3:9f745022331a 338 * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
itead 3:9f745022331a 339 * @see bool releaseTCP(uint8_t mux_id);
itead 3:9f745022331a 340 */
itead 3:9f745022331a 341 bool startTCPServer(uint32_t port = 333);
itead 1:edc634cad906 342
itead 1:edc634cad906 343
itead 3:9f745022331a 344 /**
itead 3:9f745022331a 345 * Stop TCP Server(Only in multiple mode).
itead 3:9f745022331a 346 *
itead 3:9f745022331a 347 * @retval true - success.
itead 3:9f745022331a 348 * @retval false - failure.
itead 3:9f745022331a 349 */
itead 3:9f745022331a 350 bool stopTCPServer(void);
itead 3:9f745022331a 351
itead 1:edc634cad906 352 private:
itead 3:9f745022331a 353 ArduinoSerial *m_puart; /* The UART to communicate with ESP8266 */
itead 1:edc634cad906 354
itead 1:edc634cad906 355 };
itead 0:d3b93948c925 356
itead 2:fb209f93f3f1 357 #endif /* #ifndef __ESP8266_H__ */