docs/ESP32: Reinit watchdog with longer timeout.

IhorNehrutsa · IhorNehrutsa · commit 77a5199682aa · 2023-10-06T09:11:32.000+03:00
docs/ESP32: Reinitialize watchdog timer with longer timeout.

Signed-off-by: Ihor Nehrutsa &lt;IhorNehrutsa@gmail.com&gt;
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -141,7 +141,7 @@ These are working configurations for LAN interfaces of popular boards::
     # Olimex ESP32-GATEWAY: power controlled by Pin(5)
     # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
 
-    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5), 
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
                       phy_type=network.PHY_LAN8720, phy_addr=0,
                       ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
 
@@ -564,7 +564,7 @@ See :ref:`machine.WDT <machine.WDT>`. ::
     from machine import WDT
 
     # enable the WDT with a timeout of 5s (1s is the minimum)
-    wdt = WDT(timeout=5000)
+    wdt = WDT(timeout=5000)  # timeout in milliseconds
     wdt.feed()
 
 .. _Deep_sleep_mode:
diff --git a/docs/esp32/tutorial/index.rst b/docs/esp32/tutorial/index.rst
@@ -20,4 +20,5 @@ to `<https://www.python.org>`__.
 
    intro.rst
    pwm.rst
+   wdt.rst
    peripheral_access.rst
diff --git a/docs/esp32/tutorial/wdt.rst b/docs/esp32/tutorial/wdt.rst
@@ -0,0 +1,43 @@
+
+.. _esp32_wdt:
+
+WDT
+===
+
+When the WDT timeout is short, a problem occurs when updating the software:
+you don't have enough time to copy the updates to the device.
+ESP32 allows reinitialise the watchdog with a longer timeout - like an hour.
+
+More comprehansive example usage::
+
+    # Save as 'main.py' and it will run automatically after 'boot.py'
+
+    import sys
+    from time import sleep
+    from machine import WDT, reset
+
+    try:
+        print('Press Ctrl-C to break the program.')
+        sleep(5)
+        print('Enable the WDT with a timeout of 5s.')
+        wdt = WDT(timeout=5000)
+
+        seconds = 1
+        while True:  # infinite work loop
+            print('Do something useful in less than 5 seconds.')
+            print(f'Sleep {seconds} seconds.')
+            if seconds >= 5:
+                print(f'WDT will reboot the board.')
+            sleep(seconds)
+            seconds += 1
+            wdt.feed()
+
+            # 1/0  # uncomment this line to raise an runtime exception, then WDT reboot
+
+            # sys.exit()  # uncomment this line for planned program exit
+
+    except SystemExit:
+        wdt = WDT(timeout=1000 * 60 * 60)  # 1 hour before WDT reboot
+        print('Now you have 1 hour to update program on the board.')
+        print('When ready, type reset() on the REPL/WebREPL command line to reboot.')
+
diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst
@@ -5,15 +5,17 @@ class WDT -- watchdog timer
 ===========================
 
 The WDT is used to restart the system when the application crashes and ends
-up into a non recoverable state. Once started it cannot be stopped or
-reconfigured in any way. After enabling, the application must "feed" the
+up into a non recoverable state. Once started it cannot be stopped
+in any way. After enabling, the application must "feed" the
 watchdog periodically to prevent it from expiring and resetting the system.
 
 Example usage::
 
     from machine import WDT
     wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
-    wdt.feed()
+    while True:
+        # do something useful in less than 2 seconds
+        wdt.feed()
 
 Availability of this class: pyboard, WiPy, esp8266, esp32, rp2040, mimxrt.
 
