Unify Heltec V4 OLED, TFT and headless display selection

Detect OLED or the original stock TFT touch assembly in ordinary V4.2/V4.3
images. Add saved live display.type auto/oled/tft/off selection and report
the active selection in board output. Keep sensors on primary I2C, preserve
shared power, and isolate TFT FSPI from radio HSPI through sleep and changes.

Consolidate future picker/build choices only with application capability
proof. Retain exact legacy OTA identities and separate R8 hardware images.
Document controls and physical qualification limits.

Validation: five serialized Full builds with capability/size/RAM checks;
focused host tests, existing R8/T-Deck/OLED regressions, build-profile suite,
and picker/provider tests. V4.3 OLED live changes and off/auto reboot
persistence passed on Mercerwood. Physical TFT qualification remains pending.

docs/_javascript/firmware_picker.js

@@ -822,8 +822,20 @@
       releaseBoundControl(profile, "combinedCompanion"));
   }
 
+  function unifiedV4DisplayProfile(profile) {
+    return Boolean(profile && profile.hardware === "heltec_v4" &&
+      profile.controls && profile.controls.platform === "ESP32_PLATFORM" &&
+      profile.controls.display === true && releaseBoundControl(profile, "unifiedV4Display"));
+  }
+
   function consolidationSuccessor(profile, candidate) {
     if (!profile || !candidate || profile.role !== candidate.role) return false;
+    if (/^heltec_v4(?:_3)?(?:_expansionkit)?(?:_tft)?$/.test(profile.hardware) &&
+        profile.hardware !== "heltec_v4" && unifiedV4DisplayProfile(candidate)) {
+      return candidate.feature === profile.feature && candidate.ota === profile.ota &&
+        (!profile.sensorProfile || profile.sensorProfile === candidate.sensorProfile) &&
+        (profile.role !== "companion" || isFullCompanion(candidate));
+    }
     if (/^PicoW_companion_radio_(usb|ble|wifi)$/.test(profile.target)) {
       return combinedPicoCompanion(candidate);
     }
@@ -1725,6 +1737,10 @@
       requested[field] = params.get(field) || "";
     });
     [
+      ...["heltec_v4_3", "heltec_v4_tft", "heltec_v4_3_tft", "heltec_v4_expansionkit",
+        "heltec_v4_expansionkit_tft", "heltec_v4_3_expansionkit_tft"].map(function (hardware) {
+        return [hardware, "heltec_v4", unifiedV4DisplayProfile];
+      }),
       ["heltec_rc32_without_display", "heltec_rc32", function (profile) { return optionalAutoDisplayProfile(profile); }],
       ["heltec_v4_expansionkit", "heltec_v4", function (profile) { return ["repeater", "room"].includes(profile.role) && releaseBoundControl(profile, "oledExpansionCompatible"); }],
       ["heltec_v4_r8_tft_portrait", "heltec_v4_r8_tft", function (profile) { return ["repeater", "room"].includes(profile.role) && releaseBoundControl(profile, "displayRotation"); }],
@@ -2011,6 +2027,10 @@
     if (combinedPicoCompanion(profile)) {
       notes.push("This Companion image includes USB, Bluetooth LE and WiFi together. Separate transport firmware is unnecessary; this image does not add a wireless firmware updater.");
     }
+    if (unifiedV4DisplayProfile(profile)) {
+      notes.push("One ordinary Heltec V4 image supports V4.2/V4.3 with OLED, the stock touch TFT kit, or no screen. The saved display.type setting selects auto, oled, tft or off; board reports the detected revision and active display. R8 uses its separate hardware image.");
+      notes.push("When changing from a legacy TFT or expansion-kit target, use a local USB installation or a supported WiFi application update. Their LoRa OTA target IDs remain distinct; never force a different target's LoRa OTA package.");
+    }
     if (releaseBoundControl(profile, "oledExpansionCompatible")) {
       notes.push("The same OLED firmware supports the base Heltec V4 and its OLED expansion kit. Existing expansion-kit OTA identities still require their exact historical update or a local USB migration.");
     }
@@ -2375,6 +2395,9 @@
     if (infrastructure && (info.updateMethods || []).includes("bluetooth")) section("Bluetooth firmware update", [
       { label: "Start DFU", commands: ["start ota"], text: "Use the exact board's application DFU ZIP with the matching Bluetooth-capable bootloader." },
     ]);
+    if (unifiedV4DisplayProfile(profile)) section("Display type", ["auto", "oled", "tft", "off"].map(function (type) {
+      return {label: type === "auto" ? "Automatic" : type === "off" ? "Screen off" : type.toUpperCase(), commands: ["set display.type " + type]};
+    }), "Saved choice applies immediately. Check with get display.type and board. Automatic mode continues without a screen if no supported display is detected.");
     if ((full || releaseBoundControl(profile, "displayRotation")) && info.display) section("Display rotation", [0, 90, 180, 270].map(function (angle) {
       return { label: angle === 0 ? "Board default" : angle + " degrees", commands: ["set display.rotation " + angle] };
     }), "Use on supported displays; 0 restores the board default. Check with get display.rotation.");

docs/cli_commands.md

@@ -1310,6 +1310,40 @@ build flag is needed.
 
 ---
 
+## Select the original Heltec V4 display
+
+New unified original-V4 images support V4.2/V4.3 OLED, the original TFT
+touchscreen expansion kit, and operation without a screen. This feature is
+not present in the older 1.17.1.1 or 1.17.1.5 images. V4 R8 remains a separate
+hardware target.
+
+```text
+get display.type
+set display.type auto
+set display.type oled
+set display.type tft
+set display.type off
+board
+```
+
+The default `auto` requires an OLED I2C response or a stable identity from the
+stock TFT assembly's touch controller. No OLED response alone is not evidence
+of a TFT. When neither responds, the node runs without a screen and `board`
+reports `none detected`. Touch identification establishes the stock assembly,
+not LCD health. A damaged or nonstandard panel can require an override.
+
+`oled` explicitly selects and checks the OLED driver. `tft` explicitly selects
+the TFT driver and reports `TFT (forced)` rather than claiming detection.
+`off` disables display initialization and reports `off`, distinct from
+`none detected`. Selections apply immediately and survive reboot in the checked
+`/display_type` file. A failed save leaves the live selection unchanged.
+
+`board` combines the detected radio front end with the live display status,
+for example `Heltec V4.3 OLED`, `Heltec V4.2 TFT`, or `Heltec V4.3 off`.
+The radio front end identifies the V4.2/V4.3 hardware generation; it is not a
+read of a PCB revision register. Use `display.mode` below for normal screen
+sleep/wake policy without changing the selected hardware driver.
+
 ## Set display modes and timeouts
 
 Companion message sound, vibration, LED, screen and GPIO rules have separate

docs/firmware_picker.md

@@ -338,6 +338,14 @@ SSD1306 Full Companion builds use `set display.rotation 90|180|270`; `0`
 restores the board default, so a separate rotated release image is not
 recommended.
 
+Newly built ordinary Heltec V4 images combine V4.2/V4.3, OLED, the stock touch
+TFT kit, and no screen in one image per role. A qualified image offers saved
+`display.type auto|oled|tft|off` controls; selection applies immediately, and
+`board` reports the detected revision and active display. R8 remains separate.
+Older TFT/expansion-kit target names retain their distinct LoRa OTA identities;
+use USB or supported WiFi updating when moving to the canonical image. Older
+published downloads keep their original behavior. See [optional screens](optional_screens.md#heltec-v42-v43).
+
 New display-capable RAK4631 and RAK3401 images with OLED controller detection
 also offer saved `display.controller` choices: `auto`, `ssd1306` or `sh1106`.
 This applies after restart and avoids a custom image when a panel needs an

docs/optional_screens.md

@@ -7,7 +7,9 @@
 Use the normal display-capable firmware for your exact board and role. When
 automatic detection is included, that image starts the supported screen if
 it responds, or continues headless if it is absent. There is no screen-presence
-setting. Power the board off before attaching or removing an optional screen.
+setting on most boards. The unified ordinary Heltec V4 image also offers a
+saved display override, described below. Power the board off before attaching
+or removing an optional screen.
 
 The [firmware picker](firmware_picker.md) describes automatic screen detection
 only when the selected application has been verified to contain it. Previously
@@ -31,10 +33,34 @@ add detection to an older download.
 | Muzi Base Uno/Duo with SuperIO | [SuperIO](https://muzi.works/products/super-io) adds the OLED, GPS, buttons and buzzer to the matching Base radio. | New Companion images probe the SH1107 display, leave its 12 V supply off when absent, and discover GPS independently. Uno and Duo retain their different radio drivers. |
 | LilyGo T-Echo Lite core/display assembly | [LilyGo](https://lilygo.cc/en-us/products/t-echo-lite) documents the split core/base design. | New Companion images check SSD1681 status readback before e-paper initialization and continue headless when the panel does not respond. The old non-shell target names remain compatibility recipes. |
 
-The older V4 TFT expansion configuration is also optional, but its current
-recipe has no verified panel readback connection. Detection is not enabled for
-that wiring. A touchscreen acknowledgement alone does not establish that the
-LCD responds. The V4 R8 TFT and older V4 TFT pin mappings are distinct.
+## Heltec V4.2 / V4.3
+
+New ordinary V4 images combine OLED, the original stock touch TFT expansion
+kit, and operation without a screen in one image per role. The OLED probe uses
+its own I2C bus; a verified CHSC6xxx touch-controller identity selects the stock
+TFT assembly. This identifies the touchscreen assembly, not a working LCD.
+With neither display detected, the firmware continues without a screen.
+
+`get display.type` reports the saved choice and active display. Use
+`set display.type auto|oled|tft|off` to change it immediately and save the choice.
+`auto` is the default. `off` explicitly disables rendering; it is distinct from
+an absent or unrecognized screen. `board` reports the radio front-end revision
+and active display, including the off/headless states. V4.2/V4.3 is inferred
+from the detected radio front end, rather than reading a PCB revision code.
+
+This change applies to newly built and qualified unified images. Existing
+releases retain their compiled OLED/TFT behavior. The picker advertises the
+combined image only when its application and source-bound metadata prove that
+it includes the new driver. V4.3 OLED detection, live selection and reboot
+persistence passed on the Mercerwood test board. Physical TFT detection and
+display operation remain unqualified. See the [validation record](test-results/firmware_variant_consolidation.md#unified-ordinary-v4-update-2026-10-26).
+
+The V4 R8 retains its separate hardware image because its memory configuration
+and display wiring differ. Older TFT/expansion-kit target names remain explicit
+compatibility builds with their original LoRa OTA identity. Moving to the
+canonical ordinary V4 image requires a local USB installation or an updater
+that accepts the matching application over WiFi. Do not force a different
+LoRa OTA target ID. No settings erase is required for display selection.
 
 RAK4631 and RAK3401 images with OLED controller detection support
 `set display.controller auto`, `ssd1306` or `sh1106` in all display-enabled

docs/test-results/firmware_variant_consolidation.md

@@ -67,3 +67,45 @@ The production controls generator and picker used release metadata assembled fro
 These checks are required before describing the hardware combinations as physically qualified.
 
 The earlier [optional-screen record](../optional_screens.md#validation) covers separate RC32 and Tracker smoke packages; those are not part of this ten-profile matrix.
+
+## Unified ordinary V4 update - 2026-10-26
+
+New original-V4 builds combine OLED, the stock touch TFT kit and headless
+operation. `display.type` defaults to `auto`; saved `oled`, `tft` and `off`
+overrides apply immediately. `board` reports the radio front end's V4.2/V4.3
+generation and live display selection. R8 retains its separate hardware image.
+
+All five Full packages below passed serialized compilation, application size,
+capability-marker and runtime RAM admission checks. Test version:
+`v1.18.0.2-display-test-a87b2a33`, built from the working implementation based
+on `a87b2a33a`. The application hashes distinguish these local test builds.
+
+| Target | Application bytes | RAM admission margin (bytes) | SHA-256 prefix |
+| --- | ---: | ---: | --- |
+| V4 Full Companion | 2,545,128 | 25,328 | `d90b050b9892` |
+| V4 Full Repeater | 2,140,920 | 3,912 | `9e1bf8b7c31a` |
+| V4 Full Room Server | 2,139,400 | 18,040 | `8d3cddf67659` |
+| V4 Full Sensor | 1,524,472 | 123,112 | `6bd02f499a4a` |
+| Legacy TFT Repeater identity | 1,784,936 | 50,936 | `7c47a7825100` |
+
+The ten focused detection/integration tests pass, including absent and invalid
+panels, saved-setting recovery, live switching, clock wrap and headless
+Companion notifications/battery checks. They also verify that display sleep
+keeps the sensor power rail intact, sensors retain primary I2C, and TFT FSPI
+cleanup cannot stop the radio's separate HSPI controller. Shared R8, T-Deck
+and OLED regressions pass, as do build-profile and picker/provider checks.
+
+The Mercerwood V4.3 OLED passed automatic detection, live off/auto/oled changes,
+off and auto persistence across reboot, accurate `board` output and USB CLI
+responses. Its original display power preferences were retained. Only the
+active application was flashed; partitions and stored device data were kept.
+The final image also passed a save/logging smoke check: no false missing-file
+errors. Native USB needed one additional monitored RTS reset after esptool's
+flash/reset handoff before the terminal responded; later application reboots
+passed the persistence checks.
+
+Physical TFT identity/readback, visible rendering and sleep/wake still require
+the original stock kit. Screen-absent hardware and V4.2 hardware were covered
+by software tests, not a physical run. These display checks do not qualify
+maximum MQTT/TLS load, radio throughput or sleep current. Existing published
+images and LoRa update identities were not changed.