heltec comment updates

zephcore/CMakeLists.txt

@@ -478,24 +478,40 @@ endif()
 # build would light-sleep mid-advertising or mid-connection. repeater.conf
 # sets CONFIG_BT=n, which removes the problem instead of racing it.
 #
-# BOARD ALLOWLIST, not a platform check. Light sleep is only safe where DIO1
-# can wake the SoC, i.e. an RTC-capable pin (GPIO 0-21 on the S3). Every board
-# below wires DIO1 to GPIO14 and consoles on uart0 through a USB-serial bridge,
-# so both the packet wake and the console flush land correctly. Deliberately
-# ABSENT and must stay absent unless their wiring changes:
+# BOARD ALLOWLIST, not a platform check. The hard requirement is DIO1 on an
+# RTC-capable pin (GPIO 0-21 on the S3) so a received packet can wake the SoC.
+# Every board below wires DIO1 to GPIO14. Deliberately ABSENT and must stay
+# absent unless their wiring changes:
 #   xiao_esp32s3 (DIO1=GPIO39), station_g2 (GPIO48), thinknode_m9 (GPIO42),
 #   lilygo_tlora_c6 (GPIO23, outside the C6's LP range 0-7),
-#   lilygo_t3s3 (GPIO33 — and its console is USB Serial/JTAG, so it fails
-#     the second test below as well)
+#   lilygo_t3s3 (GPIO33)
 #     -> cannot wake on a received packet; the node would go deaf while
 #        looking excellent on a current meter.
-#   ttgo_lora32 -> SX127x; patches/zephyr/0012 arms DIO1 in the sx126x driver
-#        only, so nothing marks the pin as a wake source.
-# Boards with a native USB Serial/JTAG console are also unsuitable: the USB
-# peripheral drops off the bus in light sleep and there is no USJ wake source
-# in the HAL (only UART0/1/2 and LP-UART).
+#   ttgo_lora32 -> SX127x; the DIO1 wake flag lives in the sx126x half of
+#        patches/zephyr/0003, so nothing marks the pin as a wake source.
+#
+# CONSOLE, and why it does NOT gate this list. A native USB Serial/JTAG console
+# cannot survive light sleep: the peripheral drops off the bus and the HAL has
+# no USJ wake source (only UART0/1/2 and LP-UART). Of the boards below, only
+# Heltec V3 consoles on a physical uart0 (CP2102). V4, V4.3 and Wireless
+# Tracker V2 choose usb_serial in their board.overlay, and the uart0 reroute in
+# boards/common/esp32s3_usb.overlay is COMPANION-ONLY (the auto-include below
+# excludes repeater/observer/room_server), so a repeater build of those boards
+# keeps a USJ console.
+#
+# The consequence is accepted, not overlooked: on V4/V4.3/WT-V2 the USB CLI
+# stops answering once ZEPHCORE_PM_BOOT_AWAKE_MS expires, and the console flush
+# in helpers/pm_esp32_console.c targets UART0, which is not their console, so it
+# is inert there. Remote admin over LoRa is unaffected, and connecting a
+# terminal normally resets the board (the bridge drives EN from DTR) which
+# re-arms the window. These boards are in the field deliberately to get light
+# sleep exercised; drop them from the regex to take it away.
+#
+# The regex lists v43 explicitly. "heltec_wifi_lora32_v4" already substring-
+# matches it (CMake MATCHES is unanchored), which made V4.3's inclusion look
+# accidental; spelling it out makes the intent reviewable.
 if(ZEPHCORE_PLATFORM_CONF MATCHES "esp32_common" AND EXTRA_CONF_FILE MATCHES "repeater"
-   AND BOARD MATCHES "heltec_wifi_lora32_v3|heltec_wifi_lora32_v4|heltec_wireless_tracker")
+   AND BOARD MATCHES "heltec_wifi_lora32_v3|heltec_wifi_lora32_v4|heltec_wifi_lora32_v43|heltec_wireless_tracker")
     set(ZEPHCORE_PM_CONF "${CMAKE_CURRENT_SOURCE_DIR}/boards/common/pm_esp32.conf")
     if(EXISTS ${ZEPHCORE_PM_CONF})
         list(APPEND ZEPHCORE_CONF_FILES ${ZEPHCORE_PM_CONF})

zephcore/Kconfig

@@ -502,10 +502,16 @@ config ZEPHCORE_PM_CONSOLE_UART_NUM
 	  esp_rom_uart_tx_wait_idle() before entering light sleep, so a line in
 	  the TX FIFO is not cut off mid-character by the clock stopping.
 
