FAQ Section Updated about Watchdog resets

doc/faq/readme.md

@@ -43,3 +43,111 @@ You will see this issue only if serial upload was not followed by a physical res
 
 Ref. [#1017](https://github.com/esp8266/Arduino/issues/1017), [#1107](https://github.com/esp8266/Arduino/issues/1107), [#1782](https://github.com/esp8266/Arduino/issues/1782)
 
+
+### I'm getting these Watchdog Resets "wdt reset"�How can I avoid them?
+The esp8266 is equipped with two watchdog timers: A software watchdog and a hardware watchdog. If you don't understand why microcontrollers need a watchdog (timer), you may first read [here](http://www.embedded.com/electronics-blogs/beginner-s-corner/4023849/Introduction-to-Watchdog-Timers).
+
+When your sketch is running�either in the `setup` or during the `loop`�you have to make sure to feed the watchdog periodically. Otherwise "it will bite" and the watchdog will restart your sketch. The basic operation is illustrated in the following picture:
+![wdt basic operation](pictures/wdt_basic_operation.png)
+
+
+**How does the esp8266 Arduino Core feed the watchdog(s)?**
+From the perspective of your Arduino sketch, the basic feeding is implicit: Everytime an iteration of your main loop starts again, i.e. it hits the `loop` statement both watchdogs are fed; cf. (1) in the figure above. Esp8266 Arduino libraries, especially core libraries like for instance the `ESP8266WiFi` library take care of feeding the watchdogs, too. Thus, normally you don't have to feed them explicitly.
+
+**When and why should I feed the watchdog(s) explicitly?**
+The software watchdog bites exactly every 3.2 seconds, the hardware watchdog every 7�8 seconds. If your sketch contains code which could exceed running for 3.2 seconds you must feed the watchdogs. I.e. you have to feed them explicitly by calling (cf. (1) in the figure above):
+
+ - `yield()`
+ or
+ - `delay(...)`
+
+Note that calling `delayMicroseconds(...)` does **not** feed the watchdogs!
+
+**Can I disable the watchdogs?**
+You can disable the software watchdog but you **cannot** disable the hardware watchdog. Furthermore, you **cannot** change the intervals of the watchdogs timers. 
+
+If you want to disable the software watchdog, you have to call the corresponding SDK functions from the `user_interface.h`. For the documentation on these functions see Espressif's ESP8266 Non-OS SDK API Reference (download on [bbs.espressif](http://bbs.espressif.com/)).
+
+ - `system_soft_wdt_stop()`
+ - `system_soft_wdt_feed()`
+ - `system_soft_wdt_restart()`
+
+The name of the function `system_soft_wdt_feed()` is bit confusing: In general it will feed **both** watchdogs, i.e. the software **and** hardware watchdog. If you disable the software watchdog by calling `system_soft_wdt_stop()` and then call `system_soft_wdt_feed()` afterwards, it will still feed both watchdogs. However, since you have just disabled the software watchdog before, it will have no effect on the software watchdog (timer) and will only affect the hardware watchdog (timer). Thus, from an "End-User's" perspective, this looks like `system_soft_wdt_feed()` feeds the hardware watchdog only.
+
+The following code snippet shows you how to disable the software watchdog and how to feed the hardware watchdog periodically.
+```c
+extern "C" {
+    #include "user_interface.h"
+}
+int j = 0;
+unsigned long a, b;
+
+void setup() {
+  delay(1000); // This feeds both watchdogs
+  Serial.begin(115200);
+  Serial.println("Setup...");
+}
+// This function keeps the cpu busy for 1 second by doing stupid NOPs
+void ICACHE_RAM_ATTR busy_1second() {
+    unsigned int i, iterations;
+  if (F_CPU == 160000000) {
+        iterations = 13333332;
+  }
+  else {
+        iterations = 6666666;
+  }
+
+  for (i = 0; i < iterations; i++) {
+    asm(
+      "NOP;"
+      "NOP;"
+      "NOP;"
+      "NOP;"
+      "NOP;"
+      "NOP;"
+      "NOP;"
+    );
+  }
+}
+void loop() {
+  Serial.println("Getting busy in 3 seconds...");
+  delay(3000);
+  Serial.println("now!");
+  system_soft_wdt_stop(); // Disable Software watchdog
+  system_soft_wdt_feed(); // Feed Hardware Watchdog
+  for (j = 1; j < 20; j++) {
+    a = micros();
+    busy_1second();
+    b = micros();
+    Serial.println(b - a);
+    // Feed Hardware Watchdog every 6 seconds
+    if (j % 6 == 0) {
+      system_soft_wdt_feed();
+      Serial.println("HW Dog fed! Miam miam :-o ");
+    }
+  }
+  system_soft_wdt_feed();
+  system_soft_wdt_restart();
+}
+```
+And it will give you the following output:
+```
+Getting busy in 3 seconds...
+now!
+1000002
+1000007
+1000001
+1000000
+1000000
+1000000
+HW Dog fed! Miam miam :-o 
+1000001
+1000007
+1000000
+1000001
+1000001
+1000000
+HW Dog fed! Miam miam :-o 
+1000000
+...
+```