Heltec V4: System freeze during radio transmission with custom UI (LVGL overlay)

[xMIKx]

Hardware

Board: Heltec LoRa V4 (ESP32-S3, 16MB Flash, 2MB PSRAM)
Display: ST7796 320x480 TFT via SPI3
Touch: FT5x06 capacitive touch via I2C
Firmware: Meshtastic 2.7.13.163842d alpha

Description
Screen/UI freezes when radio attempts to transmit packets after AES encryption. Freeze occurs consistently at the first NodeInfo broadcast (~147 seconds after boot) or when sending messages via app. The issue ONLY occurs with custom LVGL UI overlay - official firmware works perfectly.
Expected Behavior
Radio should successfully transmit packets after encryption, as it does with official firmware.
Actual Behavior (CORRECTED)
System crashes and automatically reboots during/after radio transmission following “Use AES128 key!” log. The device enters a crash-reboot loop:
• Serial output stops at “Use AES128 key!”
• Screen UI freezes (blinking UI dot stops blinking) but screen stays on for a while (exact timing unknown)
• Then crashes - board reboots and screen turns off then back on, display dot starts blinking again (confirms device rebooted)
• Serial connection breaks - no boot logs appear in monitor
• Device boots and crashes again at same point (~147 seconds later)
• Cycle repeats indefinitely

Logs
INFO | ??:??:?? 146 [NodeInfo] Send our nodeinfo to mesh (wantReplies=0)
INFO | ??:??:?? 146 [NodeInfo] Send owner !b2a7c154/Meshtastic c154/c154
DEBUG | ??:??:?? 146 [NodeInfo] Initial packet id 335703107
DEBUG | ??:??:?? 146 [NodeInfo] Partially randomized packet id 1544295492
DEBUG | ??:??:?? 146 [NodeInfo] Ignore update from self
DEBUG | ??:??:?? 146 [NodeInfo] handleReceived(LOCAL) (id=0x5c0c1444 fr=0xb2a7c154 to=0xffffffff, transport = 0, WantAck=0, HopLim=3 Ch=0x0 Portnum=4 priority=10)
DEBUG | ??:??:?? 146 [NodeInfo] No modules interested in portnum=4, src=LOCAL
INFO | ??:??:?? 146 [NodeInfo] Packet History - insert: Using new slot @uptime 146.442s TRACE NEW
DEBUG | ??:??:?? 146 [NodeInfo] Expand short PSK #1
DEBUG | ??:??:?? 146 [NodeInfo] Use AES128 key!
[SYSTEM FREEZES HERE - no further logs, no reboot]
Custom Overlay Details

Display Library: LovyanGFX (local lib, same version that works on V3)
UI Framework: LVGL 8.x
SPI Configuration: SPI3_HOST, DMA_CH_AUTO
Display Pins: SCLK=3, MOSI=4, DC=26, CS=33, RST=48
LVGL Buffer: 320x40 static array in internal RAM (confirmed via address check)

What We've (Claude and I) Tested
✅ Confirmed working:

Official Meshtastic 2.7.13/2.7.14 firmware on same V4 hardware (no freeze)
Identical custom overlay code on Heltec V3 hardware (no freeze)
Minimal code with NO display operations (radio works perfectly)

❌ All cause freeze:

Full LVGL overlay with custom screens
Minimal overlay with just tft.fillCircle() (no LVGL)
Any display operations running when radio transmits

Attempted fixes (all failed):

Different DMA channels (1, 2, 3, disabled)
Different SPI hosts (SPI2_HOST, SPI3_HOST)
Deferred LGFX initialization (after radio init)
LVGL buffer in internal RAM vs PSRAM
Disabling touch input
Adding delays before/after radio operations
Pausing LVGL during transmission attempts

Root Cause Theory (May be Incorrect)
V4 has external QSPI PSRAM while V3 has internal PSRAM. We suspect concurrent access to external PSRAM by both the LoRa radio driver and display operations causes a deadlock/race condition during radio transmission. The freeze happens specifically during the transmission phase after encryption completes, suggesting the radio driver's DMA or interrupt handling conflicts with display SPI operations.
Comparison with Working V3
The exact same custom overlay code works perfectly on Heltec V3 (ESP32, internal PSRAM). The ONLY hardware difference between V3 and V4 that affects this is the external PSRAM architecture.