-	  0 is correct for every board this is currently enabled on: their
-	  console is uart0, whether via a USB-serial bridge (Heltec V3/V4/V4.3)
-	  or the ROM-default pads.  Change it only if a board's console is moved
-	  to another hardware UART — a wrong index does not fail the build, it
+	  0 is correct for the boards whose console really is uart0: Heltec V3
+	  (via a CP2102 bridge) and anything on the ROM-default pads.  On Heltec
+	  V4, V4.3 and Wireless Tracker V2 the console is usb_serial (their
+	  board.overlay chooses it, and the uart0 reroute in
+	  boards/common/esp32s3_usb.overlay is companion-only), so this flush
+	  targets a peripheral that is not their console and does nothing.  That
+	  is harmless but not a fix: a USJ console has no wake source either way,
+	  so on those boards the USB CLI is simply unavailable once
+	  ZEPHCORE_PM_BOOT_AWAKE_MS expires.  Change it only if a board's console
+	  is moved to another hardware UART — a wrong index does not fail the build, it
 	  just silently flushes the wrong peripheral and lets the console
 	  truncate again.
 

zephcore/boards/common/pm_esp32.conf

@@ -17,6 +17,16 @@
 # drives EN from DTR) which re-arms the window — but a terminal that does not
 # toggle DTR needs a manual power cycle. Remote admin over LoRa is unaffected.
 #
+# Only Heltec V3 actually consoles on uart0. V4, V4.3 and Wireless Tracker V2
+# choose usb_serial in board.overlay, and the uart0 reroute in
+# boards/common/esp32s3_usb.overlay is companion-only, so a REPEATER build of
+# those boards has a USB Serial/JTAG console. The flush above then targets a
+# peripheral that is not their console and is inert, and the USJ peripheral
+# drops off the bus in light sleep with no wake source in the HAL. Net effect
+# on those three: no USB CLI at all after the boot window, rather than a CLI
+# that merely ignores keystrokes. This is accepted so the boards stay in the
+# field exercising light sleep — see the allowlist block in CMakeLists.txt.
+#
 # WiFi builds hold a pm_policy lock and never light-sleep at all — the OTA
 # session takes one for its duration (adapters/ota/wifi_ota.c) and an uplink or
 # observer station takes one permanently (adapters/wifi/ZephyrWiFiStation.c).
@@ -41,7 +51,7 @@
 #           -> DIO1 = GPIO14
 #   NOT OK  xiao_esp32s3 (GPIO39), station_g2 (GPIO48), thinknode_m9 (GPIO42),
 #           lilygo_tlora_c6 (GPIO23, outside the C6's LP range 0-7)
-#   N/A     ttgo_lora32 -> SX127x; patch 0012 arms DIO1 in the sx126x driver
+#   N/A     ttgo_lora32 -> SX127x; patch 0003 arms DIO1 in the sx126x driver
 #           only, so nothing marks the pin as a wake source at all
 #
 # On a NOT-OK board the driver logs "Pin N is not wakeup capable" at boot and
@@ -63,7 +73,7 @@
 #     source." — i.e. CONFIG_PM=y alone silently does nothing.
 #   - &gpio0 as a wakeup-source, so the driver's PM resume hook calls
 #     esp_sleep_enable_gpio_wakeup().
-# And patches/zephyr/0012 marks DIO1 itself with GPIO_INT_WAKEUP.
+# And patches/zephyr/0003 marks DIO1 itself with GPIO_INT_WAKEUP.
 #
 # Kernel time is safe across sleep: the Xtensa/ESP32 timer drivers implement
 # the LPM hooks (esp32_lptim_hook_on_lpm_entry/exit) that read the RTC counter

zephcore/boards/common/pm_esp32.overlay

@@ -27,7 +27,7 @@
  * esp_sleep_enable_gpio_wakeup() on PM_DEVICE_ACTION_RESUME, but only when the
  * PORT is wakeup-capable — that is what pm_device_wakeup_is_capable() tests,
  * and it is set by this property.  Per-PIN arming is separate and comes from
- * patches/zephyr/0012, which passes GPIO_INT_WAKEUP on the DIO1 configure.
+ * patches/zephyr/0003, which passes GPIO_INT_WAKEUP on the DIO1 configure.
  * Both halves are needed: the port enables the wake source, the pin selects
  * which line triggers it.
  *
@@ -45,7 +45,7 @@
  * allowlisted boards is an RTC-capable pad (GPIO 0-21), so their levels are
  * NOT retained unless explicitly held.  The chain:
  *
- *   1. patches/zephyr/0012 passes GPIO_INT_WAKEUP on DIO1.  On the S3 that
+ *   1. patches/zephyr/0003 passes GPIO_INT_WAKEUP on DIO1.  On the S3 that
  *      lands on esp_sleep_enable_ext1_wakeup_io() (drivers/gpio/gpio_esp32.c,
  *      SOC_PM_SUPPORT_EXT1_WAKEUP), i.e. RTC_EXT1_TRIG_EN.
  *   2. esp_sleep_start() only forces ESP_PD_DOMAIN_RTC_PERIPH on for
@@ -86,7 +86,7 @@
  * DIO1 is not the only thing that needs to interrupt a sleeping node — a person
  * pressing the button expects the display to come on.  Marking the PORT
  * wakeup-source above only enables esp_sleep_enable_gpio_wakeup(); the PIN is
- * armed separately, and until now only DIO1 got that (via patches/zephyr/0012).
+ * armed separately, and until now only DIO1 got that (via patches/zephyr/0003).
  * The result was a node that woke for packets and ignored its own button: press
  * it, nothing happens, the display never lights.  Reported from the field.
  *