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 <noreply@anthropic.com>

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 |
+| Joystick press — Enter | **33** | the stick's own fifth contact; required whenever the joystick is enabled |
-| Centre / Enter | **0** | the onboard PRG button — nothing to wire |
+| 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.
 

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
+Four direction contacts plus a fifth "press" contact. Each contact simply
-its pin to ground — the firmware enables the internal pull-ups, so no external
+shorts its pin to ground — the firmware enables the internal pull-ups, so no
-resistors are needed.
+external resistors are needed.
 
-- The board's existing user button (PRG on the Heltec boards) stays the
+- The stick's own press contact drives the centre / Enter press — your thumb
-  centre / Enter press.
+  is already on the stick, so pressing it in is the natural "confirm" action.
-- Back is **not** optional: the UI uses it unconditionally once the joystick is
+- The board's existing user button (PRG on the Heltec boards) becomes Back
-  enabled. Triple-clicking Back toggles the buzzer.
+  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 |
+| Joystick press — Enter | 33 | the stick's own fifth contact; required when the joystick is enabled |
-| Centre / Enter | 0 | the onboard PRG button — nothing to wire |
+| 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

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
+;  * Wired joystick: four direction pins plus a fifth "press" contact. The
-;    uses Back unconditionally once UI_HAS_JOYSTICK is set, so it isn't optional.
+;    press contact drives Enter (your thumb's already on the stick) via
-;    PIN_USER_BTN (PRG) stays the centre/Enter press. Each contact just shorts
+;    PIN_USER_BTN -- overridden below (-U/-D) from the PRG-button default
-;    its pin to GND; target.cpp enables the internal pull-ups. Drop
+;    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=<gpio>
 build_src_filter = ${Heltec_lora32_v3.build_src_filter}
   +<helpers/ui/SSD1306Display.cpp>

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
+;  * Wired joystick: four direction pins plus a fifth "press" contact. The
-;    uses Back unconditionally once UI_HAS_JOYSTICK is set, so it isn't optional.
+;    press contact drives Enter (your thumb's already on the stick) via
-;    PIN_USER_BTN (PRG) stays the centre/Enter press. Each contact just shorts
+;    PIN_USER_BTN -- overridden below (-U/-D) from the PRG-button default
-;    its pin to GND; target.cpp enables the internal pull-ups. Drop
+;    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=<gpio>
 build_src_filter = ${heltec_v4_oled.build_src_filter}
   +<helpers/ui/SSD1306Display.cpp>