From 8279b5cfd1cde0bc03d58ff2ee40f868e71b623f Mon Sep 17 00:00:00 2001
From: Alex Stewart <Alexander.Stewart@consensuscorp.com>
Date: Mon, 22 Feb 2016 09:32:12 -0800
Subject: [PATCH] Added some clarifications to comments in esp/gpio.h

---
 core/include/esp/gpio.h | 34 ++++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/core/include/esp/gpio.h b/core/include/esp/gpio.h
index 95b3c31..01fe144 100644
--- a/core/include/esp/gpio.h
+++ b/core/include/esp/gpio.h
@@ -29,6 +29,9 @@ void gpio_enable(const uint8_t gpio_num, const gpio_direction_t direction);
  * 100K ohms (see http://bbs.espressif.com/viewtopic.php?t=1079#p4097)
  * However, measured values suggest that the actual value is likely to be close
  * to 47K in reality.
+ *
+ * NOTE: The enabled_during_sleep setting is currently untested (please send
+ * feedback if you give it a try)
  */
 void gpio_set_pullup(uint8_t gpio_num, bool enabled, bool enabled_during_sleep);
 
@@ -46,6 +49,9 @@ static inline void gpio_disable(const uint8_t gpio_num)
 /* Set whether the specified pin continues to drive its output when the ESP8266
  * goes into sleep mode.  Note that this setting is reset to off whenever
  * gpio_enable is called, so this must be called after calling that function.
+ *
+ * NOTE: This functionality is currently untested (please send feedback if you
+ * give it a try)
  */
 static inline void gpio_set_output_on_sleep(const uint8_t gpio_num, bool enabled)
 {
@@ -58,11 +64,19 @@ static inline void gpio_set_output_on_sleep(const uint8_t gpio_num, bool enabled
 
 /* Set output of a pin high or low.
  *
- * Only works if pin has been set to GPIO_OUTPUT via gpio_enable()
+ * Only works if pin has been set to GPIO_OUTPUT or GPIO_OUT_OPEN_DRAIN via
+ * gpio_enable()
+ *
+ * If the mode is GPIO_OUT_OPEN_DRAIN, setting it low (false) will pull the pin
+ * down to ground, but setting it high (true) will allow it to float.  Note
+ * that even in GPIO_OUT_OPEN_DRAIN mode, the input gates are still physically
+ * connected to the pin, and can be damaged if the voltage is not in either the
+ * "low" or "high" range.  Make sure there is some sort of pull-up resistor on
+ * the line to avoid floating logic lines!
  */
 static inline void gpio_write(const uint8_t gpio_num, const bool set)
 {
-    if(set)
+    if (set)
         GPIO.OUT_SET = BIT(gpio_num);
     else
         GPIO.OUT_CLEAR = BIT(gpio_num);
@@ -70,7 +84,10 @@ static inline void gpio_write(const uint8_t gpio_num, const bool set)
 
 /* Toggle output of a pin
  *
- * Only works if pin has been set to GPIO_OUTPUT via gpio_enable()
+ * Only works if pin has been set to GPIO_OUTPUT or GPIO_OUT_OPEN_DRAIN via
+ * gpio_enable()
+ *
+ * See notes in gpio_write() about GPIO_OUT_OPEN_DRAIN mode.
  */
 static inline void gpio_toggle(const uint8_t gpio_num)
 {
@@ -88,8 +105,12 @@ static inline void gpio_toggle(const uint8_t gpio_num)
 
 /* Read input value of a GPIO pin.
  *
- * If pin is set as an input, this reads the value on the pin.
- * If pin is set as an output, this reads the last value written to the pin.
+ * If pin is set GPIO_INPUT, this reads the level on the pin.
+ * If pin is set GPIO_OUTPUT, this reads the level at which the pin is
+ * currently being driven (i.e. the last value written).
+ * If pin is set GPIO_OUT_OPEN_DRAIN, when the pin is written low, this will
+ * return low (false), when the pin is written high, this will behave like
+ * GPIO_INPUT.
  */
 static inline bool gpio_read(const uint8_t gpio_num)
 {
@@ -100,7 +121,8 @@ extern void gpio_interrupt_handler(void);
 
 /* Set the interrupt type for a given pin
  *
- * If int_type is not GPIO_INTTYPE_NONE, the gpio_interrupt_handler will be attached and unmasked.
+ * If int_type is not GPIO_INTTYPE_NONE, the gpio_interrupt_handler will be
+ * attached and unmasked.
  */
 static inline void gpio_set_interrupt(const uint8_t gpio_num, const gpio_inttype_t int_type)
 {