source: rtos_arduino/trunk/arduino_lib/libraries/ESP8266/ESP8266.h@ 136

Last change on this file since 136 was 136, checked in by ertl-honda, 8 years ago

ライブラリとOS及びベーシックなサンプルの追加．
File size: 15.0 KB
Line 
1/**
2 * @file ESP8266.h
3 * @brief The definition of class ESP8266.
4 * @author Wu Pengfei<pengfei.wu@itead.cc>
5 * @date 2015.02
6 *
7 * @par Copyright:
8 * Copyright (c) 2015 ITEAD Intelligent Systems Co., Ltd. \n\n
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as
11 * published by the Free Software Foundation; either version 2 of
12 * the License, or (at your option) any later version. \n\n
13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19 * THE SOFTWARE.
20 */
21#ifndef __ESP8266_H__
22#define __ESP8266_H__
23
24#include "Arduino.h"
25
26
27//#define ESP8266_USE_SOFTWARE_SERIAL
28
29
30#ifdef ESP8266_USE_SOFTWARE_SERIAL
31#include "SoftwareSerial.h"
32#endif
33
34
35/**
36 * Provide an easy-to-use way to manipulate ESP8266.
37 */
38class ESP8266 {
39 public:
40
41#ifdef ESP8266_USE_SOFTWARE_SERIAL
42 /*
43 * Constuctor.
44 *
45 * @param uart - an reference of SoftwareSerial object.
46 * @param baud - the buad rate to communicate with ESP8266(default:115200).
47 *
48 * @warning parameter baud depends on the AT firmware. 115200 is an common value.
49 */
50 void begin(SoftwareSerial &uart, uint32_t baud = 115200);
51#else /* HardwareSerial */
52 /*
53 * Constuctor.
54 *
55 * @param uart - an reference of HardwareSerial object.
56 * @param baud - the buad rate to communicate with ESP8266(default:115200).
57 *
58 * @warning parameter baud depends on the AT firmware. 115200 is an common value.
59 */
60 void begin(HardwareSerial &uart, uint32_t baud = 115200);
61#endif
62
63
64 /**
65 * Verify ESP8266 whether live or not.
66 *
67 * Actually, this method will send command "AT" to ESP8266 and waiting for "OK".
68 *
69 * @retval true - alive.
70 * @retval false - dead.
71 */
72 bool kick(void);
73
74 /**
75 * Restart ESP8266 by "AT+RST".
76 *
77 * This method will take 3 seconds or more.
78 *
79 * @retval true - success.
80 * @retval false - failure.
81 */
82 bool restart(void);
83
84 /**
85 * Get the version of AT Command Set.
86 *
87 * @return the string of version.
88 */
89 String getVersion(void);
90
91 /**
92 * Set operation mode to staion.
93 *
94 * @retval true - success.
95 * @retval false - failure.
96 */
97 bool setOprToStation(void);
98
99 /**
100 * Set operation mode to softap.
101 *
102 * @retval true - success.
103 * @retval false - failure.
104 */
105 bool setOprToSoftAP(void);
106
107 /**
108 * Set operation mode to station + softap.
109 *
110 * @retval true - success.
111 * @retval false - failure.
112 */
113 bool setOprToStationSoftAP(void);
114
115 /**
116 * Search available AP list and return it.
117 *
118 * @return the list of available APs.
119 * @note This method will occupy a lot of memeory(hundreds of Bytes to a couple of KBytes).
120 * Do not call this method unless you must and ensure that your board has enough memery left.
121 */
122 String getAPList(void);
123
124 /**
125 * Join in AP.
126 *
127 * @param ssid - SSID of AP to join in.
128 * @param pwd - Password of AP to join in.
129 * @retval true - success.
130 * @retval false - failure.
131 * @note This method will take a couple of seconds.
132 */
133 bool joinAP(String ssid, String pwd);
134
135 /**
136 * Leave AP joined before.
137 *
138 * @retval true - success.
139 * @retval false - failure.
140 */
141 bool leaveAP(void);
142
143 /**
144 * Set SoftAP parameters.
145 *
146 * @param ssid - SSID of SoftAP.
147 * @param pwd - PASSWORD of SoftAP.
148 * @param chl - the channel (1 - 13, default: 7).
149 * @param ecn - the way of encrypstion (0 - OPEN, 1 - WEP,
150 * 2 - WPA_PSK, 3 - WPA2_PSK, 4 - WPA_WPA2_PSK, default: 4).
151 * @note This method should not be called when station mode.
152 */
153 bool setSoftAPParam(String ssid, String pwd, uint8_t chl = 7, uint8_t ecn = 4);
154
155 /**
156 * Get the IP list of devices connected to SoftAP.
157 *
158 * @return the list of IP.
159 * @note This method should not be called when station mode.
160 */
161 String getJoinedDeviceIP(void);
162
163 /**
164 * Get the current status of connection(UDP and TCP).
165 *
166 * @return the status.
167 */
168 String getIPStatus(void);
169
170 /**
171 * Get the IP address of ESP8266.
172 *
173 * @return the IP list.
174 */
175 String getLocalIP(void);
176
177 /**
178 * Enable IP MUX(multiple connection mode).
179 *
180 * In multiple connection mode, a couple of TCP and UDP communication can be builded.
181 * They can be distinguished by the identifier of TCP or UDP named mux_id.
182 *
183 * @retval true - success.
184 * @retval false - failure.
185 */
186 bool enableMUX(void);
187
188 /**
189 * Disable IP MUX(single connection mode).
190 *
191 * In single connection mode, only one TCP or UDP communication can be builded.
192 *
193 * @retval true - success.
194 * @retval false - failure.
195 */
196 bool disableMUX(void);
197
198
199 /**
200 * Create TCP connection in single mode.
201 *
202 * @param addr - the IP or domain name of the target host.
203 * @param port - the port number of the target host.
204 * @retval true - success.
205 * @retval false - failure.
206 */
207 bool createTCP(String addr, uint32_t port);
208
209 /**
210 * Release TCP connection in single mode.
211 *
212 * @retval true - success.
213 * @retval false - failure.
214 */
215 bool releaseTCP(void);
216
217 /**
218 * Register UDP port number in single mode.
219 *
220 * @param addr - the IP or domain name of the target host.
221 * @param port - the port number of the target host.
222 * @retval true - success.
223 * @retval false - failure.
224 */
225 bool registerUDP(String addr, uint32_t port);
226
227 /**
228 * Unregister UDP port number in single mode.
229 *
230 * @retval true - success.
231 * @retval false - failure.
232 */
233 bool unregisterUDP(void);
234
235 /**
236 * Create TCP connection in multiple mode.
237 *
238 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
239 * @param addr - the IP or domain name of the target host.
240 * @param port - the port number of the target host.
241 * @retval true - success.
242 * @retval false - failure.
243 */
244 bool createTCP(uint8_t mux_id, String addr, uint32_t port);
245
246 /**
247 * Release TCP connection in multiple mode.
248 *
249 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
250 * @retval true - success.
251 * @retval false - failure.
252 */
253 bool releaseTCP(uint8_t mux_id);
254
255 /**
256 * Register UDP port number in multiple mode.
257 *
258 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
259 * @param addr - the IP or domain name of the target host.
260 * @param port - the port number of the target host.
261 * @retval true - success.
262 * @retval false - failure.
263 */
264 bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
265
266 /**
267 * Unregister UDP port number in multiple mode.
268 *
269 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
270 * @retval true - success.
271 * @retval false - failure.
272 */
273 bool unregisterUDP(uint8_t mux_id);
274
275
276 /**
277 * Set the timeout of TCP Server.
278 *
279 * @param timeout - the duration for timeout by second(0 ~ 28800, default:180).
280 * @retval true - success.
281 * @retval false - failure.
282 */
283 bool setTCPServerTimeout(uint32_t timeout = 180);
284
285 /**
286 * Start TCP Server(Only in multiple mode).
287 *
288 * After started, user should call method: getIPStatus to know the status of TCP connections.
289 * The methods of receiving data can be called for user's any purpose. After communication,
290 * release the TCP connection is needed by calling method: releaseTCP with mux_id.
291 *
292 * @param port - the port number to listen(default: 333).
293 * @retval true - success.
294 * @retval false - failure.
295 *
296 * @see String getIPStatus(void);
297 * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
298 * @see bool releaseTCP(uint8_t mux_id);
299 */
300 bool startTCPServer(uint32_t port = 333);
301
302 /**
303 * Stop TCP Server(Only in multiple mode).
304 *
305 * @retval true - success.
306 * @retval false - failure.
307 */
308 bool stopTCPServer(void);
309
310 /**
311 * Start Server(Only in multiple mode).
312 *
313 * @param port - the port number to listen(default: 333).
314 * @retval true - success.
315 * @retval false - failure.
316 *
317 * @see String getIPStatus(void);
318 * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
319 */
320 bool startServer(uint32_t port = 333);
321
322 /**
323 * Stop Server(Only in multiple mode).
324 *
325 * @retval true - success.
326 * @retval false - failure.
327 */
328 bool stopServer(void);
329
330 /**
331 * Send data based on TCP or UDP builded already in single mode.
332 *
333 * @param buffer - the buffer of data to send.
334 * @param len - the length of data to send.
335 * @retval true - success.
336 * @retval false - failure.
337 */
338 bool send(const uint8_t *buffer, uint32_t len);
339
340 /**
341 * Send data based on one of TCP or UDP builded already in multiple mode.
342 *
343 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
344 * @param buffer - the buffer of data to send.
345 * @param len - the length of data to send.
346 * @retval true - success.
347 * @retval false - failure.
348 */
349 bool send(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
350
351 /**
352 * Send data based on TCP or UDP builded already in single mode.
353 *
354 * @param str - String to send.
355 * @retval true - success.
356 * @retval false - failure.
357 */
358 bool send(String &str);
359
360 /**
361 * Send data based on one of TCP or UDP builded already in multiple mode.
362 *
363 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
364 * @param str - String to send.
365 * @retval true - success.
366 * @retval false - failure.
367 */
368 bool send(uint8_t mux_id, String &str);
369
370 /**
371 * Receive data from TCP or UDP builded already in single mode.
372 *
373 * @param buffer - the buffer for storing data.
374 * @param buffer_size - the length of the buffer.
375 * @param timeout - the time waiting data.
376 * @return the length of data received actually.
377 */
378 uint32_t recv(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
379
380 /**
381 * Receive data from one of TCP or UDP builded already in multiple mode.
382 *
383 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
384 * @param buffer - the buffer for storing data.
385 * @param buffer_size - the length of the buffer.
386 * @param timeout - the time waiting data.
387 * @return the length of data received actually.
388 */
389 uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
390
391 /**
392 * Receive data from all of TCP or UDP builded already in multiple mode.
393 *
394 * After return, coming_mux_id store the id of TCP or UDP from which data coming.
395 * User should read the value of coming_mux_id and decide what next to do.
396 *
397 * @param coming_mux_id - the identifier of TCP or UDP.
398 * @param buffer - the buffer for storing data.
399 * @param buffer_size - the length of the buffer.
400 * @param timeout - the time waiting data.
401 * @return the length of data received actually.
402 */
403 uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
404
405 private:
406
407 /*
408 * Empty the buffer or UART RX.
409 */
410 void rx_empty(void);
411
412 /*
413 * Recvive data from uart. Return all received data if target found or timeout.
414 */
415 String recvString(String target, uint32_t timeout = 1000);
416
417 /*
418 * Recvive data from uart. Return all received data if one of target1 and target2 found or timeout.
419 */
420 String recvString(String target1, String target2, uint32_t timeout = 1000);
421
422 /*
423 * Recvive data from uart. Return all received data if one of target1, target2 and target3 found or timeout.
424 */
425 String recvString(String target1, String target2, String target3, uint32_t timeout = 1000);
426
427 /*
428 * Recvive data from uart and search first target. Return true if target found, false for timeout.
429 */
430 bool recvFind(String target, uint32_t timeout = 1000);
431
432 /*
433 * Recvive data from uart and search first target and cut out the substring between begin and end(excluding begin and end self).
434 * Return true if target found, false for timeout.
435 */
436 bool recvFindAndFilter(String target, String begin, String end, String &data, uint32_t timeout = 1000);
437
438 /*
439 * Receive a package from uart.
440 *
441 * @param buffer - the buffer storing data.
442 * @param buffer_size - guess what!
443 * @param data_len - the length of data actually received(maybe more than buffer_size, the remained data will be abandoned).
444 * @param timeout - the duration waitting data comming.
445 * @param coming_mux_id - in single connection mode, should be NULL and not NULL in multiple.
446 */
447 uint32_t recvPkg(uint8_t *buffer, uint32_t buffer_size, uint32_t *data_len, uint32_t timeout, uint8_t *coming_mux_id);
448
449
450 bool eAT(void);
451 bool eATRST(void);
452 bool eATGMR(String &version);
453
454 bool qATCWMODE(uint8_t *mode);
455 bool sATCWMODE(uint8_t mode);
456 bool sATCWJAP(String ssid, String pwd);
457 bool eATCWLAP(String &list);
458 bool eATCWQAP(void);
459 bool sATCWSAP(String ssid, String pwd, uint8_t chl, uint8_t ecn);
460 bool eATCWLIF(String &list);
461
462 bool eATCIPSTATUS(String &list);
463 bool sATCIPSTARTSingle(String type, String addr, uint32_t port);
464 bool sATCIPSTARTMultiple(uint8_t mux_id, String type, String addr, uint32_t port);
465 bool sATCIPSENDSingle(const uint8_t *buffer, uint32_t len);
466 bool sATCIPSENDMultiple(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
467 bool sATCIPSENDSingle(String &str);
468 bool sATCIPSENDMultiple(uint8_t mux_id, String &str);
469 bool sATCIPCLOSEMulitple(uint8_t mux_id);
470 bool eATCIPCLOSESingle(void);
471 bool eATCIFSR(String &list);
472 bool sATCIPMUX(uint8_t mode);
473 bool sATCIPSERVER(uint8_t mode, uint32_t port = 333);
474 bool sATCIPSTO(uint32_t timeout);
475
476 /*
477 * +IPD,len:data
478 * +IPD,id,len:data
479 */
480
481#ifdef ESP8266_USE_SOFTWARE_SERIAL
482 SoftwareSerial *m_puart; /* The UART to communicate with ESP8266 */
483#else
484 HardwareSerial *m_puart; /* The UART to communicate with ESP8266 */
485#endif
486 uint32_t m_baud;
487};
488
489#endif /* #ifndef __ESP8266_H__ */
490
Note: See TracBrowser for help on using the repository browser.