Merge pull request #8689 from VeijoPesonen/esp8266-driver_v1.7

Add ESP8266 driver v1.7

components/wifi/esp8266-driver/ESP8266Interface.h

@@ -17,30 +17,53 @@
 #ifndef ESP8266_INTERFACE_H
 #define ESP8266_INTERFACE_H
 
-#include "mbed.h"
-#include "ESP8266.h"
-
+#include "ESP8266/ESP8266.h"
+#include "events/EventQueue.h"
+#include "events/mbed_shared_queues.h"
+#include "features/netsocket/NetworkInterface.h"
+#include "features/netsocket/NetworkStack.h"
+#include "features/netsocket/nsapi_types.h"
+#include "features/netsocket/SocketAddress.h"
+#include "features/netsocket/WiFiAccessPoint.h"
+#include "features/netsocket/WiFiInterface.h"
+#include "platform/Callback.h"
 
 #define ESP8266_SOCKET_COUNT 5
 
+#ifdef TARGET_FF_ARDUINO
+#ifndef MBED_CONF_ESP8266_TX
+#define MBED_CONF_ESP8266_TX D1
+#endif
+
+#ifndef MBED_CONF_ESP8266_RX
+#define MBED_CONF_ESP8266_RX D0
+#endif
+#endif /* TARGET_FF_ARDUINO */
+
 /** ESP8266Interface class
  *  Implementation of the NetworkStack for the ESP8266
  */
-class ESP8266Interface : public NetworkStack, public WiFiInterface
-{
+class ESP8266Interface : public NetworkStack, public WiFiInterface {
 public:
+#if defined MBED_CONF_ESP8266_TX && defined MBED_CONF_ESP8266_RX
     /**
      * @brief ESP8266Interface default constructor
      *        Will use values defined in mbed_lib.json
      */
     ESP8266Interface();
+#endif
 
     /** ESP8266Interface lifetime
      * @param tx        TX pin
      * @param rx        RX pin
      * @param debug     Enable debugging
      */
-    ESP8266Interface(PinName tx, PinName rx, bool debug = false);
+    ESP8266Interface(PinName tx, PinName rx, bool debug = false, PinName rts = NC, PinName cts = NC);
+
+    /**
+     * @brief ESP8266Interface default destructor
+     */
+    virtual ~ESP8266Interface();
 
     /** Start the interface
      *
@@ -62,7 +85,7 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
      *  @return          0 on success, or error code on failure
      */
     virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE,
-                                  uint8_t channel = 0);
+                        uint8_t channel = 0);
 
     /** Set the WiFi network credentials
      *
@@ -98,11 +121,11 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
      */
     virtual const char *get_mac_address();
 
-     /** Get the local gateway
-     *
-     *  @return         Null-terminated representation of the local gateway
-     *                  or null if no network mask has been recieved
-     */
+    /** Get the local gateway
+    *
+    *  @return         Null-terminated representation of the local gateway
+    *                  or null if no network mask has been recieved
+    */
     virtual const char *get_gateway();
 
     /** Get the local network mask
@@ -156,12 +179,12 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
     /** @copydoc NetworkStack::setsockopt
      */
     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
-            int optname, const void *optval, unsigned optlen);
+                                     int optname, const void *optval, unsigned optlen);
 
     /** @copydoc NetworkStack::getsockopt
      */
     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
-            void *optval, unsigned *optlen);
+                                     void *optval, unsigned *optlen);
 
     /** Register callback for status reporting
      *
@@ -292,31 +315,49 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
     }
 
 private:
+    // AT layer
+    ESP8266 _esp;
+    void update_conn_state_cb();
+
+    // Credentials
     static const int ESP8266_SSID_MAX_LENGTH = 32; /* 32 is what 802.11 defines as longest possible name */
+    char ap_ssid[ESP8266_SSID_MAX_LENGTH + 1]; /* The longest possible name; +1 for the \0 */
     static const int ESP8266_PASSPHRASE_MAX_LENGTH = 63; /* The longest allowed passphrase */
     static const int ESP8266_PASSPHRASE_MIN_LENGTH = 8; /* The shortest allowed passphrase */