Request
From the application/overlay side, we have not found a configuration that avoids this freeze while still using the display. We’re wondering:

Is this a known limitation or bug on the Heltec V4 / ESP32-S3 target when using external PSRAM + SPI display?

Are there recommended constraints (e.g., no DMA on display, specific PSRAM config, task/core affinity) for custom overlays on V4?

Is support for custom UI overlays on V4 something that’s expected to work in 2.7.x, or is it planned for a later stable?

[mverch67]

What measures did you take to prevent concurrent access to the SPI bus?

[xMIKx]

@mverch67 thank you for the follow up!

SPI Bus Protection Measures and Testing Done:

We’ve attempted several approaches to prevent concurrent SPI access, though we may be missing the correct method for V4:

1. Display Library Locking:

• Configured LovyanGFX with cfg.use_lock = true (library’s built-in SPI mutex)
• Assumed this would handle basic SPI arbitration

2. SPI Host Isolation:

• Tested display on both SPI2_HOST and SPI3_HOST
• LoRa radio appears to use its own SPI configuration
• Issue persists regardless of which host is used

3. Manual Synchronization Attempt:

volatile bool radioIsBusy = false;

void enhanced_loopCustomUI() {
    if (!radioIsBusy) {
        lv_timer_handler();
        // display operations
    }
}

// Modified NodeInfoModule to set flag before transmission
radioIsBusy = true;
delay(100);
sendOurNodeInfo(...);
delay(100);
radioIsBusy = false;

Still froze during transmission.

4. DMA Channel Configuration:

• Explicitly tested display with DMA channels 1, 2, 3, and disabled
• Radio uses SPI_DMA_CH_AUTO
• No improvement with any configuration

5. Deferred Initialization:

• Moved all LGFX SPI configuration out of constructor
• Called initialization only after 5-second delay (after radio fully boots)
• Ensured no SPI operations during radio initialization phase
• Still froze at transmission

6. Memory Allocation Testing:

• Forced LVGL framebuffer to internal RAM (MALLOC_CAP_INTERNAL)
• Tested both heap allocation and static arrays
• Tried PSRAM vs internal RAM for all buffers
• No difference in behavior

7. Complexity Reduction:

• Removed all LVGL code - tested with just tft.fillCircle() (raw LovyanGFX)
• No lv_timer_handler(), minimal display operations only
• Still froze during radio transmission

8. Complete Display Removal:

• Tested with zero display operations (empty functions)
• Radio worked perfectly with no freeze
• Confirms display operations cause the conflict

Consistent Behavior Pattern:

The freeze is 100% reproducible:

• Official firmware (no display): ✅ Radio transmits successfully
• Custom overlay with ANY display code: ❌ Freeze at “Use AES128 key!”
• Same code on Heltec V3: ✅ Works perfectly
• V4 with official firmware: ✅ Works perfectly

Serial output always stops here:

DEBUG | Use AES128 key!
[System completely freezes - no crash, no reboot, requires power cycle]

Questions We Have:

1. Is there a V4-specific synchronization mechanism we should use? The official Meshtastic screen code might have access to internal mutexes/semaphores we don’t know about.
2. Could this be PSRAM contention rather than SPI? V4 has external QSPI PSRAM while V3 has internal PSRAM. Both radio buffers and display might access external PSRAM simultaneously.
3. Does the radio driver require exclusive access to something during transmission? The freeze happens AFTER encryption completes, during actual radio transmission, suggesting the radio needs access to a resource (interrupts, DMA, PSRAM) that display operations are blocking.

We’re likely missing the proper approach for V4 custom overlays. Any guidance on the correct synchronization method or known limitations would be greatly appreciated. We’re happy to test any suggested approaches or provide additional debugging information.

[mverch67]

Regarding 3. (manual synchronization attempt):

You need to use OS semaphores for synchronization! A simple boolean check cannot work (infamous testAndSet problem).
Also include a delay() in your loop, e.g.

#include "SPILock.h"

void loopCustomUI() {
    {
        concurrency::LockGuard g(spiLock);
        lv_timer_periodic_handler();
    }
    delay(5);
}

