From c0a615e99cce2c23b5052713dc43dda9ec688ec8 Mon Sep 17 00:00:00 2001
From: Peter Harper <77111776+peterharperuk@users.noreply.github.com>
Date: Wed, 7 Jun 2023 17:52:07 +0100
Subject: [PATCH] Improve the comments around VSYS/VBUS config. (#1414)

---
 src/boards/include/boards/pico.h   |  5 +++--
 src/boards/include/boards/pico_w.h | 11 ++++++++---
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/boards/include/boards/pico.h b/src/boards/include/boards/pico.h
index b1799577..139c0d39 100644
--- a/src/boards/include/boards/pico.h
+++ b/src/boards/include/boards/pico.h
@@ -81,12 +81,13 @@
 #define PICO_RP2040_B0_SUPPORTED 1
 #endif
 
-// Pin get VBUS
+// The GPIO Pin used to read VBUS to determine if the device is battery powered.
 #ifndef PICO_VBUS_PIN
 #define PICO_VBUS_PIN 24
 #endif
 
-// Pin used to monitor VSYS using ADC
+// The GPIO Pin used to monitor VSYS. Typically you would use this with ADC.
+// There is an example in adc/read_vsys in pico-examples.
 #ifndef PICO_VSYS_PIN
 #define PICO_VSYS_PIN 29
 #endif
diff --git a/src/boards/include/boards/pico_w.h b/src/boards/include/boards/pico_w.h
index 60e2312c..3109c78a 100644
--- a/src/boards/include/boards/pico_w.h
+++ b/src/boards/include/boards/pico_w.h
@@ -99,17 +99,22 @@
 #define CYW43_WL_GPIO_LED_PIN 0
 #endif
 
-// CYW43 GPIO to get VBUS
+// If CYW43_WL_GPIO_VBUS_PIN is defined then a CYW43 GPIO has to be used to read VBUS.
+// This can be passed to cyw43_arch_gpio_get to determine if the device is battery powered.
+// PICO_VBUS_PIN and CYW43_WL_GPIO_VBUS_PIN should not both be defined.
 #ifndef CYW43_WL_GPIO_VBUS_PIN
 #define CYW43_WL_GPIO_VBUS_PIN 2
 #endif
 
-// VSYS pin is shared with CYW43
+// If CYW43_USES_VSYS_PIN is defined then CYW43 uses the VSYS GPIO (defined by PICO_VSYS_PIN) for other purposes.
+// If this is the case, to use the VSYS GPIO it's necessary to ensure CYW43 is not using it.
+// This can be achieved by wrapping the use of the VSYS GPIO in cyw43_thread_enter / cyw43_thread_exit.
 #ifndef CYW43_USES_VSYS_PIN
 #define CYW43_USES_VSYS_PIN 1
 #endif
 
-// Pin used to monitor VSYS using ADC
+// The GPIO Pin used to monitor VSYS. Typically you would use this with ADC.
+// There is an example in adc/read_vsys in pico-examples.
 #ifndef PICO_VSYS_PIN
 #define PICO_VSYS_PIN 29
 #endif