From 2e6d7c8c25a68e12b87631a447428a708b15c728 Mon Sep 17 00:00:00 2001
From: gijsio <67470426+gijsio@users.noreply.github.com>
Date: Fri, 25 Jun 2021 10:33:06 +0200
Subject: [PATCH] improve pin.hold() explanation (#428)

* improve pin.hold() explanation

processed comments by Peter
---
 content/firmwareapi/pycom/machine/pin.md | 26 ++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/content/firmwareapi/pycom/machine/pin.md b/content/firmwareapi/pycom/machine/pin.md
index 5d71b8a..49d1229 100644
--- a/content/firmwareapi/pycom/machine/pin.md
+++ b/content/firmwareapi/pycom/machine/pin.md
@@ -105,9 +105,31 @@ Get or set the pin pull. Pull can be:
 
 ### pin.hold([hold])
 
-Get or set the pin hold. You can apply a hold to a pin by passing `True` (or clear it by passing `False`). When a pin is held, its value cannot be changed by using `Pin.value()` or `Pin.toggle()` until the hold is released. This Can be used to retain the pin state through a core reset and system reset triggered by watchdog time-out or Deep-sleep events. Only pins in the RTC power domain can retain their value through deep sleep or reset.
+Get or set the pin hold. This functionality can be used to hold a pin's state after [deepsleep](#machinedeepsleeptime_ms), `machine.reset()` or a [watchdog timer reset](/firmwareapi/pycom/machine/wdt/). Passing `True` will hold the current value of the pin, `False` will release the hold state. When a pin is in hold state, its value cannot be changed by using `Pin.value()` or `Pin.toggle()`, until the hold is released. Only pins in the RTC power domain can retain their value through deep sleep or reset. These are: `P2, P3, P4, P6, P8, P9, P10, P13, P14, P15, P16, P17, P18, P19, P20, P21, P22, P23`
+
+You can use the following example:
+```python
+from machine import Pin
+import machine
+p3 = Pin('P3', mode=Pin.OUT)
+p3.value(1) #can also be p3.value(0)
+p3.hold(True) #hold the pin high
+machine.reset()
+# instead, you can use:
+# machine.deepsleep(10000)
+
+# P3 will still be high here
+```
+A few things to keep in mind when using the pin hold functionality:
+* This feature only preserves the pin value:
+  * During a (deep)sleep
+  * After waking up from deepsleep
+  * After `machine.reset()`
+  * After a WDT reset
+* The hold state itself is not preserved _in Micropython_ after the above mentioned resets. This means that `pin.hold()` will return `False` after such reset, even though the pin is actually still held _in hardware_.
+* `pin.hold()` does **not** return the pin's value. You can hold a pin high or low.
+* Applying a hard-reset, by for example pressing the reset button, will reset the pin value and release the hold. 
 
-These are: `P2, P3, P4, P6, P8, P9, P10, P13, P14, P15, P16, P17, P18, P19, P20, P21, P22, P23`
 
 ### pin.callback(trigger, [handler=None, arg=None])