source: rtos_arduino/trunk/arduino_lib/libraries/ESP8266_Arudino_AT/ESP8266.h@ 178

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

ドキュメントの更新
File size: 17.5 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 * Copyright (C) 2015 Embedded and Real-Time Systems Laboratory
10 * Graduate School of Information Science, Nagoya Univ., JAPAN \n\n
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License as
13 * published by the Free Software Foundation; either version 2 of
14 * the License, or (at your option) any later version. \n\n
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 * THE SOFTWARE.
22 */
23#ifndef __ESP8266_H__
24#define __ESP8266_H__
25
26#include "Arduino.h"
27
28//#define ESP8266_USE_SOFTWARE_SERIAL
29
30#define ESP8266_SUPPORT_VERSION "AT version:0.25"
31
32#define ESP8266_NUM_CONNECTION 5
33
34#ifdef ESP8266_USE_SOFTWARE_SERIAL
35#include "SoftwareSerial.h"
36#endif /* ESP8266_USE_SOFTWARE_SERIAL */
37
38#define ESP8266_CONNECTION_OPEN 0x01
39#define ESP8266_CONNECTION_CLOSE 0x02
40
41#define ESP8266_CONNECTION_TCP 0x01
42#define ESP8266_CONNECTION_UDP 0x02
43
44#define ESP8266_CONNECTION_CLIENT 0x01
45#define ESP8266_CONNECTION_SERVER 0x02
46
47#define ESP8266_STATUS_GOTIP 0x02
48#define ESP8266_STATUS_CONNECTED 0x03
49#define ESP8266_STATUS_DISCONNECTED 0x04
50
51#define ESP8266_WMODE_STATION 0x01
52#define ESP8266_WMODE_SOFTAP 0x02
53#define ESP8266_WMODE_AP_STATION 0x03
54
55struct esp8266_connection_status
56{
57 uint8_t connection_type;
58 uint8_t protocol_type;
59};
60
61#define ESP8266_RINGBUFFER_SIZE 512
62
63class ESP8266_RingBuffer
64{
65 public:
66 ESP8266_RingBuffer(void);
67 void init(void);
68 void free(void) {len = head = tail = 0;};
69 bool write(uint8_t c);
70 uint8_t read(void);
71 uint32_t copy(uint8_t *pdata, uint32_t size);
72 uint8_t peek(void);
73 bool available(void) {return (len > 0);};
74 bool isFull(void) {return (len == ESP8266_RINGBUFFER_SIZE);};
75 uint32_t length(void) {return len;};
76
77 private:
78 uint8_t *buffer;
79 uint32_t head;
80 uint32_t tail;
81 uint32_t len;
82};
83
84/**
85 * Provide an easy-to-use way to manipulate ESP8266.
86 */
87class ESP8266 {
88 public:
89
90 /*
91 * Begin.
92 *
93 * @param uart - an reference of SoftwareSerial object.
94 * @param baud - the buad rate to communicate with ESP8266(default:115200).
95 *
96 * @retval 0 : Success
97 * @retval 1 : Can not communicate ESP8266
98 * @retval 2 : Firmware Version mismatch.
99 *
100 * @warning parameter baud depends on the AT firmware. 115200 is an common value.
101 */
102#ifdef ESP8266_USE_SOFTWARE_SERIAL
103 int begin(SoftwareSerial &uart, uint32_t baud = 115200);
104#else /* HardwareSerial */
105 int begin(HardwareSerial &uart, uint32_t baud = 115200);
106#endif /* ESP8266_USE_SOFTWARE_SERIAL */
107
108 /**
109 * Verify ESP8266 whether live or not.
110 *
111 * Actually, this method will send command "AT" to ESP8266 and waiting for "OK".
112 *
113 * @retval true - alive.
114 * @retval false - dead.
115 */
116 bool kick(void);
117
118 /**
119 * Restart ESP8266 by "AT+RST".
120 *
121 * This method will take 3 seconds or more.
122 *
123 * @retval true - success.
124 * @retval false - failure.
125 */
126 bool restart(void);
127
128 /**
129 * Get the version of AT Command Set.
130 *
131 * @return the string of version.
132 */
133 String getVersion(void);
134
135 /**
136 * Set operation mode to staion.
137 *
138 * @retval true - success.
139 * @retval false - failure.
140 */
141 bool setOprToStation(void);
142
143 /**
144 * Set operation mode to softap.
145 *
146 * @retval true - success.
147 * @retval false - failure.
148 */
149 bool setOprToSoftAP(void);
150
151 /**
152 * Set operation mode to station + softap.
153 *
154 * @retval true - success.
155 * @retval false - failure.
156 */
157 bool setOprToStationSoftAP(void);
158
159 /**
160 * Search available AP list and return it.
161 *
162 * @return the list of available APs.
163 * @note This method will occupy a lot of memeory(hundreds of Bytes to a couple of KBytes).
164 * Do not call this method unless you must and ensure that your board has enough memery left.
165 */
166 String getAPList(void);
167
168 /**
169 * Join in AP.
170 *
171 * @param ssid - SSID of AP to join in.
172 * @param pwd - Password of AP to join in.
173 * @retval true - success.
174 * @retval false - failure.
175 * @note This method will take a couple of seconds.
176 */
177 bool joinAP(String ssid, String pwd);
178
179 /**
180 * Leave AP joined before.
181 *
182 * @retval true - success.
183 * @retval false - failure.
184 */
185 bool leaveAP(void);
186
187 /**
188 * Set SoftAP parameters.
189 *
190 * @param ssid - SSID of SoftAP.
191 * @param pwd - PASSWORD of SoftAP.
192 * @param chl - the channel (1 - 13, default: 7).
193 * @param ecn - the way of encrypstion (0 - OPEN, 1 - WEP,
194 * 2 - WPA_PSK, 3 - WPA2_PSK, 4 - WPA_WPA2_PSK, default: 4).
195 * @note This method should not be called when station mode.
196 */
197 bool setSoftAPParam(String ssid, String pwd, uint8_t chl = 7, uint8_t ecn = 4);
198
199 /**
200 * Get the IP list of devices connected to SoftAP.
201 *
202 * @return the list of IP.
203 * @note This method should not be called when station mode.
204 */
205 String getJoinedDeviceIP(void);
206
207 /**
208 * Get the current status of connection(UDP and TCP).
209 *
210 * @return the status.
211 */
212 String getIPStatus(void);
213
214 /**
215 * Get the IP address of ESP8266.
216 *
217 * @return the IP list.
218 */
219 String getLocalIP(void);
220
221 /**
222 * Enable IP MUX(multiple connection mode).
223 *
224 * In multiple connection mode, a couple of TCP and UDP communication can be builded.
225 * They can be distinguished by the identifier of TCP or UDP named mux_id.
226 *
227 * @retval true - success.
228 * @retval false - failure.
229 */
230 bool enableMUX(void);
231
232 /**
233 * Disable IP MUX(single connection mode).
234 *
235 * In single connection mode, only one TCP or UDP communication can be builded.
236 *
237 * @retval true - success.
238 * @retval false - failure.
239 */
240 bool disableMUX(void);
241
242
243 /**
244 * Create TCP connection in single mode.
245 *
246 * @param addr - the IP or domain name of the target host.
247 * @param port - the port number of the target host.
248 * @retval true - success.
249 * @retval false - failure.
250 */
251 bool createTCP(String addr, uint32_t port);
252
253 /**
254 * Release TCP connection in single mode.
255 *
256 * @retval true - success.
257 * @retval false - failure.
258 */
259 bool releaseTCP(void);
260
261 /**
262 * Register UDP port number in single mode.
263 *
264 * @param addr - the IP or domain name of the target host.
265 * @param port - the port number of the target host.
266 * @retval true - success.
267 * @retval false - failure.
268 */
269 bool registerUDP(String addr, uint32_t port);
270
271 /**
272 * Unregister UDP port number in single mode.
273 *
274 * @retval true - success.
275 * @retval false - failure.
276 */
277 bool unregisterUDP(void);
278
279 /**
280 * Create TCP connection in multiple mode.
281 *
282 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
283 * @param addr - the IP or domain name of the target host.
284 * @param port - the port number of the target host.
285 * @retval true - success.
286 * @retval false - failure.
287 */
288 bool createTCP(uint8_t mux_id, String addr, uint32_t port);
289
290 /**
291 * Release TCP connection in multiple mode.
292 *
293 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
294 * @retval true - success.
295 * @retval false - failure.
296 */
297 bool releaseTCP(uint8_t mux_id);
298
299 /**
300 * Register UDP port number in multiple mode.
301 *
302 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
303 * @param addr - the IP or domain name of the target host.
304 * @param port - the port number of the target host.
305 * @retval true - success.
306 * @retval false - failure.
307 */
308 bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
309
310 /**
311 * Unregister UDP port number in multiple mode.
312 *
313 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
314 * @retval true - success.
315 * @retval false - failure.
316 */
317 bool unregisterUDP(uint8_t mux_id);
318
319
320 /**
321 * Set the timeout of TCP Server.
322 *
323 * @param timeout - the duration for timeout by second(0 ~ 28800, default:180).
324 * @retval true - success.
325 * @retval false - failure.
326 */
327 bool setTCPServerTimeout(uint32_t timeout = 180);
328
329 /**
330 * Start TCP Server(Only in multiple mode).
331 *
332 * After started, user should call method: getIPStatus to know the status of TCP connections.
333 * The methods of receiving data can be called for user's any purpose. After communication,
334 * release the TCP connection is needed by calling method: releaseTCP with mux_id.
335 *
336 * @param port - the port number to listen(default: 333).
337 * @retval true - success.
338 * @retval false - failure.
339 *
340 * @see String getIPStatus(void);
341 * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
342 * @see bool releaseTCP(uint8_t mux_id);
343 */
344 bool startTCPServer(uint32_t port = 333);
345
346 /**
347 * Stop TCP Server(Only in multiple mode).
348 *
349 * @retval true - success.
350 * @retval false - failure.
351 */
352 bool stopTCPServer(void);
353
354 /**
355 * Start Server(Only in multiple mode).
356 *
357 * @param port - the port number to listen(default: 333).
358 * @retval true - success.
359 * @retval false - failure.
360 *
361 * @see String getIPStatus(void);
362 * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
363 */
364 bool startServer(uint32_t port = 333);
365
366 /**
367 * Stop Server(Only in multiple mode).
368 *
369 * @retval true - success.
370 * @retval false - failure.
371 */
372 bool stopServer(void);
373
374 /**
375 * Send data based on TCP or UDP builded already in single mode.
376 *
377 * @param buffer - the buffer of data to send.
378 * @param len - the length of data to send.
379 * @retval true - success.
380 * @retval false - failure.
381 */
382 bool send(const uint8_t *buffer, uint32_t len);
383
384 /**
385 * Send data based on one of TCP or UDP builded already in multiple mode.
386 *
387 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
388 * @param buffer - the buffer of data to send.
389 * @param len - the length of data to send.
390 * @retval true - success.
391 * @retval false - failure.
392 */
393 bool send(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
394
395 /**
396 * Send data based on TCP or UDP builded already in single mode.
397 *
398 * @param str - String to send.
399 * @retval true - success.
400 * @retval false - failure.
401 */
402 bool send(String &str);
403
404 /**
405 * Send data based on one of TCP or UDP builded already in multiple mode.
406 *
407 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
408 * @param str - String to send.
409 * @retval true - success.
410 * @retval false - failure.
411 */
412 bool send(uint8_t mux_id, String &str);
413
414 /**
415 * Receive data from TCP or UDP builded already in single mode.
416 *
417 * @param buffer - the buffer for storing data.
418 * @param buffer_size - the length of the buffer.
419 * @param timeout - the time waiting data.
420 * @return the length of data received actually.
421 */
422 uint32_t recv(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
423
424 /**
425 * Receive data from one of TCP or UDP builded already in multiple mode.
426 *
427 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
428 * @param buffer - the buffer for storing data.
429 * @param buffer_size - the length of the buffer.
430 * @param timeout - the time waiting data.
431 * @return the length of data received actually.
432 */
433 uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
434
435 /**
436 * Receive data from all of TCP or UDP builded already in multiple mode.
437 *
438 * After return, coming_mux_id store the id of TCP or UDP from which data coming.
439 * User should read the value of coming_mux_id and decide what next to do.
440 *
441 * @param coming_mux_id - the identifier of TCP or UDP.
442 * @param buffer - the buffer for storing data.
443 * @param buffer_size - the length of the buffer.
444 * @param timeout - the time waiting data.
445 * @return the length of data received actually.
446 */
447 uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
448
449 /**
450 * Check data is available in specific connection.
451 *
452 * @param mux_id - the identifier of this TCP(available value: 0 - 4).
453 * @return true - data is available.
454 * @return false - data is not available.
455 */
456 bool isDataAvailable(uint8_t mux_id);
457
458 /**
459 * Check data is available in any connection.
460 *
461 * @return true - data is available.
462 * @return false - data is not available.
463 */
464 bool isDataAvailable(void);
465
466 /**
467 * Check connection is opned in single mode.
468 *
469 * @return true - opend.
470 * @return false - closed.
471 */
472 bool isConnected(void);
473
474 /**
475 * Check specific connection is opned in multiple mode.
476 *
477 * @return true - opend.
478 * @return false - closed.
479 */
480 bool isConnected(uint8_t mux_id);
481
482 /**
483 * Get connection link status
484 *
485 * @return true - success.
486 * @return false - error.
487 */
488 bool getMuxCStatus(uint8_t *mux_id_ptn);
489
490 /**
491 * Rceive Buffer for each link.
492 */
493 ESP8266_RingBuffer rx_buffer[ESP8266_NUM_CONNECTION];
494
495 private:
496
497 /*
498 * Empty the buffer or UART RX.
499 */
500 void rx_empty(void);
501
502 /*
503 * Read all data in UART RX and store to Rceive Buffer .
504 */
505 void rx_update(void);
506
507 /*
508 * Recvive data from uart. Return all received data if one of target1, target2 and target3 found or timeout.
509 */
510 int recvString(String target1, String target2, String target3, uint32_t timeout = 1000);
511
512 /*
513 * Recvive data from uart and search first target. Return true if target found, false for timeout.
514 */
515 bool recvFind(String target, uint32_t timeout = 1000);
516
517 /*
518 * Recvive data from uart and search first target and cut out the substring between begin and end(excluding begin and end self). a
519 * Return true if target found, false for timeout.
520 */
521 bool recvFindAndFilter(String target, String begin, String end, String &data, uint32_t timeout = 1000);
522
523 /*
524 * Receive a package from uart.
525 *
526 * @param buffer - the buffer storing data.
527 * @param buffer_size - guess what!
528 * @param data_len - the length of data actually received(maybe more than buffer_size, the remained data will be abandoned).
529 * @param timeout - the duration waitting data comming.
530 * @param coming_mux_id - in single connection mode, should be NULL and not NULL in multiple.
531 */
532 uint32_t recvPkg(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout, uint8_t mux_id, uint8_t *coming_mux_id);
533
534 bool eAT(void);
535 bool eATRST(void);
536 bool eATGMR(String &version);
537
538 bool qATCWMODE_CUR(uint8_t *mode);
539 bool sATCWMODE_CUR(uint8_t mode);
540 bool sATCWJAP_CUR(String ssid, String pwd);
541 bool eATCWLAP(String &list);
542 bool eATCWQAP(void);
543 bool sATCWSAP_CUR(String ssid, String pwd, uint8_t chl, uint8_t ecn);
544 bool eATCWLIF(String &list);
545
546 bool eATCIPSTATUS(String &list);
547 bool sATCIPSTARTSingle(String type, String addr, uint32_t port);
548 bool sATCIPSTARTMultiple(uint8_t mux_id, String type, String addr, uint32_t port);
549 bool sATCIPSENDSingle(const uint8_t *buffer, uint32_t len);
550 bool sATCIPSENDMultiple(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
551 bool sATCIPSENDSingle(String &str);
552 bool sATCIPSENDMultiple(uint8_t mux_id, String &str);
553 bool sATCIPCLOSEMulitple(uint8_t mux_id);
554 bool eATCIPCLOSESingle(void);
555 bool eATCIFSR(String &list);
556 bool sATCIPMUX(uint8_t mode);
557 bool sATCIPSERVER(uint8_t mode, uint32_t port = 333);
558 bool sATCIPSTO(uint32_t timeout);
559
560 void initialize_status(void);
561
562 uint32_t recvIPD(uint32_t timeout, uint8_t *buffer = NULL, uint32_t buffer_size = 0,
563 uint8_t mux_id = 0, uint8_t *coming_mux_id = NULL);
564
565 void recvAsyncdata(uint32_t timeout = 0);
566
567#ifdef ESP8266_USE_SOFTWARE_SERIAL
568 SoftwareSerial *m_puart; /* The UART to communicate with ESP8266 */
569#else
570 HardwareSerial *m_puart; /* The UART to communicate with ESP8266 */
571#endif
572 uint32_t m_baud;
573
574 uint8_t wifi_status;
575
576 bool mux_mode;
577
578 uint8_t connection_bitmap;
579
580 esp8266_connection_status connection_status[ESP8266_NUM_CONNECTION];
581
582 String rx_cmd;
583};
584
585#endif /* #ifndef __ESP8266_H__ */
586
Note: See TracBrowser for help on using the repository browser.