+    char ap_pass[ESP8266_PASSPHRASE_MAX_LENGTH + 1]; /* The longest possible passphrase; +1 for the \0 */
+    nsapi_security_t _ap_sec;
 
-    ESP8266 _esp;
-    bool _ids[ESP8266_SOCKET_COUNT];
-    int _initialized;
-    int _started;
-
-    char ap_ssid[ESP8266_SSID_MAX_LENGTH + 1]; /* 32 is what 802.11 defines as longest possible name; +1 for the \0 */
-    nsapi_security_t ap_sec;
-    uint8_t ap_ch;
-    char ap_pass[ESP8266_PASSPHRASE_MAX_LENGTH + 1];
-    uint16_t _local_ports[ESP8266_SOCKET_COUNT];
+    // Drivers's socket info
+    struct _sock_info {
+        bool open;
+        uint16_t sport;
+    };
+    struct _sock_info _sock_i[ESP8266_SOCKET_COUNT];
 
-    bool _disable_default_softap();
-    void event();
+    // Driver's state
+    int _initialized;
     bool _get_firmware_ok();
     nsapi_error_t _init(void);
+    int _started;
     nsapi_error_t _startup(const int8_t wifi_mode);
 
+    //sigio
     struct {
         void (*callback)(void *);
         void *data;
     } _cbs[ESP8266_SOCKET_COUNT];
+    void event();
+
+    // Connection state reporting to application
+    nsapi_connection_status_t _conn_stat;
+    mbed::Callback<void(nsapi_event_t, intptr_t)> _conn_stat_cb;
+
+    // Background OOB processing
+    // Use global EventQueue
+    events::EventQueue *_global_event_queue;
+    int _oob_event_id;
+    void proc_oob_evnt();
+    void _oob2global_event_queue();
 };
 
 #endif

components/wifi/esp8266-driver/README.md

@@ -4,10 +4,97 @@ The Mbed OS driver for the ESP8266 WiFi module.
 
 ## Firmware version
 
