ESP8266.h

00001 /* ESP8266Interface Example
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef ESP8266_H
00018 #define ESP8266_H
00019 
00020 #include "ATCmdParser.h"
00021 #include "nsapi_types.h"
00022 #include "rtos.h"
00023 
00024 // Various timeouts for different ESP8266 operations
00025 #ifndef ESP8266_CONNECT_TIMEOUT
00026 #define ESP8266_CONNECT_TIMEOUT 15000
00027 #endif
00028 #ifndef ESP8266_SEND_TIMEOUT
00029 #define ESP8266_SEND_TIMEOUT    2000
00030 #endif
00031 #ifndef ESP8266_RECV_TIMEOUT
00032 #define ESP8266_RECV_TIMEOUT    2000
00033 #endif
00034 #ifndef ESP8266_MISC_TIMEOUT
00035 #define ESP8266_MISC_TIMEOUT    2000
00036 #endif
00037 
00038 /** ESP8266Interface class.
00039     This is an interface to a ESP8266 radio.
00040  */
00041 class ESP8266
00042 {
00043 public:
00044     ESP8266(PinName tx, PinName rx, bool debug=false);
00045 
00046     /**
00047     * Check firmware version of ESP8266
00048     *
00049     * @return integer firmware version or -1 if firmware query command gives outdated response
00050     */
00051     int get_firmware_version(void);
00052     
00053     /**
00054     * Startup the ESP8266
00055     *
00056     * @param mode mode of WIFI 1-client, 2-host, 3-both
00057     * @return true only if ESP8266 was setup correctly
00058     */
00059     bool startup(int mode);
00060 
00061     /**
00062     * Reset ESP8266
00063     *
00064     * @return true only if ESP8266 resets successfully
00065     */
00066     bool reset(void);
00067 
00068     /**
00069     * Enable/Disable DHCP
00070     *
00071     * @param enabled DHCP enabled when true
00072     * @param mode mode of DHCP 0-softAP, 1-station, 2-both
00073     * @return true only if ESP8266 enables/disables DHCP successfully
00074     */
00075     bool dhcp(bool enabled, int mode);
00076 
00077     /**
00078     * Connect ESP8266 to AP
00079     *
00080     * @param ap the name of the AP
00081     * @param passPhrase the password of AP
00082     * @return NSAPI_ERROR_OK only if ESP8266 is connected successfully
00083     */
00084     nsapi_error_t connect(const char *ap, const char *passPhrase);
00085 
00086     /**
00087     * Disconnect ESP8266 from AP
00088     *
00089     * @return true only if ESP8266 is disconnected successfully
00090     */
00091     bool disconnect(void);
00092 
00093     /**
00094     * Get the IP address of ESP8266
00095     *
00096     * @return null-teriminated IP address or null if no IP address is assigned
00097     */
00098     const char *getIPAddress(void);
00099 
00100     /**
00101     * Get the MAC address of ESP8266
00102     *
00103     * @return null-terminated MAC address or null if no MAC address is assigned
00104     */
00105     const char *getMACAddress(void);
00106 
00107      /** Get the local gateway
00108      *
00109      *  @return         Null-terminated representation of the local gateway
00110      *                  or null if no network mask has been recieved
00111      */
00112     const char *getGateway();
00113 
00114     /** Get the local network mask
00115      *
00116      *  @return         Null-terminated representation of the local network mask 
00117      *                  or null if no network mask has been recieved
00118      */
00119     const char *getNetmask();
00120 
00121     /* Return RSSI for active connection
00122      *
00123      * @return      Measured RSSI
00124      */
00125     int8_t getRSSI();
00126 
00127     /** Scan for available networks
00128      *
00129      * @param  ap    Pointer to allocated array to store discovered AP
00130      * @param  limit Size of allocated @a res array, or 0 to only count available AP
00131      * @return       Number of entries in @a res, or if @a count was 0 number of available networks, negative on error
00132      *               see @a nsapi_error
00133      */
00134     int scan(WiFiAccessPoint *res, unsigned limit);
00135     
00136     /**Perform a dns query
00137     *
00138     * @param name Hostname to resolve
00139     * @param ip   Buffer to store IP address
00140     * @return 0 true on success, false on failure
00141     */
00142     bool dns_lookup(const char *name, char *ip);
00143 
00144     /**
00145     * Open a socketed connection
00146     *
00147     * @param type the type of socket to open "UDP" or "TCP"
00148     * @param id id to give the new socket, valid 0-4
00149     * @param port port to open connection with
00150     * @param addr the IP address of the destination
00151     * @param port the port on the destination
00152     * @param local_port UDP socket's local port, zero means any
00153     * @return true only if socket opened successfully
00154     */
00155     nsapi_error_t open_udp(int id, const char* addr, int port, int local_port = 0);
00156 
00157     /**
00158     * Open a socketed connection
00159     *
00160     * @param type the type of socket to open "UDP" or "TCP"
00161     * @param id id to give the new socket, valid 0-4
00162     * @param port port to open connection with
00163     * @param addr the IP address of the destination
00164     * @param port the port on the destination
00165     * @param tcp_keepalive TCP connection's keep alive time, zero means disabled
00166     * @return true only if socket opened successfully
00167     */
00168     bool open_tcp(int id, const char* addr, int port, int keepalive = 0);
00169 
00170     /**
00171     * Sends data to an open socket
00172     *
00173     * @param id id of socket to send to
00174     * @param data data to be sent
00175     * @param amount amount of data to be sent - max 1024
00176     * @return NSAPI_ERROR_OK in success, negative error code in failure
00177     */
00178     nsapi_error_t send(int id, const void *data, uint32_t amount);
00179 
00180     /**
00181     * Receives datagram from an open UDP socket
00182     *
00183     * @param id id to receive from
00184     * @param data placeholder for returned information
00185     * @param amount number of bytes to be received
00186     * @return the number of bytes received
00187     */
00188     int32_t recv_udp(int id, void *data, uint32_t amount, uint32_t timeout=ESP8266_RECV_TIMEOUT);
00189 
00190     /**
00191     * Receives stream data from an open TCP socket
00192     *
00193     * @param id id to receive from
00194     * @param data placeholder for returned information
00195     * @param amount number of bytes to be received
00196     * @return the number of bytes received
00197     */
00198     int32_t recv_tcp(int id, void *data, uint32_t amount, uint32_t timeout=ESP8266_RECV_TIMEOUT);
00199 
00200     /**
00201     * Closes a socket
00202     *
00203     * @param id id of socket to close, valid only 0-4
00204     * @return true only if socket is closed successfully
00205     */
00206     bool close(int id);
00207 
00208     /**
00209     * Allows timeout to be changed between commands
00210     *
00211     * @param timeout_ms timeout of the connection
00212     */
00213     void setTimeout(uint32_t timeout_ms=ESP8266_MISC_TIMEOUT);
00214 
00215     /**
00216     * Checks if data is available
00217     */
00218     bool readable();
00219 
00220     /**
00221     * Checks if data can be written
00222     */
00223     bool writeable();
00224 
00225     /**
00226     * Attach a function to call whenever sigio happens in the serial
00227     *
00228     * @param func A pointer to a void function, or 0 to set as none
00229     */
00230     void sigio(Callback<void()> func);
00231 
00232     /**
00233     * Attach a function to call whenever sigio happens in the serial
00234     *
00235     * @param obj pointer to the object to call the member function on
00236     * @param method pointer to the member function to call
00237     */
00238     template <typename T, typename M>
00239     void sigio(T *obj, M method) {
00240         sigio(Callback<void()>(obj, method));
00241     }
00242 
00243     /**
00244     * Attach a function to call whenever network state has changed
00245     *
00246     * @param func A pointer to a void function, or 0 to set as none
00247     */
00248     void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00249 
00250     /**
00251      * Read default Wifi mode from flash
00252      *
00253      * return Station, SoftAP or SoftAP+Station - 0 on failure
00254      */
00255     int8_t get_default_wifi_mode();
00256 
00257     /**
00258      * Write default Wifi mode to flash
00259      */
00260     bool set_default_wifi_mode(const int8_t mode);
00261 
00262     /** Get the connection status
00263      *
00264      *  @return         The connection status according to ConnectionStatusType
00265      */
00266     nsapi_connection_status_t get_connection_status() const;
00267 
00268     static const int8_t WIFIMODE_STATION = 1;
00269     static const int8_t WIFIMODE_SOFTAP = 2;
00270     static const int8_t WIFIMODE_STATION_SOFTAP = 3;
00271     static const int8_t SOCKET_COUNT = 5;
00272 
00273 private:
00274     UARTSerial _serial;
00275     ATCmdParser _parser;
00276     Mutex _smutex; // Protect serial port access
00277 
00278     struct packet {
00279         struct packet *next;
00280         int id;
00281         uint32_t len;
00282         // data follows
00283     } *_packets, **_packets_end;
00284     void _packet_handler();
00285     void _connect_error_handler();
00286     bool recv_ap(nsapi_wifi_ap_t *ap);
00287     void _oob_socket0_closed_handler();
00288     void _oob_socket1_closed_handler();
00289     void _oob_socket2_closed_handler();
00290     void _oob_socket3_closed_handler();
00291     void _oob_socket4_closed_handler();
00292     void _connection_status_handler();
00293     void _oob_socket_close_error();
00294     void _clear_socket_packets(int id);
00295 
00296     char _ip_buffer[16];
00297     char _gateway_buffer[16];
00298     char _netmask_buffer[16];
00299     char _mac_buffer[18];
00300 
00301     int _connect_error;
00302     bool _fail;
00303     bool _closed;
00304     int _socket_open[SOCKET_COUNT];
00305     nsapi_connection_status_t _connection_status;
00306     Callback<void(nsapi_event_t, intptr_t)> _connection_status_cb;
00307 };
00308 
00309 #endif