HaloKeymind/docs/optional_screens.md

View this page on MeshCore Docs.

Optional screens

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 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 describes automatic screen detection only when the selected application has been verified to contain it. Previously published firmware retains its original behavior. These additions become available as new firmware is built and qualified; changing the picker does not add detection to an older download.

Manufacturer-confirmed optional screens

Hardware	Manufacturer evidence	Firmware behavior
Heltec T114	Heltec offers the optional stock screen.	Automatic ST7789 detection; see the T114 guide.
Heltec RC32 with T108	The T108 is a separate pin-header display module. The manufacturer example documents its pins and power controls.	New display-capable images detect the NV3001B panel. Legacy without_display targets remain headless compatibility builds.
Heltec Wireless Tracker V1/V1.1	The manufacturer listing explicitly offers Screen Yes/No.	New display-capable images detect the ST7735 panel. Its absence releases only the display's power claim; GPS retains its own claim on the shared supply.
Heltec V4 R8 Expansion Kit	The manufacturer kit offers front-panel configurations; its V2 expansion schematic connects the display's separate return line.	New R8 TFT images detect the panel through the documented MISO pin. Existing touch reset and backlight-only sleep/wake behavior are retained.
Heltec V4/V4 R8 OLED	The manufacturer listing offers OLED and No Display configurations.	Existing SSD1306 images already check whether the OLED responds.
RAK WisBlock	The RAK4631 kit guide labels the RAK1921 OLED optional.	Display-capable RAK4631 and RAK3401 images check presence and detect SSD1306 or SH1106 controllers. New images also provide a saved controller choice; see below.
iKoka Stick and Handheld	The designer documents an optional Stick OLED and optional Handheld OLED.	Existing display-capable images already check presence. Handheld Companion supports the screen; currently headless infrastructure recipes remain headless.
Original LilyGo T-Beam	LilyGo offers soldered/non-soldered OLED configurations.	Existing display-capable SSD1306 images already check presence.
XIAO ESP32-S3 with Wio-SX1262	Seeed lists the expansion board as an accessory for adding screens and sensors.	Existing display-capable Companion images already check presence.
Muzi Base Uno/Duo with SuperIO	SuperIO 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 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.

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.

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 roles. Keep auto for normal use; choose the panel's controller explicitly if detection gives shifted or wrapped pixels. The choice is saved and applies after restarting the node. get display.controller shows the configured and active choices and any pending restart. With no saved choice, automatic detection or an existing build-time override supplies the default; saved auto takes precedence over that override. Normal controller selection does not require custom firmware. See the controller commands.

New R8 TFT images support saved display.rotation values of 0, 90, 180 and 270, including portrait/landscape dashboard changes without reflashing. The stock R8 expansion board has no accelerometer for automatic orientation. See the rotation commands.

The variant consolidation validation records the ten qualified packages, software checks and remaining physical tests for R8 rotation, Muzi SuperIO and T-Echo Lite detection.

Full Wireless Tracker repeaters retain the board's 50-neighbor capacity, as the V1.1 and V2 Full profiles already do. This preserves RAM for the screen, GPS, MQTT and update services; the RAM admission limits remain unchanged.

The R8 readback route is documented in Heltec's Expansion Kit V2.03 schematic. Tracker V1 wiring is documented in the V1.1 schematic.

Screen presence does not establish controller type, dimensions, physical orientation, or board revision. Continue choosing the exact hardware profile. Use USB when changing an old firmware target name; a different target's LoRa update package is not interchangeable. Saved identity and settings do not need to be erased for screen detection.

Integral screens

Manufacturer documentation identifies built-in screens on the LilyGo T-Echo Card, Heltec T190, T1, T096, Wireless Tracker V2, ThinkNode M9 and T-Deck. No new optional-screen detection is enabled for these boards. In particular, the T190's optional module is its LoRa radio, not its screen.

Validation

The new probes run before display SPI initialization and framebuffer allocation, with the backlight off. Bounded repeated reads under opposite pull directions reject floating, stuck and unstable return lines. An absent screen stays disabled until reboot; later drawing or wake requests cannot power it back up. Shared supplies retain other peripherals' ownership.

Native tests cover controller replies, timing, pin turnaround, power ownership, headless behavior, rendering, sleep/wake, and exclusions for integral screens. Release checks require the detection marker in the uploadable application, the exact resolved board/driver flags and the matching source commit before the picker can advertise detection.

Check	Result
Native detection, rendering, power and headless regressions	PASS, 31 test methods, including 12 new detection methods with sanitizers and negative controls
Recipe, release-proof, controls and offline-picker regressions	PASS, 42 test methods
Resolved PlatformIO configuration	PASS, 31 optional-screen environments across the three hardware families; integral-screen recipes excluded
Picker JavaScript regressions	PASS, 4 suites
Complete build-profile selection suite	PASS
Hosted documentation links	PASS, 7 test methods
Packaged ESP32 firmware smoke builds	PASS, RC32 Full Companion, Tracker V1 Full Repeater/MQTT, Tracker V1.1 Full Repeater/MQTT, and V4 R8 TFT Full Companion

The qualified smoke packages use firmware source 8268befbd. All four uploadable applications contain their board-specific detection marker and matching firmware/source version. Their bound package hashes and generated picker controls pass verification. RAM headroom after the complete modeled allocation and transient margin is 68,672 bytes for RC32, 1,942 for Tracker V1, 4,054 for Tracker V1.1, and 66,528 for V4 R8 TFT. These are build-time admission results, not measurements of physical runtime load.

Physical verification on RC32, Tracker V1 and V4 R8 with and without their manufacturer-supported screen has not been performed. Hardware qualification requires cold USB/battery boots, screen sleep/wake, headless input, normal radio transmit/receive, and GPS or touch operation where fitted.