ESP8266.h

00001 /**
00002  * @file ESP8266.h
00003  * @brief The definition of class ESP8266. 
00004  * @author Wu Pengfei<pengfei.wu@itead.cc> 
00005  * @date 2015.02
00006  * 
00007  * @par Copyright:
00008  * Copyright (c) 2015 ITEAD Intelligent Systems Co., Ltd. \n\n
00009  * This program is free software; you can redistribute it and/or
00010  * modify it under the terms of the GNU General Public License as
00011  * published by the Free Software Foundation; either version 2 of
00012  * the License, or (at your option) any later version. \n\n
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00014  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00015  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00016  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00017  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00018  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00019  * THE SOFTWARE.
00020  */
00021 #ifndef __ESP8266_H__
00022 #define __ESP8266_H__
00023 
00024 #include "ArduinoAPI.h"
00025 
00026 /**
00027  * Provide an easy-to-use way to manipulate ESP8266. 
00028  */
00029 class ESP8266 {
00030  public:
00031  
00032     /**
00033      * Constuctor. 
00034      *
00035      * @param uart - an reference of ArduinoSerial object with baud 9600. 
00036      */
00037     ESP8266(ArduinoSerial &uart); /* baud rate is 9600 */
00038     
00039     /** 
00040      * Verify ESP8266 whether live or not. 
00041      *
00042      * Actually, this method will send command "AT" to ESP8266 and waiting for "OK". 
00043      * 
00044      * @retval true - alive.
00045      * @retval false - dead.
00046      */
00047     bool kick(void);
00048     
00049     /**
00050      * Restart ESP8266 by "AT+RST". 
00051      *
00052      * This method will take 3 seconds or more. 
00053      *
00054      * @retval true - success.
00055      * @retval false - failure.
00056      */
00057     bool restart(void);
00058     
00059     /**
00060      * Get the version of AT Command Set. 
00061      * 
00062      * @return the string of version. 
00063      */
00064     String getVersion(void);
00065     
00066     /**
00067      * Set operation mode to staion. 
00068      * 
00069      * @retval true - success.
00070      * @retval false - failure.
00071      */
00072     bool setOprToStation(void);
00073     
00074     /**
00075      * Set operation mode to softap. 
00076      * 
00077      * @retval true - success.
00078      * @retval false - failure.
00079      */
00080     bool setOprToSoftAP(void);
00081     
00082     /**
00083      * Set operation mode to station + softap. 
00084      * 
00085      * @retval true - success.
00086      * @retval false - failure.
00087      */
00088     bool setOprToStationSoftAP(void);
00089     
00090     /**
00091      * Search available AP list and return it.
00092      * 
00093      * @return the list of available APs. 
00094      * @note This method will occupy a lot of memeory(hundreds of Bytes to a couple of KBytes). 
00095      *  Do not call this method unless you must and ensure that your board has enough memery left.
00096      */
00097     String getAPList(void);
00098     
00099     /**
00100      * Join in AP. 
00101      *
00102      * @param ssid - SSID of AP to join in. 
00103      * @param pwd - Password of AP to join in. 
00104      * @retval true - success.
00105      * @retval false - failure.
00106      * @note This method will take a couple of seconds. 
00107      */
00108     bool joinAP(String ssid, String pwd);
00109     
00110     /**
00111      * Leave AP joined before. 
00112      *
00113      * @retval true - success.
00114      * @retval false - failure.
00115      */
00116     bool leaveAP(void);
00117     
00118     /**
00119      * Set SoftAP parameters. 
00120      * 
00121      * @param ssid - SSID of SoftAP. 
00122      * @param pwd - PASSWORD of SoftAP. 
00123      * @param chl - the channel (1 - 13, default: 7). 
00124      * @param ecn - the way of encrypstion (0 - OPEN, 1 - WEP, 
00125      *  2 - WPA_PSK, 3 - WPA2_PSK, 4 - WPA_WPA2_PSK, default: 4). 
00126      * @note This method should not be called when station mode. 
00127      */
00128     bool setSoftAPParam(String ssid, String pwd, uint8_t chl = 7, uint8_t ecn = 4);
00129     
00130     /**
00131      * Get the IP list of devices connected to SoftAP. 
00132      * 
00133      * @return the list of IP.
00134      * @note This method should not be called when station mode. 
00135      */
00136     String getJoinedDeviceIP(void);
00137     
00138     /**
00139      * Get the current status of connection(UDP and TCP). 
00140      * 
00141      * @return the status. 
00142      */
00143     String getIPStatus(void);
00144     
00145     /**
00146      * Get the IP address of ESP8266. 
00147      *
00148      * @return the IP list. 
00149      */
00150     String getLocalIP(void);
00151     
00152     /**
00153      * Enable IP MUX(multiple connection mode). 
00154      *
00155      * In multiple connection mode, a couple of TCP and UDP communication can be builded. 
00156      * They can be distinguished by the identifier of TCP or UDP named mux_id. 
00157      * 
00158      * @retval true - success.
00159      * @retval false - failure.
00160      */
00161     bool enableMUX(void);
00162     
00163     /**
00164      * Disable IP MUX(single connection mode). 
00165      *
00166      * In single connection mode, only one TCP or UDP communication can be builded. 
00167      * 
00168      * @retval true - success.
00169      * @retval false - failure.
00170      */
00171     bool disableMUX(void);
00172     
00173     
00174     /**
00175      * Create TCP connection in single mode. 
00176      * 
00177      * @param addr - the IP or domain name of the target host. 
00178      * @param port - the port number of the target host. 
00179      * @retval true - success.
00180      * @retval false - failure.
00181      */
00182     bool createTCP(String addr, uint32_t port);
00183     
00184     /**
00185      * Release TCP connection in single mode. 
00186      * 
00187      * @retval true - success.
00188      * @retval false - failure.
00189      */
00190     bool releaseTCP(void);
00191     
00192     /**
00193      * Register UDP port number in single mode.
00194      * 
00195      * @param addr - the IP or domain name of the target host. 
00196      * @param port - the port number of the target host. 
00197      * @retval true - success.
00198      * @retval false - failure.
00199      */
00200     bool registerUDP(String addr, uint32_t port);
00201     
00202     /**
00203      * Unregister UDP port number in single mode. 
00204      * 
00205      * @retval true - success.
00206      * @retval false - failure.
00207      */
00208     bool unregisterUDP(void);
00209   
00210     /**
00211      * Create TCP connection in multiple mode. 
00212      * 
00213      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00214      * @param addr - the IP or domain name of the target host. 
00215      * @param port - the port number of the target host. 
00216      * @retval true - success.
00217      * @retval false - failure.
00218      */
00219     bool createTCP(uint8_t mux_id, String addr, uint32_t port);
00220     
00221     /**
00222      * Release TCP connection in multiple mode. 
00223      * 
00224      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00225      * @retval true - success.
00226      * @retval false - failure.
00227      */
00228     bool releaseTCP(uint8_t mux_id);
00229     
00230     /**
00231      * Register UDP port number in multiple mode.
00232      * 
00233      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00234      * @param addr - the IP or domain name of the target host. 
00235      * @param port - the port number of the target host. 
00236      * @retval true - success.
00237      * @retval false - failure.
00238      */
00239     bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
00240     
00241     /**
00242      * Unregister UDP port number in multiple mode. 
00243      * 
00244      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00245      * @retval true - success.
00246      * @retval false - failure.
00247      */
00248     bool unregisterUDP(uint8_t mux_id);
00249 
00250 
00251     /**
00252      * Set the timeout of TCP Server. 
00253      * 
00254      * @param timeout - the duration for timeout by second(0 ~ 28800, default:180). 
00255      * @retval true - success.
00256      * @retval false - failure.
00257      */
00258     bool setTCPServerTimeout(uint32_t timeout = 180);
00259     
00260     /**
00261      * Start TCP Server(Only in multiple mode). 
00262      * 
00263      * After started, user should call method: getIPStatus to know the status of TCP connections. 
00264      * The methods of receiving data can be called for user's any purpose. After communication, 
00265      * release the TCP connection is needed by calling method: releaseTCP with mux_id. 
00266      *
00267      * @param port - the port number to listen(default: 333).
00268      * @retval true - success.
00269      * @retval false - failure.
00270      *
00271      * @see String getIPStatus(void);
00272      * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
00273      * @see bool releaseTCP(uint8_t mux_id);
00274      */
00275     bool startTCPServer(uint32_t port = 333);
00276 
00277     /**
00278      * Stop TCP Server(Only in multiple mode). 
00279      * 
00280      * @retval true - success.
00281      * @retval false - failure.
00282      */
00283     bool stopTCPServer(void);
00284 
00285     /**
00286      * Send data based on TCP or UDP builded already in single mode. 
00287      * 
00288      * @param buffer - the buffer of data to send. 
00289      * @param len - the length of data to send. 
00290      * @retval true - success.
00291      * @retval false - failure.
00292      */
00293     bool send(const uint8_t *buffer, uint32_t len);
00294             
00295     /**
00296      * Send data based on one of TCP or UDP builded already in multiple mode. 
00297      * 
00298      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00299      * @param buffer - the buffer of data to send. 
00300      * @param len - the length of data to send. 
00301      * @retval true - success.
00302      * @retval false - failure.
00303      */
00304     bool send(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00305     
00306     /**
00307      * Receive data from TCP or UDP builded already in single mode. 
00308      *
00309      * @param buffer - the buffer for storing data. 
00310      * @param buffer_size - the length of the buffer. 
00311      * @param timeout - the time waiting data. 
00312      * @return the length of data received actually. 
00313      */
00314     uint32_t recv(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00315     
00316     /**
00317      * Receive data from one of TCP or UDP builded already in multiple mode. 
00318      *
00319      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00320      * @param buffer - the buffer for storing data. 
00321      * @param buffer_size - the length of the buffer. 
00322      * @param timeout - the time waiting data. 
00323      * @return the length of data received actually. 
00324      */
00325     uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00326     
00327     /**
00328      * Receive data from all of TCP or UDP builded already in multiple mode. 
00329      *
00330      * After return, coming_mux_id store the id of TCP or UDP from which data coming. 
00331      * User should read the value of coming_mux_id and decide what next to do. 
00332      * 
00333      * @param coming_mux_id - the identifier of TCP or UDP. 
00334      * @param buffer - the buffer for storing data. 
00335      * @param buffer_size - the length of the buffer. 
00336      * @param timeout - the time waiting data. 
00337      * @return the length of data received actually. 
00338      */
00339     uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00340 
00341  private:
00342     /* 
00343      * Recvive data from uart. Return all received data if target found or timeout. 
00344      */
00345     String recvString(String target, uint32_t timeout = 1000);
00346     
00347     /* 
00348      * Recvive data from uart. Return all received data if one of target1 and target2 found or timeout. 
00349      */
00350     String recvString(String target1, String target2, uint32_t timeout = 1000);
00351     
00352     /* 
00353      * Recvive data from uart. Return all received data if one of target1, target2 and target3 found or timeout. 
00354      */
00355     String recvString(String target1, String target2, String target3, uint32_t timeout = 1000);
00356     
00357     /* 
00358      * Recvive data from uart and search first target. Return true if target found, false for timeout.
00359      */
00360     bool recvFind(String target, uint32_t timeout = 1000);
00361     
00362     /* 
00363      * Recvive data from uart and search first target and cut out the substring between begin and end(excluding begin and end self). 
00364      * Return true if target found, false for timeout.
00365      */
00366     bool recvFindAndFilter(String target, String begin, String end, String &data, uint32_t timeout = 1000);
00367     
00368     /*
00369      * Receive a package from uart. 
00370      *
00371      * @param buffer - the buffer storing data. 
00372      * @param buffer_size - guess what!
00373      * @param data_len - the length of data actually received(maybe more than buffer_size, the remained data will be abandoned).
00374      * @param timeout - the duration waitting data comming.
00375      * @param coming_mux_id - in single connection mode, should be NULL and not NULL in multiple. 
00376      */
00377     uint32_t recvPkg(uint8_t *buffer, uint32_t buffer_size, uint32_t *data_len, uint32_t timeout, uint8_t *coming_mux_id);
00378     
00379     
00380     bool eAT(void);
00381     bool eATRST(void);
00382     bool eATGMR(String &version);
00383     
00384     bool qATCWMODE(uint8_t *mode);
00385     bool sATCWMODE(uint8_t mode);
00386     bool sATCWJAP(String ssid, String pwd);
00387     bool eATCWLAP(String &list);
00388     bool eATCWQAP(void);
00389     bool sATCWSAP(String ssid, String pwd, uint8_t chl, uint8_t ecn);
00390     bool eATCWLIF(String &list);
00391     
00392     bool eATCIPSTATUS(String &list);
00393     bool sATCIPSTARTSingle(String type, String addr, uint32_t port);
00394     bool sATCIPSTARTMultiple(uint8_t mux_id, String type, String addr, uint32_t port);
00395     bool sATCIPSENDSingle(const uint8_t *buffer, uint32_t len);
00396     bool sATCIPSENDMultiple(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00397     bool sATCIPCLOSEMulitple(uint8_t mux_id);
00398     bool eATCIPCLOSESingle(void);
00399     bool eATCIFSR(String &list);
00400     bool sATCIPMUX(uint8_t mode);
00401     bool sATCIPSERVER(uint8_t mode, uint32_t port = 333);
00402     bool sATCIPSTO(uint32_t timeout);
00403     
00404     /*
00405      * +IPD,len:data
00406      * +IPD,id,len:data
00407      */
00408     
00409     
00410     ArduinoSerial *m_puart; /* The UART to communicate with ESP8266 */
00411  
00412 };
00413 
00414 #endif /* #ifndef __ESP8266_H__ */