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, int baud_rate=9600); /* 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      * @param pStatus - pointer to int for Status, decoded from status query 
00142      * @return the status. 
00143      */
00144     String getIPStatus(int *pStatus=NULL);
00145     
00146     /**
00147      * Get the IP address of ESP8266. 
00148      *
00149      * @return the IP list. 
00150      */
00151     String getLocalIP(void);
00152     
00153     /**
00154      * Enable IP MUX(multiple connection mode). 
00155      *
00156      * In multiple connection mode, a couple of TCP and UDP communication can be builded. 
00157      * They can be distinguished by the identifier of TCP or UDP named mux_id. 
00158      * 
00159      * @retval true - success.
00160      * @retval false - failure.
00161      */
00162     bool enableMUX(void);
00163     
00164     /**
00165      * Disable IP MUX(single connection mode). 
00166      *
00167      * In single connection mode, only one TCP or UDP communication can be builded. 
00168      * 
00169      * @retval true - success.
00170      * @retval false - failure.
00171      */
00172     bool disableMUX(void);
00173     
00174     
00175     /**
00176      * Create TCP connection in single mode. 
00177      * 
00178      * @param addr - the IP or domain name of the target host. 
00179      * @param port - the port number of the target host. 
00180      * @retval true - success.
00181      * @retval false - failure.
00182      */
00183     bool createTCP(String addr, uint32_t port);
00184     
00185     /**
00186      * Release TCP connection in single mode. 
00187      * 
00188      * @retval true - success.
00189      * @retval false - failure.
00190      */
00191     bool releaseTCP(void);
00192     
00193     /**
00194      * Register UDP port number in single mode.
00195      * 
00196      * @param addr - the IP or domain name of the target host. 
00197      * @param port - the port number of the target host. 
00198      * @retval true - success.
00199      * @retval false - failure.
00200      */
00201     bool registerUDP(String addr, uint32_t port);
00202     
00203     /**
00204      * Unregister UDP port number in single mode. 
00205      * 
00206      * @retval true - success.
00207      * @retval false - failure.
00208      */
00209     bool unregisterUDP(void);
00210   
00211     /**
00212      * Create TCP connection in multiple mode. 
00213      * 
00214      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00215      * @param addr - the IP or domain name of the target host. 
00216      * @param port - the port number of the target host. 
00217      * @retval true - success.
00218      * @retval false - failure.
00219      */
00220     bool createTCP(uint8_t mux_id, String addr, uint32_t port);
00221     
00222     /**
00223      * Release TCP connection in multiple mode. 
00224      * 
00225      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00226      * @retval true - success.
00227      * @retval false - failure.
00228      */
00229     bool releaseTCP(uint8_t mux_id);
00230     
00231     /**
00232      * Register UDP port number in multiple mode.
00233      * 
00234      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00235      * @param addr - the IP or domain name of the target host. 
00236      * @param port - the port number of the target host. 
00237      * @retval true - success.
00238      * @retval false - failure.
00239      */
00240     bool registerUDP(uint8_t mux_id, String addr, uint32_t port);
00241     
00242     /**
00243      * Unregister UDP port number in multiple mode. 
00244      * 
00245      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00246      * @retval true - success.
00247      * @retval false - failure.
00248      */
00249     bool unregisterUDP(uint8_t mux_id);
00250 
00251 
00252     /**
00253      * Set the timeout of TCP Server. 
00254      * 
00255      * @param timeout - the duration for timeout by second(0 ~ 28800, default:180). 
00256      * @retval true - success.
00257      * @retval false - failure.
00258      */
00259     bool setTCPServerTimeout(uint32_t timeout = 180);
00260     
00261     /**
00262      * Start TCP Server(Only in multiple mode). 
00263      * 
00264      * After started, user should call method: getIPStatus to know the status of TCP connections. 
00265      * The methods of receiving data can be called for user's any purpose. After communication, 
00266      * release the TCP connection is needed by calling method: releaseTCP with mux_id. 
00267      *
00268      * @param port - the port number to listen(default: 333).
00269      * @retval true - success.
00270      * @retval false - failure.
00271      *
00272      * @see String getIPStatus(void);
00273      * @see uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t len, uint32_t timeout);
00274      * @see bool releaseTCP(uint8_t mux_id);
00275      */
00276     bool startTCPServer(uint32_t port = 333);
00277 
00278     /**
00279      * Stop TCP Server(Only in multiple mode). 
00280      * 
00281      * @retval true - success.
00282      * @retval false - failure.
00283      */
00284     bool stopTCPServer(void);
00285 
00286     /**
00287      * Send data based on TCP or UDP builded already in single mode. 
00288      * 
00289      * @param buffer - the buffer of data to send. 
00290      * @param len - the length of data to send. 
00291      * @retval true - success.
00292      * @retval false - failure.
00293      */
00294     bool send(const uint8_t *buffer, uint32_t len);
00295             
00296     /**
00297      * Send data based on one of TCP or UDP builded already in multiple mode. 
00298      * 
00299      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00300      * @param buffer - the buffer of data to send. 
00301      * @param len - the length of data to send. 
00302      * @retval true - success.
00303      * @retval false - failure.
00304      */
00305     bool send(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00306     
00307     /**
00308      * Receive data from TCP or UDP builded already in single mode. 
00309      *
00310      * @param buffer - the buffer for storing data. 
00311      * @param buffer_size - the length of the buffer. 
00312      * @param timeout - the time waiting data. 
00313      * @return the length of data received actually. 
00314      */
00315     uint32_t recv(uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00316     
00317     /**
00318      * Receive data from one of TCP or UDP builded already in multiple mode. 
00319      *
00320      * @param mux_id - the identifier of this TCP(available value: 0 - 4). 
00321      * @param buffer - the buffer for storing data. 
00322      * @param buffer_size - the length of the buffer. 
00323      * @param timeout - the time waiting data. 
00324      * @return the length of data received actually. 
00325      */
00326     uint32_t recv(uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00327     
00328     /**
00329      * Receive data from all of TCP or UDP builded already in multiple mode. 
00330      *
00331      * After return, coming_mux_id store the id of TCP or UDP from which data coming. 
00332      * User should read the value of coming_mux_id and decide what next to do. 
00333      * 
00334      * @param coming_mux_id - the identifier of TCP or UDP. 
00335      * @param buffer - the buffer for storing data. 
00336      * @param buffer_size - the length of the buffer. 
00337      * @param timeout - the time waiting data. 
00338      * @return the length of data received actually. 
00339      */
00340     uint32_t recv(uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout = 1000);
00341 
00342  private:
00343     /* 
00344      * Recvive data from uart. Return all received data if target found or timeout. 
00345      */
00346     String recvString(String target, uint32_t timeout = 1000);
00347     
00348     /* 
00349      * Recvive data from uart. Return all received data if one of target1 and target2 found or timeout. 
00350      */
00351     String recvString(String target1, String target2, uint32_t timeout = 1000);
00352     
00353     /* 
00354      * Recvive data from uart. Return all received data if one of target1, target2 and target3 found or timeout. 
00355      */
00356     String recvString(String target1, String target2, String target3, uint32_t timeout = 1000);
00357     
00358     /* 
00359      * Recvive data from uart and search first target. Return true if target found, false for timeout.
00360      */
00361     bool recvFind(String target, uint32_t timeout = 1000);
00362     
00363     /* 
00364      * Recvive data from uart and search first target and cut out the substring between begin and end(excluding begin and end self). 
00365      * Return true if target found, false for timeout.
00366      */
00367     bool recvFindAndFilter(String target, String begin, String end, String &data, uint32_t timeout = 1000);
00368     
00369     /*
00370      * Receive a package from uart. 
00371      *
00372      * @param buffer - the buffer storing data. 
00373      * @param buffer_size - guess what!
00374      * @param data_len - the length of data actually received(maybe more than buffer_size, the remained data will be abandoned).
00375      * @param timeout - the duration waitting data comming.
00376      * @param coming_mux_id - in single connection mode, should be NULL and not NULL in multiple. 
00377      */
00378     uint32_t recvPkg(uint8_t *buffer, uint32_t buffer_size, uint32_t *data_len, uint32_t timeout, uint8_t *coming_mux_id);
00379     
00380     
00381     bool eAT(void);
00382     bool eATRST(void);
00383     bool eATGMR(String &version);
00384     
00385     bool qATCWMODE(uint8_t *mode);
00386     bool sATCWMODE(uint8_t mode);
00387     bool sATCWJAP(String ssid, String pwd);
00388     bool eATCWLAP(String &list);
00389     bool eATCWQAP(void);
00390     bool sATCWSAP(String ssid, String pwd, uint8_t chl, uint8_t ecn);
00391     bool eATCWLIF(String &list);
00392     
00393     bool eATCIPSTATUS(String &list, int *pStatus=NULL);
00394     bool sATCIPSTARTSingle(String type, String addr, uint32_t port);
00395     bool sATCIPSTARTMultiple(uint8_t mux_id, String type, String addr, uint32_t port);
00396     bool sATCIPSENDSingle(const uint8_t *buffer, uint32_t len);
00397     bool sATCIPSENDMultiple(uint8_t mux_id, const uint8_t *buffer, uint32_t len);
00398     bool sATCIPCLOSEMulitple(uint8_t mux_id);
00399     bool eATCIPCLOSESingle(void);
00400     bool eATCIFSR(String &list);
00401     bool sATCIPMUX(uint8_t mode);
00402     bool sATCIPSERVER(uint8_t mode, uint32_t port = 333);
00403     bool sATCIPSTO(uint32_t timeout);
00404     
00405     /*
00406      * +IPD,len:data
00407      * +IPD,id,len:data
00408      */
00409     
00410     
00411     ArduinoSerial *m_puart; /* The UART to communicate with ESP8266 */
00412  
00413 };
00414 
00415 #endif /* #ifndef __ESP8266_H__ */