ESP8266WiFi library documentation (#2388)

* New section with ESP8266WiFi library documentation

* ESP8266WiFi library documentation

1. Introduction - example, diagnostic, doxygen
2. Station - examples, new doc
3. Soft Access Point - examples, new doc
4. Scan - examples, new doc
5. Client - examples, ref. Arduino, setNoDelay, list of functions
6. Client Secure - examples, loadCertificate, setCertificate, list of
functions
7. Server- examples, ref. Arduino, setNoDelay, list of functions
8. UDP - examples, ref. Arduino, Multicast UDP
9. Generic - examples, onEvent, WiFiEventHandler, persistent, mode, list
of functions

* Fixed numbered list

doc/esp8266wifi/generic-examples.md

@@ -0,0 +1,138 @@
+---
+title: ESP8266WiFi Generic Class - Sketch Examples
+---
+
+[ESP8266WiFi Library :back:](readme.md#generic)
+
+
+## Generic
+
+In the first [example](readme.md#quick-start) of the ESP8266WiFi library documentation we have discussed how to check when module connects to the Wi-Fi network. We were waiting until connection is established. If network is not available, the module could wait like that for ever doing nothing else. Another [example](scan-examples.md#async-scan) on the Wi-Fi asynchronous scan mode demonstrated how to wait for scan result and do in parallel something else - blink a LED not disturbing the blink pattern. Let's apply similar functionality when connecting the module to an access point.
+
+
+## Table of Contents
+  * [Introduction](#introduction)
+  * [What are the Tasks?](#what-are-the-tasks)
+  * [Event Driven Methods](#event-driven-methods)
+  * [Register the Events](#register-the-events)
+  * [The Code](#the-code)
+  * [Check the Code](#check-the-code)
+  * [Conclusion](#conclusion)
+
+
+### Introduction
+
+In example below we will show another cool example of getting ESP perform couple of tasks at the same time and with very little programming. 
+
+
+### What are the Tasks?
+
+We would like to write a code that will inform us that connection to Wi-Fi network has been established or lost. At the same time we want to perform some time critical task. We will simulate it with a blinking LED. Generic class provides specific, event driven methods, that will be executed asynchronously, depending on e.g. connection status, while we are already doing other tasks.
+
+
+### Event Driven Methods
+
+The list of all such methods is provided in [Generic Class](generic-class.md) documentation.
+
+We would like to use two of them:
+* `onStationModeGotIP` called when station is assigned IP address. This assignment may be done  by DHCP client or by executing `WiFi.config(...)`.
+* `onStationModeDisconnected` called when station is disconnected from Wi-Fi network. The reason of disconnection does not matter. Event will be triggered both if disconnection is done from the code by executing `WiFi.disconnect()`, because the Wi-Fi signal is weak, or because the access point is switched off. 
+
+
+### Register the Events
+
+To get events to work we need to complete just two steps:
+
+1. Declare the event handler:
+
+  ```cpp
+  WiFiEventHandler disconnectedEventHandler;
+  ```
+
+2. Select particular event (in this case `onStationModeDisconnected`) and add the code to be executed when event is fired.
+
+  ```cpp
+  disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)
+  {
+    Serial.println("Station disconnected");
+  });
+  ```
+If this event is fired the code will print out information that station has been disconnected.
+
+That's it. It is all we need to do. 
+
+
+### The Code
+
+The complete code, including both methods discussed at the beginning, is provided below.
+
+```cpp
+#include <ESP8266WiFi.h>
+
+const char* ssid = "********";
+const char* password = "********";
+
+WiFiEventHandler gotIpEventHandler, disconnectedEventHandler;
+
+bool ledState;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+
+  pinMode(LED_BUILTIN, OUTPUT);
+
+  gotIpEventHandler = WiFi.onStationModeGotIP([](const WiFiEventStationModeGotIP& event)
+  {
+    Serial.print("Station connected, IP: ");
+    Serial.println(WiFi.localIP());
+  });
+
+  disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)
+  {
+    Serial.println("Station disconnected");
+  });
+
+  Serial.printf("Connecting to %s ...\n", ssid);
+  WiFi.begin(ssid, password);
+}
+
+
+void loop()
+{
+  digitalWrite(LED_BUILTIN, ledState);
+  ledState = !ledState;
+  delay(250);
+}
+```
+
+### Check the Code
+
+After uploading above sketch and opening a serial monitor we should see a similar log:
+
+```
+Connecting to sensor-net ...
+Station connected, IP: 192.168.1.10
+```
+
+If you switch off the access point, and put it back on, you will see the following:
+
+```
+Station disconnected
+Station disconnected
+Station disconnected
+Station connected, IP: 192.168.1.10
+```
+
+The process of connection, disconnection and printing messages is done in background of the `loop()` that is responsible for blinking the LED. Therefore the blink pattern all the time remains undisturbed.
+
+
+### Conclusion
+
+Check out events from generic class. They will help you to write more compact code. Use them to practice splitting your code into separate tasks that are executed asynchronously.
+
+
+For review of functions included in generic class, please refer to the [Generic Class :arrow_right:](generic-class.md) documentation.
+