esp32/modesp32: Add new gpio_deep_sleep_hold function.

Add a new function to control whether held pins will retain their function
through deep-sleep.

Also document this function and explain how to use this in quickref to
retain pin configuration during deep-sleep.

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
index dd7e515f1b..894508f4c2 100644
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -562,6 +562,23 @@ deep-sleep if pad hold is enabled with the ``hold=True`` argument to
 ``Pin.init()``.
 
 Non-RTC GPIO pins will be disconnected by default on entering deep-sleep.
+Configuration of non-RTC pins - including output level - can be retained by
+enabling pad hold on the pin and enabling GPIO pad hold during deep-sleep::
+
+    from machine import Pin, deepsleep
+    import esp32
+
+    opin = Pin(19, Pin.OUT, value=1, hold=True) # hold output level
+    ipin = Pin(21, Pin.IN, Pin.PULL_UP, hold=True) # hold pull-up
+
+    # enable pad hold in deep-sleep for non-RTC GPIO
+    esp32.gpio_deep_sleep_hold(True)
+
+    # 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
 -------