-ESP8266 modules come in different shapes and formats, but the most important factor is the firmware version in it. To make sure that the firmware in your module is compatible with Mbed OS, follow the [Update guide](https://developer.mbed.org/teams/ESP8266/wiki/Firmware-Update).
+ESP8266 modules come in different shapes and formats, but the firmware version is the most important factor. To
+make sure that the firmware in your module is compatible with Mbed OS, follow the
+[Update guide](https://developer.mbed.org/teams/ESP8266/wiki/Firmware-Update).
+
+This driver supports AT firmware versions 1.3.0 to 1.7.0. We advise updating the
+[AT firmware](https://www.espressif.com/en/support/download/at?keys=) to at least version 1.7.0.
 
 ## Restrictions
 
-- The ESP8266 WiFi module does not allow the TCP client to bind on a specific port.
-- Setting up a UDP server is not possible.
-- The serial port does not have hardware flow control enabled. The AT command set does not either have a way to limit the download rate. Therefore, downloading anything larger than the serial port input buffer is unreliable. An application should be able to read fast enough to stay ahead of the network. This affects mostly the TCP protocol where data would be lost with no notification. On UDP, this would lead to only packet losses which the higher layer protocol should recover from.
+* The ESP8266 Wi-Fi module does not allow the TCP client to bind to a specific port.
+* Setting up a UDP server is not possible.
+* The serial port does not have hardware flow control enabled by default. Additionally, the AT command set does not have a method for limiting the download rate. Therefore, downloading anything larger than the serial port input buffer is unreliable 
+unless you use [AT firmware](https://www.espressif.com/en/support/download/at?keys=) version 1.7.0 or later. With older
+firmware, an application should be able to read fast enough to stay ahead of the network. This applies mostly to TCP
+protocol, where data would be lost without notification. On UDP using all firmware versions, the higher-layer protocol should recover from packet loss.
+
+## Mandatory configuration
+
+![mbed_lib.json](mbed_lib.json) configuration assumes Arduino form factor. Please adjust according to your board. You can override parameters from your app config file.
+
+At minimum, check the following configuration parameters:
+
+```javascript
+{
+    "name": "esp8266",
+    "config": {
+        "tx": {
+            "help": "TX pin for serial connection",
+            "value": null <- 'D1' by default if Arduino, adjust based on your board
+        },
+        "rx": {
+            "help": "RX pin for serial connection",
+            "value": null <- 'D0' by default if Arduino, adjust based on your board
+        },
+        "provide-default": {
+            "help": "Provide default WifiInterface. [true/false]",
+            "value": false <- Set to 'true' if this is the interface you are using
+        },
+        "socket-bufsize": {
+            "help": "Max socket data heap usage",
+            "value": 8192 <- Without HW flow control more is better. Once the limit is reached packets are
+                             dropped - does not matter is it TCP or UDP.
+        }
+    }
+}
+```
+
+## UART HW flow control
+
+UART HW flow control requires you to additionally wire the CTS and RTS flow control pins between your board and your
+ESP8266 module. After this, remember to add the configuration option for flow control to your app configuration file. This example uses the [ST NUCLEO-F429ZI](https://os.mbed.com/platforms/ST-Nucleo-F429ZI/) board and
+[ESPBee XBee Module](https://www.cascologix.com/product/espbee/).
+
+**Note:** Not all modules expose ESP8266's RTS and CTS pins, so choose modules carefully.
+
+Once you have your hardware set up, add a configuration like the following to your app configuration file. Arduino pins D1 and D0 are used as TX and RX:
+
+``` javascript
+"target_overrides": {
+        "NUCLEO_F429ZI": {
+            "esp8266.rts": "PG_12",
+            "esp8266.cts": "PG_15"
+         }
+```
+
+### Example board pins
+
+* TX: D1 (Arduino Uno Revision 3 connectivity  headers)
+* RX: D0 (Arduino Uno Revision 3 connectivity headers)
+* RTS: PG_12 (STMicroelectronics Morpho extension pin headers)
+* CTS: PG_15 (STMicroelectronics Morpho extension pin headers)
+
+### Example ESP8266 pins
+
+* TX: D1 (Arduino Wireless Protoshield headers)/ TX (ESPBee XBee headers)
+* RX: D0 (Arduino Wireless Protoshield headers)/ RX (ESPBee XBee headers)
+* RTS: RTS (ESPBee XBee headers)
+* CTS: CTS (ESPBee XBee headers)
+
+### Connections
+
+With these pictures only consider the green and yellow wires which are connected to ESP8266. The pink wire is for reset and
+the rest are for firmware update. TX and RX go through Arduino pins D1 and D0.
+
+**Note:** Pull down GPIO15(ESPBee RTS) during startup to **boot from flash**, instead of **firmware update** or
+**boot from SD card**. Once the software is running, the same pin is used as the RTS pin:
+
+* Board TX: ESP8266 RX
+* Board RX: ESP8266 TX
+* Board RTS (grey): ESP8266 CTS(yellow)
+* Board CTS (white): ESP8266 RTS(green)
+
+![RTS,CTS](nucleo_esp8266_hw_fc1.jpg)
+![RTS,CTS](nucleo_esp8266_hw_fc2.jpg)

components/wifi/esp8266-driver/mbed_lib.json

@@ -2,20 +2,32 @@
     "name": "esp8266",
     "config": {
         "tx": {
-            "help": "TX pin for serial connection",
+            "help": "TX pin for serial connection. D1 assumed if Arduino Form Factor, needs to be set/overwritten otherwise",
             "value": null
         },
         "rx": {
-            "help": "RX pin for serial connection",
+            "help": "RX pin for serial connection. D0 assumed if Arduino Form Factor, needs to be set/overwritten otherwise",
+            "value": null
+        },
+        "rts": {
+            "help": "RTS pin for serial connection, defaults to Not Connected",
+            "value": null
+        },
+        "cts": {
+            "help": "CTS pin for serial connection, defaults to Not Connected",
             "value": null
         },
         "debug": {
-            "help": "Enable debug logs",
+            "help": "Enable debug logs. [true/false]",
             "value": false
         },
         "provide-default": {
             "help": "Provide default WifiInterface. [true/false]",
             "value": false
+        },
+        "socket-bufsize": {
+            "help": "Max socket data heap usage",
+            "value": 8192
         }
     },
     "target_overrides": {