feat(heltec): solo dual-transport builds for Heltec V3/V4

Port the Wio Tracker L1 solo firmware (full on-device UI, dual BLE/USB
companion transport) to Heltec V3 and V4 OLED boards. Neither board has
a joystick or CardKB on-board, so each new env wires up both as optional
peripherals with default pins from what the board leaves free, gated
behind the existing UI_HAS_JOYSTICK/ENV_PIN_SDA+SCL flags.

DUAL_SERIAL was nRF52-only; added an ESP32 helpers/esp32/DualSerialInterface.h
counterpart so the flag isn't silently ignored on these boards. On V4's
native USB CDC, isClientConnected() also honours (bool)Serial (real DTR),
same as the nRF52 version; V3 has no native CDC so it stays BLE-only there.

Screen (SDA 17/SCL 18) and CardKB (SDA 3/SCL 4) confirmed working on real
V4 hardware.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

variants/heltec_v3/platformio.ini

@@ -179,6 +179,84 @@ lib_deps =
   ${Heltec_lora32_v3.lib_deps}
   densaugeo/base64 @ ~1.4.0
 
+; Solo build: the full standalone on-device UI (message history, contacts, map,
+; tools) rather than a screen that only mirrors the phone app. Dual transport --
+; the companion app can attach over BLE or USB serial, whichever it finds, and
+; BLE wins while both are live.
+;
+; This firmware needs a real input device: the solo UI cannot be driven from the
+; PRG button alone. Both supported ones are wired up in target.cpp and enabled
+; below, so either is enough on its own and having both is fine. The pins are
+; defaults picked from what this board leaves free -- change them to match how
+; the device is actually built. Pins with nothing attached read as not-pressed,
+; so the unused half costs nothing.
+;
+;  * CardKB (M5Stack I2C keyboard, addr 0x5F) on a second I2C bus. Any two free
+;    GPIOs -- NOT 17/18, the OLED already owns those on Wire. It's probed at
+;    boot, so a build with these set still runs fine with nothing plugged in.
+;    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.
+;    Defaults below: SDA 41, SCL 42.
+;
+;  * 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
+;    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.
+;    Comment the whole block out for a CardKB-only build. UI_HAS_JOYSTICK
+;    replaces the single-button handling rather than adding to it (UITask.cpp
+;    dispatches on '#if UI_HAS_JOYSTICK ... #elif defined(PIN_USER_BTN)'), which
+;    costs nothing here -- that fallback only feeds KEY_NEXT/KEY_PREV, which the
+;    solo screens don't act on.
+;
+; Pins already taken on this board: 8/9/10/11/13/14 (LoRa), 17/18 (OLED I2C),
+; 21 (OLED reset), 0 (PRG), 35 (TX LED), 36 (VEXT), 37 (ADC ctrl), 1 (battery
+; ADC), 26/47/48 (GPS). On top of that the ESP32-S3 reserves 19/20 (USB), 26-32
+; (flash) and 43/44 (UART0), and 0/3/45/46 are strapping pins. That leaves
+; 2, 4-7, 33/34 and 38-42, which is where the defaults below come from -- verify
+; against your own module before soldering. The GPS defines above already look
+; optimistic: on a quad-flash S3, GPIO26 is a flash line.
+[env:Heltec_v3_companion_solo_dual]
+extends = Heltec_lora32_v3
+build_flags =
+  ${Heltec_lora32_v3.build_flags}
+  -I examples/companion_radio/ui-new
+  -D MAX_CONTACTS=350
+  -D MAX_GROUP_CHANNELS=40
+  -D DISPLAY_CLASS=SSD1306Display
+  -D BLE_PIN_CODE=123456   ; dynamic, random PIN
+  -D DUAL_SERIAL=1         ; companion app over BLE *or* USB serial
+  -D AUTO_SHUTDOWN_MILLIVOLTS=3400
+  -D OFFLINE_QUEUE_SIZE=256
+  -D FIRMWARE_SOLO_BUILD=1
+  -D UI_SENSORS_PAGE=1
+  -D OLED_MISC_FIXED_FONT=1   ; full Latin/Greek/Cyrillic 6x9 font, ~14 KB flash
+  ; CardKB on the second I2C bus. Harmless with nothing plugged in.
+  -D ENV_PIN_SDA=41
+  -D ENV_PIN_SCL=42
+  ; Wired joystick — comment the block out for a CardKB-only build.
+  -D UI_HAS_JOYSTICK=1
+  -D UI_HAS_JOYSTICK_UPDOWN=1
+  -D JOYSTICK_UP=4
+  -D JOYSTICK_DOWN=5
+  -D JOYSTICK_LEFT=6
+  -D JOYSTICK_RIGHT=7
+  -D PIN_BACK_BTN=2
+;  -D PIN_BUZZER=<gpio>
+build_src_filter = ${Heltec_lora32_v3.build_src_filter}
+  +<helpers/ui/SSD1306Display.cpp>
+  +<helpers/ui/MomentaryButton.cpp>
+  +<helpers/ui/buzzer.cpp>
+  +<helpers/esp32/*.cpp>
+  +<../examples/companion_radio/*.cpp>
+  +<../examples/companion_radio/ui-new/*.cpp>
+lib_deps =
+  ${Heltec_lora32_v3.lib_deps}
+  densaugeo/base64 @ ~1.4.0
+  end2endzone/NonBlockingRTTTL@^1.3.0
+
 [env:Heltec_v3_companion_radio_wifi]
 extends = Heltec_lora32_v3
 build_flags =

variants/heltec_v3/target.cpp

@@ -26,6 +26,20 @@ AutoDiscoverRTCClock rtc_clock(fallback_clock);
 #ifdef DISPLAY_CLASS
   DISPLAY_CLASS display;
   MomentaryButton user_btn(PIN_USER_BTN, 1000, true);
+  #if UI_HAS_JOYSTICK
+    // Optional wired joystick — see the Heltec_v3_companion_solo_dual env for the
+    // pin defines this needs. Unlike the Wio Tracker L1 (external pull-ups on
+    // board) these pass pulldownup = true, so each contact only has to short its
+    // pin to GND; the internal pull-up does the rest. Back gets multiclick = true
+    // because the UI's triple-click buzzer toggle lives on it.
+    MomentaryButton joystick_left (JOYSTICK_LEFT,  1000, true, true, false);
+    MomentaryButton joystick_right(JOYSTICK_RIGHT, 1000, true, true, false);
+    MomentaryButton back_btn      (PIN_BACK_BTN,   1000, true, true, true);
+    #if UI_HAS_JOYSTICK_UPDOWN
+      MomentaryButton joystick_up  (JOYSTICK_UP,   1000, true, true, false);
+      MomentaryButton joystick_down(JOYSTICK_DOWN, 1000, true, true, false);
+    #endif
+  #endif
 #endif
 
 bool radio_init() {

variants/heltec_v3/target.h

@@ -21,6 +21,15 @@ extern EnvironmentSensorManager sensors;
 #ifdef DISPLAY_CLASS
   extern DISPLAY_CLASS display;
   extern MomentaryButton user_btn;
+  #if UI_HAS_JOYSTICK
+    extern MomentaryButton joystick_left;
+    extern MomentaryButton joystick_right;
+    extern MomentaryButton back_btn;
+    #if UI_HAS_JOYSTICK_UPDOWN
+      extern MomentaryButton joystick_up;
+      extern MomentaryButton joystick_down;
+    #endif
+  #endif
 #endif
 
 bool radio_init();