From d4363775aed7bc5874685debf32113702bd0ad86 Mon Sep 17 00:00:00 2001 From: liquidraver <504870+liquidraver@users.noreply.github.com> Date: Fri, 28 Aug 2026 13:48:53 +0200 Subject: [PATCH] heltec comment updates --- zephcore/CMakeLists.txt | 42 +++++++++++++++++-------- zephcore/Kconfig | 14 ++++++--- zephcore/boards/common/pm_esp32.conf | 14 +++++++-- zephcore/boards/common/pm_esp32.overlay | 6 ++-- 4 files changed, 54 insertions(+), 22 deletions(-) diff --git a/zephcore/CMakeLists.txt b/zephcore/CMakeLists.txt index 86c2b6a..ac54083 100644 --- a/zephcore/CMakeLists.txt +++ b/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}) diff --git a/zephcore/Kconfig b/zephcore/Kconfig index 27c45fa..98ffe53 100644 --- a/zephcore/Kconfig +++ b/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. diff --git a/zephcore/boards/common/pm_esp32.conf b/zephcore/boards/common/pm_esp32.conf index e8e396a..4068449 100644 --- a/zephcore/boards/common/pm_esp32.conf +++ b/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 diff --git a/zephcore/boards/common/pm_esp32.overlay b/zephcore/boards/common/pm_esp32.overlay index e7e6e21..104bdcb 100644 --- a/zephcore/boards/common/pm_esp32.overlay +++ b/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. *