Then you can leave the LovyanGFX cfg.use_lock = false .

Also make sure that you explicitly initialize all SPI CS pins that are connected to the same SPI bus prior any SPI initialization.

[xMIKx]

@mverch67 I made the suggested adjustments but ran into the same issue

• CS pins initialized before LGFX
• SPILock wrapping lv_timer_handler
• use_lock = false
• Still crashes at same spot after “Use AES128 key!

I attempted calling lv_timer_periodic_handler but it didn't seem to be available for my version of LVGL,could this be contributing to the issue?

Also, this could be completely unrelated but for the V3 board I could just plug it in and upload, however, for V4 I have to manually (using the Boot/reset buttons) put the board into bootloader mode every time I upload then reset the board before I can use serial monitor because bootloader is using a different port than the serial monitor.

[mverch67]

How exactly did you initialize the CS pins?

[xMIKx]

@mverch67 Thank you again for the help on this. This is an overview:

void setupCustomUI() {
// Initialize CS pins FIRST (before any SPI/LGFX initialization)
pinMode(33, OUTPUT); // Display CS
digitalWrite(33, HIGH);
pinMode(8, OUTPUT); // Radio CS (SX1262)
digitalWrite(8, HIGH);
delay(100);

// THEN create LGFX object
if (!tft) {
    tft = new LGFX();  // Constructor configures SPI
}

// ... rest of initialization

}

LGFX Config:
cfg.spi_host = SPI3_HOST;
cfg.use_lock = false; // Using SPILock instead
cfg.pin_cs = 33; // Set in panel config

Main Loop with SPILock:
void enhanced_loopCustomUI() {
{
concurrency::LockGuard g(spiLock);
lv_tick_inc(5);
lv_timer_handler();
// ... display operations
}
delay(5);
}

Timing: setupCustomUI() is called from main.cpp at startup after Meshtastic initializes (~8 seconds after boot).
Still crashes at the same point - immediately after "Use AES128 key!" during first NodeInfo broadcast at ~147 seconds.

Call Chain:
setupCustomUI() is called once from main.cpp setup() at startup (~8 seconds after boot)
loopOverlayUI() is called every loop iteration from main.cpp loop()
loopOverlayUI() then calls enhanced_loopCustomUI() which contains the SPILock-wrapped LVGL operations

Let me know if you need more info!

[mverch67]

void enhanced_loopCustomUI() {
    {
        concurrency::LockGuard g(spiLock);
        lv_tick_inc(5);
        lv_timer_handler();
        // ... display operations
    }
    delay(5);
}

Not related to the freeze, but if you run the lvgl in the same thread as the rest of the application (why?) then you cannot use tick_inc(5) but need to calculate the actual time that was spent in the main loop. Otherwise lvgl cannot properly draw fluid animations when there's a wrong time reference. Except you use lvgl 9.x lv_timer_periodic_handler() which calculates the time passed as just described.

[mverch67]

Is support for custom UI overlays on V4 something that’s expected to work in 2.7.x, or is it planned for a later stable?

Regarding this question, (M)UI is fully supported for this device, see here and here and here.

[xMIKx]

Thank you for the reference! I see the official MUI uses the expansion housing with different available pins.
My setup is the V4 base board with a custom-wired ST7796 display on different pins (SCK=3, MOSI=4, DC=26, CS=33, RST=48) since I don’t have the expansion housing.

Questions:
1. Is custom display wiring on V4 base board expected to work in 2.7.x alpha, or only the expansion housing?
2. Should I be using the official device-ui library architecture instead of a custom overlay?
3. Are there specific build flags from heltec-v4-tft I should add (like CONFIG_DISABLE_HAL_LOCKS=1, RADIOLIB_SPI_PARANOID=0) that might help?
The crash occurs during first radio transmission regardless of SPILock, CS pin init order, or use_lock settings.

[mverch67]

What happens if you use the same pins for ST7796 as in the settings for the expansion housing?
-D LGFX_PIN_SCK=17
-D LGFX_PIN_MOSI=33
-D LGFX_PIN_DC=16
-D LGFX_PIN_CS=15
-D LGFX_PIN_BL=21
-D LGFX_PIN_RST=18

[mverch67]

Pins 3 and 4 are already used for I2C bus