Add Heltec WiFi LoRa 32 V3 support and generic display reset#5633
Add Heltec WiFi LoRa 32 V3 support and generic display reset#5633dbwg2009 wants to merge 14 commits into
Conversation
- Automatically initialize GPIO36 and pull LOW on startup - Enables OLED power supply (Vext) without manual wiring - Checks for HELTEC_VEXT_PIN build flag before initialization - Supports WLED 17.1.1 release with integrated display support https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
- Automatically initialize GPIO36 and pull LOW on startup - Enables OLED power supply (Vext) without manual wiring - Checks for HELTEC_VEXT_PIN build flag before initialization - Supports WLED 17.1.1 release with integrated display support https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S Co-authored-by: Claude <noreply@anthropic.com>
- Added GPIO21 reset pulse sequence (HIGH → LOW → HIGH) - Added 100ms stabilization delay after GPIO36 Vext enable - Improves display initialization reliability on Heltec V3 - Released as v17.1.2 https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
- Add [env:heltec_wifi_lora_32_v3] to platformio.ini for ESP32-S3FN8 (8MB flash, NO PSRAM). BOARD_HAS_PSRAM is intentionally absent: the board has no PSRAM and setting that flag causes Error 8 (memory depleted) at boot. - Clean up four_line_display_ALT: remove hardcoded GPIO21 reset that was specific to this one board and had no place in a generic usermod. Retain the conditional HELTEC_VEXT_PIN path (disabled unless explicitly defined in a build environment) with a brief settle delay and an explanatory comment. Tested on Heltec WiFi LoRa 32 V3 hardware; firmware boots and LEDs work. OLED support can be added via the four_line_display_ALT usermod with HELTEC_VEXT_PIN=36 and I2C pins SDA=17 SCL=18 in platformio_override.ini. https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
Some boards require a reset pulse on the display RST pin before I2C initialises (the Heltec WiFi LoRa 32 V3 is the known case, GPIO21). Hard-coding GPIO21 in a generic usermod is wrong; this adds an optional FLD_PIN_RST build flag that any board can set in its platformio entry or platformio_override.ini. Nothing changes for existing builds that don't define FLD_PIN_RST. https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
… flags Add section to readme explaining the optional board-specific build flags that can be set in platformio.ini or platformio_override.ini: - FLD_PIN_RST: GPIO pin for display hardware reset (Heltec WiFi LoRa 32 V3) - HELTEC_VEXT_PIN: GPIO pin to enable switchable OLED power rail https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
WalkthroughThis pull request adds board-specific display initialization support for the Heltec WiFi LoRa 32 V3 by conditionalizing reset pin defaults, implementing pre-init GPIO handling in the Four Line Display usermod, creating a dedicated PlatformIO build environment, and documenting the new compile-time configuration flags. ChangesHeltec WiFi LoRa 32 V3 Display Support
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
usermods/usermod_v2_four_line_display_ALT/readme.md (1)
66-66: 💤 Low valueMinor: Inconsistent guidance on where to set build flags.
Line 66 mentions "your
platformio.iniorplatformio_override.ini" while line 72 only mentions "platformio.ini".For consistency and best practices (avoiding direct edits to tracked
platformio.ini), consider recommendingplatformio_override.iniin both places.📝 Suggested consistency fix
* `FLD_PIN_RST` - GPIO pin for display hardware reset (optional) - * Set in your `platformio.ini` or `platformio_override.ini`: `-D FLD_PIN_RST=<pin>` + * Set in your `platformio_override.ini` (or `platformio.ini`): `-D FLD_PIN_RST=<pin>` * Performs a reset pulse before I2C initialization * Required on boards like Heltec WiFi LoRa 32 V3 (GPIO21) * Example: `-D FLD_PIN_RST=21` * `HELTEC_VEXT_PIN` - GPIO pin to enable switchable OLED power rail (optional) - * Set in your `platformio.ini`: `-D HELTEC_VEXT_PIN=<pin>` + * Set in your `platformio_override.ini` (or `platformio.ini`): `-D HELTEC_VEXT_PIN=<pin>`Also applies to: 72-72
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@usermods/usermod_v2_four_line_display_ALT/readme.md` at line 66, The readme mentions setting build flags in "platformio.ini or platformio_override.ini" for FLD_PIN_RST at one place but later only references "platformio.ini"; update the latter occurrence so both lines consistently recommend setting flags in "platformio_override.ini" (or "platformio.ini / platformio_override.ini") and explicitly suggest using platformio_override.ini to avoid editing tracked files (refer to the FLD_PIN_RST build flag and the existing platformio.ini/platformio_override.ini guidance).platformio.ini (1)
666-683: ⚡ Quick winConsider adding an inline comment explaining the no-PSRAM configuration.
While the PR objectives clearly state that BOARD_HAS_PSRAM must NOT be set to avoid Error 8, adding a brief inline comment would help future maintainers understand why this board differs from other 8MB S3 environments (lines 577-601) that do enable PSRAM.
📝 Suggested inline comment
[env:heltec_wifi_lora_32_v3] ;; Heltec WiFi LoRa 32 V3 - ESP32-S3FN8, 8MB flash, NO PSRAM +;; NOTE: Do NOT set BOARD_HAS_PSRAM - this board has no PSRAM and setting it causes boot Error 8 ;; BOARD_HAS_PSRAM must NOT be set - this board has no PSRAM and setting it causes Error 8 (memory depleted)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@platformio.ini` around lines 666 - 683, Add a concise inline comment in the [env:heltec_wifi_lora_32_v3] block explaining that BOARD_HAS_PSRAM must NOT be set for this board because the Heltec WiFi LoRa 32 V3 (board = heltec_wifi_lora_32_V3) does not have PSRAM and enabling it causes "Error 8 (memory depleted)"; place the comment near the existing note or next to the build_flags/board_build settings (referencing BOARD_HAS_PSRAM) so future maintainers see why this S3 8MB variant differs from other S3 8MB configs that enable PSRAM.usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp (1)
226-237: ⚡ Quick winAllocate
FLD_PIN_RSTvia PinManager to prevent accidental pin reuse.
FLD_PIN_RSTis correctly documented as I2C-only (reset before I2C initialization on boards like Heltec V3), andioPin[2]is used exclusively for SPI display reset—the two are mutually exclusive by design. However, the current implementation doesn't allocateFLD_PIN_RSTvia PinManager, leaving room for misconfiguration: if a user sets bothFLD_PIN_RST=21andioPin[2]=21in different scenarios, the firmware won't detect the conflict.Allocating
FLD_PIN_RSTvia PinManager (following the pattern used for SPI pins on line 245) would provide defensive validation:🔧 Suggested refactor
`#ifdef` FLD_PIN_RST // Some boards require a hardware reset pulse on the display RST pin before // I2C init (e.g. Heltec WiFi LoRa 32 V3 uses GPIO21). Set FLD_PIN_RST in // your platformio_override.ini to enable this. + if (PinManager::allocatePin(FLD_PIN_RST, true, PinOwner::UM_FourLineDisplay)) { pinMode(FLD_PIN_RST, OUTPUT); digitalWrite(FLD_PIN_RST, HIGH); delay(1); digitalWrite(FLD_PIN_RST, LOW); delay(10); digitalWrite(FLD_PIN_RST, HIGH); delay(10); + } else { + DEBUG_PRINTLN(F("4LD: RST pin allocation failed")); + } `#endif`🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp` around lines 226 - 237, The FLD_PIN_RST reset pin is used without reserving it in the PinManager, allowing accidental reuse/conflict with ioPin[2]; update the initialization to allocate FLD_PIN_RST through the PinManager (same pattern used for SPI/reset pins around the SPI allocation code) before calling pinMode/digitalWrite/delay, i.e. call the PinManager reserve/allocate routine for FLD_PIN_RST (the same API used for ioPin[] allocations) and check for allocation failure/conflict, then proceed with the hardware reset sequence for FLD_PIN_RST; ensure you reference FLD_PIN_RST, the PinManager allocation method, and ioPin[2] in the change so conflicts are detected and logged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp`:
- Around line 218-225: Register the HELTEC_VEXT_PIN with the PinManager before
manipulating it: call PinManager::allocatePin(HELTEC_VEXT_PIN,
PinOwner::Usermod) (and handle a failed allocation if desired) immediately
before the existing pinMode/digitalWrite/delay block that references
HELTEC_VEXT_PIN, and optionally release it with
PinManager::releasePin(HELTEC_VEXT_PIN) during usermod cleanup. This keeps pin
ownership consistent with how the display I2C/SPI pins are allocated and
prevents conflicts with other code.
---
Nitpick comments:
In `@platformio.ini`:
- Around line 666-683: Add a concise inline comment in the
[env:heltec_wifi_lora_32_v3] block explaining that BOARD_HAS_PSRAM must NOT be
set for this board because the Heltec WiFi LoRa 32 V3 (board =
heltec_wifi_lora_32_V3) does not have PSRAM and enabling it causes "Error 8
(memory depleted)"; place the comment near the existing note or next to the
build_flags/board_build settings (referencing BOARD_HAS_PSRAM) so future
maintainers see why this S3 8MB variant differs from other S3 8MB configs that
enable PSRAM.
In `@usermods/usermod_v2_four_line_display_ALT/readme.md`:
- Line 66: The readme mentions setting build flags in "platformio.ini or
platformio_override.ini" for FLD_PIN_RST at one place but later only references
"platformio.ini"; update the latter occurrence so both lines consistently
recommend setting flags in "platformio_override.ini" (or "platformio.ini /
platformio_override.ini") and explicitly suggest using platformio_override.ini
to avoid editing tracked files (refer to the FLD_PIN_RST build flag and the
existing platformio.ini/platformio_override.ini guidance).
In
`@usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp`:
- Around line 226-237: The FLD_PIN_RST reset pin is used without reserving it in
the PinManager, allowing accidental reuse/conflict with ioPin[2]; update the
initialization to allocate FLD_PIN_RST through the PinManager (same pattern used
for SPI/reset pins around the SPI allocation code) before calling
pinMode/digitalWrite/delay, i.e. call the PinManager reserve/allocate routine
for FLD_PIN_RST (the same API used for ioPin[] allocations) and check for
allocation failure/conflict, then proceed with the hardware reset sequence for
FLD_PIN_RST; ensure you reference FLD_PIN_RST, the PinManager allocation method,
and ioPin[2] in the change so conflicts are detected and logged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 023ba96c-f928-4b30-bbf1-0a40624636ae
📒 Files selected for processing (3)
platformio.iniusermods/usermod_v2_four_line_display_ALT/readme.mdusermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp
1. Pin Manager Registration: Wrap HELTEC_VEXT_PIN and FLD_PIN_RST GPIO operations with PinManager::allocatePin() to prevent conflicts with other code that might use GPIO36 or GPIO21. Pins are now properly reserved and will fail gracefully if allocation fails (e.g., already in use). 2. Documentation Consistency: Updated readme to consistently recommend platformio_override.ini for all build flags (avoids editing tracked platformio.ini file). Single clear instruction point instead of mixed recommendations. 3. Platformio.ini Clarity: Added detailed comment explaining why BOARD_HAS_PSRAM is intentionally absent on the Heltec V3. References the similar pattern used by esp32s3dev_4MB_qspi_hub75. Prevents future confusion about why this board differs from other 8MB ESP32-S3 configurations. All changes maintain backward compatibility (flags remain optional and conditional). Build tested and verified. https://claude.ai/code/session_0177tCiDXsjQyQ86Nu7VYP5S
|
Addressed CodeRabbit feedback: 1. Pin Manager RegistrationWrapped 2. Documentation ConsistencyUpdated readme to consistently recommend 3. Platformio.ini ClarityAdded detailed comment explaining why All changes maintain backward compatibility (flags remain optional and conditional). Build tested and verified. Commit: |
Board-specific examples belong in the sample override file rather than the main platformio.ini. Users can copy this section to their local platformio_override.ini and customize as needed.
|
Updated: Moved the Heltec WiFi LoRa 32 V3 board configuration from The configuration now includes:
All changes have been committed to the fork and are ready for review. |
Use the existing FLD_PIN_RESET flag for I2C display reset pulse to maintain consistency with the SPI display configuration. This flag is already defined in the display usermod headers and avoids introducing a new naming variant.
|
@dbwg2009 please ensure that we don't add duplicate PIN macros that are already supported by the standard drivers. Especially
|
softhack007
added
board request
@dbwg2009 in case you took help from an AI for the description or for coding, please be transparent and state it. We usually need to heavily scrutinise AI-generated software and docs, as AI still makes a lot more mistakes than any human developer. |
softhack007
added
the
AI
The U8x8 driver already performs the reset pulse during init when given a reset pin. Pass FLD_PIN_RESET to the I2C constructors and remove the duplicate manual pinMode/digitalWrite reset block. The I2C default for FLD_PIN_RESET is now U8X8_PIN_NONE so existing I2C boards are unaffected; only boards that explicitly set a reset pin get a driver-managed reset. SPI defaults are unchanged.
Hey @softhack007 yes, I have. This is due to the fact that i am not that experienced in programming and had modified WLED slightly to work with my board and wanted to share. I apologise if it's causing problems. I didn't realise that the U8g2/U8x8 driver already performs the reset pulse itself. Hopefully I've updated it correctly. Thank you for your patience with me |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp`:
- Around line 218-227: The PinManager::allocatePin(HELTEC_VEXT_PIN, true,
PinOwner::UM_FourLineDisplay) call can fail silently; add an else branch that
logs the allocation failure (include HELTEC_VEXT_PIN and that
PinOwner::UM_FourLineDisplay was requested) and set the display init control
variable (type) to NONE to skip display setup deterministically; modify the
block around allocatePin/HELTEC_VEXT_PIN to handle the failure path by logging
and assigning type = NONE before continuing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 33fd9250-59b9-49e3-81f9-0c1352c1cd2e
📒 Files selected for processing (2)
usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display.husermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp
| #ifdef HELTEC_VEXT_PIN | ||
| // Pull the Vext power rail enable pin LOW before display init. | ||
| // Required on boards like the Heltec WiFi LoRa 32 V3 where the OLED is | ||
| // powered via a switchable rail (GPIO36) rather than always-on VCC. | ||
| if (PinManager::allocatePin(HELTEC_VEXT_PIN, true, PinOwner::UM_FourLineDisplay)) { | ||
| pinMode(HELTEC_VEXT_PIN, OUTPUT); | ||
| digitalWrite(HELTEC_VEXT_PIN, LOW); | ||
| delay(5); | ||
| } | ||
| #endif |
There was a problem hiding this comment.
Handle HELTEC_VEXT_PIN allocation failure explicitly.
If PinManager::allocatePin() fails here, setup silently continues and can attempt display init with Vext still off. Add an else branch to log and disable display init (type = NONE) for a deterministic failure mode.
Suggested patch
`#ifdef` HELTEC_VEXT_PIN
// Pull the Vext power rail enable pin LOW before display init.
// Required on boards like the Heltec WiFi LoRa 32 V3 where the OLED is
// powered via a switchable rail (GPIO36) rather than always-on VCC.
if (PinManager::allocatePin(HELTEC_VEXT_PIN, true, PinOwner::UM_FourLineDisplay)) {
pinMode(HELTEC_VEXT_PIN, OUTPUT);
digitalWrite(HELTEC_VEXT_PIN, LOW);
delay(5);
+ } else {
+ DEBUG_PRINTLN(F("4LD: HELTEC_VEXT_PIN allocation failed"));
+ type = NONE;
}
`#endif`🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@usermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp`
around lines 218 - 227, The PinManager::allocatePin(HELTEC_VEXT_PIN, true,
PinOwner::UM_FourLineDisplay) call can fail silently; add an else branch that
logs the allocation failure (include HELTEC_VEXT_PIN and that
PinOwner::UM_FourLineDisplay was requested) and set the display init control
variable (type) to NONE to skip display setup deterministically; modify the
block around allocatePin/HELTEC_VEXT_PIN to handle the failure path by logging
and assigning type = NONE before continuing.
Hi @dbwg2009 generally no problem, just - for the next PR - add a statement in the description when most your code was written by an AI (coding agent). I don't want to deduce that myself from description styles and commit details 😅 |
Sorry about that @softhack007, I will in future 🥲 |
|
@dbwg2009 !!! tip about usage of AI - it's really dangerous to allow the bot to make source code commits on its own. Code gets lost without noticing, comments vanish, completely untreated files might get garbled. I'm talking from experience. Not sure how to change your AI agent settings. Best practice is to let it do the coding for you locally, then YOU would test the changes on your board (still working locally), and then make the commit yourself, for example with github desktop. This won't make any difference for our review of your PR, so just take it as my tip on good practice. |
Ahhh, I see. That makes sense, I'll have a look at the settings and I'll do that from now on. Thank you @softhack007 ! |
|
@dbwg2009 the problem with I was also wondering if adding the build flags |
@softhack007 I'll test it now. Good point with the build flags, I'll also test that out and let you know how it goes! |
| board_build.f_flash = 80000000L | ||
| board_build.flash_mode = qio | ||
| lib_deps = ${esp32s3.lib_deps} | ||
| olikraus/U8g2 @ ^2.28.8 ;; for four_line_display_ALT usermod |
There was a problem hiding this comment.
This line should not be necessary any more, the library.json in the usermod folder should take care of pulling in the U8g2 driver.
|
@softhack007 Just compiled and tested. Compiles fine with the build flags. |
|
@dbwg2009 as someone who has invested a lot of time into this usermod to make it runtime configurable I would encourage you to avoid compile-time options and implement user selectable runtime choices in the same way as every other option in this usermod. Otherwise this looks like low-effort one-user solution. |
After some research, the story seems more complicated. I've initially mixed up I2C and SPI based displays in my recommendation, sorry about that. To clean up the mess a bit:
I agree with the comment made by @blazoncek that both additional PINs must be configurable via Usermod settings, in addition to (optionally) providing build_flags for hardware integrators. Functions that need adjustment for supporting settings by UI: Display initializion / re-initializion pin registration (not sure I found everything) |
softhack007
added
the
needs_rework
4 participants
Summary
Add official support for Heltec WiFi LoRa 32 V3 board and improve display initialization with generic build flags for board-specific requirements.
Problem
The Heltec WiFi LoRa 32 V3 (ESP32-S3FN8, 8MB flash, NO PSRAM) fails to boot with standard ESP32-S3 WLED builds because:
-DBOARD_HAS_PSRAMby defaultAdditionally, the onboard 0.96" SSD1306 OLED display requires:
Solution
1. New Board Environment:
heltec_wifi_lora_32_v3Added to
platformio.inifollowing the established pattern for boards without PSRAM.Key features:
-DBOARD_HAS_PSRAM(resolves Error 8)2. Generic Display Reset Support:
FLD_PIN_RSTAdded optional
FLD_PIN_RSTbuild flag tofour_line_display_ALTusermod to support boards that require a hardware reset pulse on the display RST pin before I2C initialization.Benefits:
3. Switchable Power Rail Support:
HELTEC_VEXT_PINAdded optional
HELTEC_VEXT_PINflag tofour_line_display_ALTto allow boards with switchable display power rails to enable them reliably.Testing
✅ Tested on actual Heltec WiFi LoRa 32 V3 hardware:
Documentation
usermods/usermod_v2_four_line_display_ALT/readme.mdwith build flag documentationCode Quality
platformio.iniDisplay usermod changes: The
FLD_PIN_RSTandHELTEC_VEXT_PINflags are purely optional (no effect unless explicitly defined) and generic (not Heltec-specific).Hardware tested: This change has been validated on actual Heltec V3 boards with the onboard OLED display working correctly.
Related Changes
Fixes WLED operation on Heltec WiFi LoRa 32 V3 boards (resolves Error 8, enables optional OLED support).
Files Changed
platformio.ini: New[env:heltec_wifi_lora_32_v3]board environmentusermods/usermod_v2_four_line_display_ALT/usermod_v2_four_line_display_ALT.cpp: AddFLD_PIN_RSTandHELTEC_VEXT_PINsupportusermods/usermod_v2_four_line_display_ALT/readme.md: Document the new build flagsSummary by CodeRabbit
Documentation
New Features