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     // funkcja do czyszczenia bufora (flush tylko zwalnia pamięć, a dużo zer ją wyzeruje)
00040     void clear_serial();
00041     
00042     /** 
00043      * Verify ESP8266 whether live or not. 
00044      *
00045      * Actually, this method will send command "AT" to ESP8266 and waiting for "OK". 
00046      * 
00047      * @retval true - alive.
00048      * @retval false - dead.
00049      */ 
00050     bool kick(void);
00051     
00052     /**
00053      * Restart ESP8266 by "AT+RST". 
00054      *
00055      * This method will take 3 seconds or more. 
00056      *
00057      * @retval true - success.
00058      * @retval false - failure.
00059      */
00060     bool restart(void);
00061     
00062     /**
00063      * Get the version of AT Command Set. 
00064      * 
00065      * @return the string of version. 
00066      */
00067     String getVersion(void);
00068     
00069     /**
00070      * Set operation mode to staion. 
00071      * 
00072      * @retval true - success.
00073      * @retval false - failure.
00074      */
00075     bool setOprToStation(void);
00076     
00077     /**
00078      * Set operation mode to softap. 
00079      * 
00080      * @retval true - success.
00081      * @retval false - failure.
00082      */
00083     bool setOprToSoftAP(void);
00084     
00085     /**
00086      * Set operation mode to station + softap. 
00087      * 
00088      * @retval true - success.
00089      * @retval false - failure.
00090      */
00091     bool setOprToStationSoftAP(void);
00092     
00093     /**
00094      * Search available AP list and return it.
00095      * 
00096      * @return the list of available APs. 
00097      * @note This method will occupy a lot of memeory(hundreds of Bytes to a couple of KBytes). 
00098      *  Do not call this method unless you must and ensure that your board has enough memery left.
00099      */
00100     String getAPList(void);
00101     
00102     /**
00103      * Join in AP. 
00104      *
00105      * @param ssid - SSID of AP to join in. 
00106      * @param pwd - Password of AP to join in. 
00107      * @retval true - success.
00108      * @retval false - failure.
00109      * @note This method will take a couple of seconds. 
00110      */
00111     bool joinAP(String ssid, String pwd);
00112     
00113     /**
00114      * Leave AP joined before. 
00115      *
00116      * @retval true - success.
00117      * @retval false - failure.
00118      */
00119     bool leaveAP(void);
00120     
00121     /**
00122      * Set SoftAP parameters. 
00123      * 
00124      * @param ssid - SSID of SoftAP. 
00125      * @param pwd - PASSWORD of SoftAP. 
00126      * @param chl - the channel (1 - 13, default: 7). 
00127      * @param ecn - the way of encrypstion (0 - OPEN, 1 - WEP, 
00128      *  2 - WPA_PSK, 3 - WPA2_PSK, 4 - WPA_WPA2_PSK, default: 4). 
00129      * @note This method should not be called when station mode. 
00130      */
00131     bool setSoftAPParam(String ssid, String pwd, uint8_t chl = 7, uint8_t ecn = 4);
00132     
00133     /**
00134      * Get the IP list of devices connected to SoftAP. 
00135      * 
00136      * @return the list of IP.
00137      * @note This method should not be called when station mode. 
00138      */
00139     String getJoinedDeviceIP(void);
00140     
00141     /**
00142      * Get the current status of connection(UDP and TCP). 
00143      * 
00144      * @return the status. 
00145      true - connected
00146      false - disconnected
00147      */
00148     int getIPStatus(void);
00149     
00150     /**
00151      * Get the IP address of ESP8266. 
00152      *
00153      * @return the IP list. 
00154      */
00155     String getLocalIP(void);
00156     
00157     /**
00158      * Enable IP MUX(multiple connection mode). 
00159      *
00160      * In multiple connection mode, a couple of TCP and UDP communication can be builded. 
00161      * They can be distinguished by the identifier of TCP or UDP named mux_id. 
00162      * 
00163      * @retval true - success.
00164      * @retval false - failure.
00165      */
00166     bool enableMUX(void);
00167     
00168     /**
00169      * Disable IP MUX(single connection mode). 
00170      *
00171      * In single connection mode, only one TCP or UDP communication can be builded. 
00172      * 
00173      * @retval true - success.
00174      * @retval false - failure.
00175      */
00176     bool disableMUX(void);
00177     
00178     
00179     /**
00180      * Create TCP connection in single mode. 
00181      * 
00182      * @param addr - the IP or domain name of the target host. 
00183      * @param port - the port number of the target host. 
00184      * @retval true - success.
00185      * @retval false - failure.
00186      */
00187     bool createTCP(String addr, uint32_t port);
00188     
00189     /**
00190      * Release TCP connection in single mode. 
00191      * 
00192      * @retval true - success.
00193      * @retval false - failure.
00194      */
00195     bool releaseTCP(void);
00196     
00197     /**
00198      * Register UDP port number in single mode.
00199      * 
00200      * @param addr - the IP or domain name of the target host. 
00201      * @param port - the port number of the target host. 
00202      * @retval true - success.
00203      * @retval false - failure.
00204      */
00205     bool registerUDP(String addr, uint32_t port);
00206     
00207     /**
00208      * Unregister UDP port number in single mode. 
00209      * 
00210      * @retval true - success.
00211      * @retval false - failure.
00212      */
00213     bool unregisterUDP(void);
00214   
00215     /**
00216      * Create TCP connection in multiple mode. 
00217      * 
00218      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00219      * @param addr - the IP or domain name of the target host. 
00220      * @param port - the port number of the target host. 
00221      * @retval true - success.
00222      * @retval false - failure.
00223      */
00224     bool createTCP(uint8_t mux_id, String addr, uint32_t port);
00225     
00226     /**
00227      * Release TCP connection in multiple mode. 
00228      * 
00229      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00230      * @retval true - success.
00231      * @retval false - failure.
00232      */
00233     bool releaseTCP(uint8_t mux_id);
00234     
00235     /**
00236      * Register UDP port number in multiple mode.
00237      * 
00238      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00239      * @param addr - the IP or domain name of the target host. 
00240      * @param port - the port number of the target host. 
00241      * @retval true - success.
00242      * @retval false - failure.
00243      */
00244     bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
00245     
00246     /**
00247      * Unregister UDP port number in multiple mode. 
00248      * 
00249      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00250      * @retval true - success.
00251      * @retval false - failure.
00252      */
00253     bool unregisterUDP(uint8_t mux_id);
00254 
00255 
00256     /**
00257      * Set the timeout of TCP Server. 
00258      * 
00259      * @param timeout - the duration for timeout by second(0 ~ 28800, default:180). 
00260      * @retval true - success.
00261      * @retval false - failure.
00262      */
00263     bool setTCPServerTimeout(uint32_t timeout = 180);
00264     
00265     /**
00266      * Start TCP Server(Only in multiple mode). 
00267      * 
00268      * After started, user should call method: getIPStatus to know the status of TCP connections. 
00269      * The methods of receiving data can be called for user's any purpose. After communication, 
00270      * release the TCP connection is needed by calling method: releaseTCP with mux_id. 
00271      *
00272      * @param port - the port number to listen(default: 333).
00273      * @retval true - success.
00274      * @retval false - failure.
00275      *
00276      * @see String getIPStatus(void);
00277      * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
00278      * @see bool releaseTCP(uint8_t mux_id);
00279      */
00280     bool startTCPServer(uint32_t port = 333);
00281 
00282     /**
00283      * Stop TCP Server(Only in multiple mode). 
00284      * 
00285      * @retval true - success.
00286      * @retval false - failure.
00287      */
00288     bool stopTCPServer(void);
00289 
00290     /**
00291      * Send data based on TCP or UDP builded already in single mode. 
00292      * 
00293      * @param buffer - the buffer of data to send. 
00294      * @param len - the length of data to send. 
00295      * @retval true - success.
00296      * @retval false - failure.
00297      */
00298     bool send(const uint8_t *buffer, uint32_t len);
00299             
00300     /**
00301      * Send data based on one of TCP or UDP builded already in multiple mode. 
00302      * 
00303      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00304      * @param buffer - the buffer of data to send. 
00305      * @param len - the length of data to send. 
00306      * @retval true - success.
00307      * @retval false - failure.
00308      */
00309     bool send(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00310     
00311     /**
00312      * Receive data from TCP or UDP builded already in single mode. 
00313      *
00314      * @param buffer - the buffer for storing data. 
00315      * @param buffer_size - the length of the buffer. 
00316      * @param timeout - the time waiting data. 
00317      * @return the length of data received actually. 
00318      */
00319     uint32_t recv(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00320     
00321     /**
00322      * Receive data from one of TCP or UDP builded already in multiple mode. 
00323      *
00324      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00325      * @param buffer - the buffer for storing data. 
00326      * @param buffer_size - the length of the buffer. 
00327      * @param timeout - the time waiting data. 
00328      * @return the length of data received actually. 
00329      */
00330     uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00331     
00332     /**
00333      * Receive data from all of TCP or UDP builded already in multiple mode. 
00334      *
00335      * After return, coming_mux_id store the id of TCP or UDP from which data coming. 
00336      * User should read the value of coming_mux_id and decide what next to do. 
00337      * 
00338      * @param coming_mux_id - the identifier of TCP or UDP. 
00339      * @param buffer - the buffer for storing data. 
00340      * @param buffer_size - the length of the buffer. 
00341      * @param timeout - the time waiting data. 
00342      * @return the length of data received actually. 
00343      */
00344     uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00345 
00346  private:
00347     /* 
00348      * Recvive data from uart. Return all received data if target found or timeout. 
00349      */
00350     String recvString(String target, uint32_t timeout = 1000);
00351     
00352     /* 
00353      * Recvive data from uart. Return all received data if one of target1 and target2 found or timeout. 
00354      */
00355     String recvString(String target1, String target2, uint32_t timeout = 1000);
00356     
00357     /* 
00358      * Recvive data from uart. Return all received data if one of target1, target2 and target3 found or timeout. 
00359      */
00360     String recvString(String target1, String target2, String target3, uint32_t timeout = 1000);
00361     
00362     /* 
00363      * Recvive data from uart and search first target. Return true if target found, false for timeout.
00364      */
00365     bool recvFind(String target, uint32_t timeout = 1000);
00366     
00367     /* 
00368      * Recvive data from uart and search first target and cut out the substring between begin and end(excluding begin and end self). 
00369      * Return true if target found, false for timeout.
00370      */
00371     bool recvFindAndFilter(String target, String begin, String end, String &data, uint32_t timeout = 1000);
00372     
00373     /*
00374      * Receive a package from uart. 
00375      *
00376      * @param buffer - the buffer storing data. 
00377      * @param buffer_size - guess what!
00378      * @param data_len - the length of data actually received(maybe more than buffer_size, the remained data will be abandoned).
00379      * @param timeout - the duration waitting data comming.
00380      * @param coming_mux_id - in single connection mode, should be NULL and not NULL in multiple. 
00381      */
00382     uint32_t recvPkg(uint8_t *buffer, uint32_t buffer_size, uint32_t *data_len, uint32_t timeout, uint8_t *coming_mux_id);
00383     
00384     
00385     bool eAT(void);
00386     bool eATRST(void);
00387     bool eATGMR(String &version);
00388     
00389     bool qATCWMODE(uint8_t *mode);
00390     bool sATCWMODE(uint8_t mode);
00391     bool sATCWJAP(String ssid, String pwd);
00392     bool eATCWLAP(String &list);
00393     bool eATCWQAP(void);
00394     bool sATCWSAP(String ssid, String pwd, uint8_t chl, uint8_t ecn);
00395     bool eATCWLIF(String &list);
00396     
00397     bool eATCIPSTATUS(String &list);
00398     bool sATCIPSTARTSingle(String type, String addr, uint32_t port);
00399     bool sATCIPSTARTMultiple(uint8_t mux_id, String type, String addr, uint32_t port);
00400     bool sATCIPSENDSingle(const uint8_t *buffer, uint32_t len);
00401     bool sATCIPSENDMultiple(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00402     bool sATCIPCLOSEMulitple(uint8_t mux_id);
00403     bool eATCIPCLOSESingle(void);
00404     bool eATCIFSR(String &list);
00405     bool sATCIPMUX(uint8_t mode);
00406     bool sATCIPSERVER(uint8_t mode, uint32_t port = 333);
00407     bool sATCIPSTO(uint32_t timeout);
00408     
00409     /*
00410      * +IPD,len:data
00411      * +IPD,id,len:data
00412      */
00413     
00414     
00415     ArduinoSerial *m_puart; /* The UART to communicate with ESP8266 */
00416  
00417 };
00418 
00419 #endif /* #ifndef __ESP8266_H__ */