From 3290fa2f5774473b1f61e7a3ca520060e3071daf Mon Sep 17 00:00:00 2001 From: MarekZegare4 Date: Wed, 12 Aug 2026 23:36:34 +0200 Subject: [PATCH] fix(heltec): joystick press drives Enter, PRG becomes Back Swaps which physical input plays which role on the Heltec V3/V4 wired joystick: the stick's own fifth "press" contact now drives Enter (your thumb's already on the stick when you'd confirm something), and the onboard PRG button -- previously Enter -- becomes Back instead, so it no longer needs a separate wired button of its own. Pure pin reassignment in the solo_dual envs, no UITask.cpp changes: PIN_USER_BTN (Enter) is undef'd and redefined from the base env's PRG default to the joystick's press pin, and PIN_BACK_BTN takes PRG's old GPIO0. Scoped to just these two envs -- Wio Tracker L1/GAT562/MeshTiny share the same UI_HAS_JOYSTICK code path with PRG already correctly wired as their one true physical button, so their behaviour is untouched. Co-Authored-By: Claude Sonnet 5 --- README.md | 4 ++-- docs/solo_features/external_keyboard.md | 19 ++++++++++--------- variants/heltec_v3/platformio.ini | 19 +++++++++++++------ variants/heltec_v4/platformio.ini | 19 +++++++++++++------ 4 files changed, 38 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 5778cf09..08bcf1ab 100644 --- a/README.md +++ b/README.md @@ -126,8 +126,8 @@ A single button can't drive the solo UI, and neither Heltec board has a joystick | Joystick DOWN | **6** | | | Joystick LEFT | **47** | | | Joystick RIGHT | **48** | | -| Back button | **33** | required whenever the joystick is enabled | -| Centre / Enter | **0** | the onboard PRG button — nothing to wire | +| Joystick press — Enter | **33** | the stick's own fifth contact; required whenever the joystick is enabled | +| Back | **0** | the onboard PRG button — nothing to wire | Each joystick contact simply shorts its pin to GND — the firmware enables the internal pull-ups, so no external resistors are needed. CardKB needs power and ground alongside SDA/SCL; check your unit's own voltage rating before picking a rail. diff --git a/docs/solo_features/external_keyboard.md b/docs/solo_features/external_keyboard.md index 0ee34047..27f99a51 100644 --- a/docs/solo_features/external_keyboard.md +++ b/docs/solo_features/external_keyboard.md @@ -80,14 +80,15 @@ so they behave identically in both modes. ## Wired joystick -Four direction contacts plus a separate Back button. Each contact simply shorts -its pin to ground — the firmware enables the internal pull-ups, so no external -resistors are needed. +Four direction contacts plus a fifth "press" contact. Each contact simply +shorts its pin to ground — the firmware enables the internal pull-ups, so no +external resistors are needed. -- The board's existing user button (PRG on the Heltec boards) stays the - centre / Enter press. -- Back is **not** optional: the UI uses it unconditionally once the joystick is - enabled. Triple-clicking Back toggles the buzzer. +- The stick's own press contact drives the centre / Enter press — your thumb + is already on the stick, so pressing it in is the natural "confirm" action. +- The board's existing user button (PRG on the Heltec boards) becomes Back + instead. Back is **not** optional: the UI uses it unconditionally once the + joystick is enabled. Triple-clicking Back toggles the buzzer. - **Settings › Display › Joystick rotation** rotates the direction mapping at runtime (0–3), for a stick mounted sideways in a custom enclosure. It is independent of display rotation. @@ -109,8 +110,8 @@ hardware**; still worth checking against your own V3 module before soldering. | Joystick DOWN | 6 | | | Joystick LEFT | 47 | | | Joystick RIGHT | 48 | | -| Back button | 33 | required when the joystick is enabled | -| Centre / Enter | 0 | the onboard PRG button — nothing to wire | +| Joystick press — Enter | 33 | the stick's own fifth contact; required when the joystick is enabled | +| Back | 0 | the onboard PRG button — nothing to wire | Everything above lives in the `[env:Heltec_v3_companion_solo_dual]` / `[env:heltec_v4_companion_solo_dual]` blocks in diff --git a/variants/heltec_v3/platformio.ini b/variants/heltec_v3/platformio.ini index 79089549..e51095c6 100644 --- a/variants/heltec_v3/platformio.ini +++ b/variants/heltec_v3/platformio.ini @@ -198,10 +198,13 @@ lib_deps = ; Pair it with Settings > Keyboard > Ext. KB = Compact, which is designed to ; need no joystick at all. The same bus is scanned for environment sensors. ; -; * Wired joystick: four direction pins plus a separate Back button -- the UI -; uses Back unconditionally once UI_HAS_JOYSTICK is set, so it isn't optional. -; PIN_USER_BTN (PRG) stays the centre/Enter press. Each contact just shorts -; its pin to GND; target.cpp enables the internal pull-ups. Drop +; * Wired joystick: four direction pins plus a fifth "press" contact. The +; press contact drives Enter (your thumb's already on the stick) via +; PIN_USER_BTN -- overridden below (-U/-D) from the PRG-button default +; the base env sets, since PRG's GPIO0 can't be moved to the stick. PRG +; becomes Back instead (PIN_BACK_BTN), so it no longer needs its own +; separately-wired button. Each contact just shorts its pin to GND; +; target.cpp enables the internal pull-ups. Drop ; UI_HAS_JOYSTICK_UPDOWN for a left/right-only stick. JOYSTICK_ROTATION (0-3) ; rotates the mapping if the stick is mounted sideways -- it's also a runtime ; setting, so leave it out unless you want a different default. @@ -237,14 +240,18 @@ build_flags = ; CardKB on the second I2C bus. Harmless with nothing plugged in. -D ENV_PIN_SDA=3 -D ENV_PIN_SCL=4 - ; Wired joystick — comment the block out for a CardKB-only build. + ; Wired joystick — comment the block out for a CardKB-only build. The + ; press contact (Enter) overrides PIN_USER_BTN from its PRG default; + ; PRG becomes Back (PIN_BACK_BTN) instead. -D UI_HAS_JOYSTICK=1 -D UI_HAS_JOYSTICK_UPDOWN=1 -D JOYSTICK_UP=23 -D JOYSTICK_DOWN=6 -D JOYSTICK_LEFT=47 -D JOYSTICK_RIGHT=48 - -D PIN_BACK_BTN=33 + -D PIN_BACK_BTN=0 ; PRG button + -U PIN_USER_BTN + -D PIN_USER_BTN=33 ; joystick press contact -- Enter ; -D PIN_BUZZER= build_src_filter = ${Heltec_lora32_v3.build_src_filter} + diff --git a/variants/heltec_v4/platformio.ini b/variants/heltec_v4/platformio.ini index 1e257019..273db83b 100644 --- a/variants/heltec_v4/platformio.ini +++ b/variants/heltec_v4/platformio.ini @@ -247,10 +247,13 @@ lib_deps = ; SCL 4, one says the reverse. 3/4 is the pair either way; swap them if the ; keyboard doesn't answer.) ; -; * Wired joystick: four direction pins plus a separate Back button -- the UI -; uses Back unconditionally once UI_HAS_JOYSTICK is set, so it isn't optional. -; PIN_USER_BTN (PRG) stays the centre/Enter press. Each contact just shorts -; its pin to GND; target.cpp enables the internal pull-ups. Drop +; * Wired joystick: four direction pins plus a fifth "press" contact. The +; press contact drives Enter (your thumb's already on the stick) via +; PIN_USER_BTN -- overridden below (-U/-D) from the PRG-button default +; the base env sets, since PRG's GPIO0 can't be moved to the stick. PRG +; becomes Back instead (PIN_BACK_BTN), so it no longer needs its own +; separately-wired button. Each contact just shorts its pin to GND; +; target.cpp enables the internal pull-ups. Drop ; UI_HAS_JOYSTICK_UPDOWN for a left/right-only stick. JOYSTICK_ROTATION (0-3) ; rotates the mapping if the stick is mounted sideways -- it's also a runtime ; setting, so leave it out unless you want a different default. @@ -287,14 +290,18 @@ build_flags = ; CardKB on the second I2C bus. Harmless with nothing plugged in. -D ENV_PIN_SDA=3 -D ENV_PIN_SCL=4 - ; Wired joystick — comment the block out for a CardKB-only build. + ; Wired joystick — comment the block out for a CardKB-only build. The + ; press contact (Enter) overrides PIN_USER_BTN from its PRG default; + ; PRG becomes Back (PIN_BACK_BTN) instead. -D UI_HAS_JOYSTICK=1 -D UI_HAS_JOYSTICK_UPDOWN=1 -D JOYSTICK_UP=23 -D JOYSTICK_DOWN=6 -D JOYSTICK_LEFT=47 -D JOYSTICK_RIGHT=48 - -D PIN_BACK_BTN=33 + -D PIN_BACK_BTN=0 ; PRG button + -U PIN_USER_BTN + -D PIN_USER_BTN=33 ; joystick press contact -- Enter ; -D PIN_BUZZER= build_src_filter = ${heltec_v4_oled.build_src_filter} +