docs/esp32: Document gpio_deep_sleep_hold() function.

jonathanhogg · jonathanhogg · commit 02ece2b56ebc · 2022-03-09T14:27:27.000Z
Document new `esp32.gpio_deep_sleep_hold()` function and explain how to
use this in quickref to retain pin configuration during deep-sleep.
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -560,6 +560,25 @@ deep-sleep mode::
 
 Non-RTC GPIO pins will be disconnected by default on entering deep-sleep.
 
+Pin configuration on *any* output-capable pin - including output level - can be
+retained during deep-sleep by enabling pad hold during deep-sleep and
+configuring a pin with pad hold::
+
+    from machine import Pin, deepsleep
+    import esp32
+
+    # enable pad hold in deep-sleep
+    esp32.gpio_deep_sleep_hold(True)
+
+    opin = Pin(2, Pin.OUT, value=1, hold=True) # hold output level
+    ipin = Pin(21, Pin.IN, Pin.PULL_UP, hold=True) # hold pull-up
+
+    # put the device to sleep for 10 seconds
+    deepsleep(10000)
+
+The pin configuration - including the pad hold - will be retained on wake from
+sleep. See :ref:`Pins_and_GPIO` above for a further discussion of pad holding.
+
 SD card
 -------
 
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -30,6 +30,11 @@ Functions
     or a tuple/list of valid Pin objects.  *level* should be ``esp32.WAKEUP_ALL_LOW``
     or ``esp32.WAKEUP_ANY_HIGH``.
 
+.. function:: gpio_deep_sleep_hold(enable)
+
+    Configure whether pin configuration is retained during deep-sleep mode for
+    held pads. *enable* should be a boolean value.
+
 .. function:: raw_temperature()
 
     Read the raw value of the internal temperature sensor, returning an integer.
