Skip to content

Add MeshPocket V2 board and power-bank UI support - #3803

Open
Quency-D wants to merge 6 commits into
meshcore-dev:devfrom
Quency-D:MeshPocket_V2
Open

Quency-D wants to merge 6 commits into
meshcore-dev:devfrom
Quency-D:MeshPocket_V2

Conversation

@Quency-D

@Quency-D Quency-D commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary
This PR adds complete MeshPocket V2 board support with four firmware targets:

  • BLE Companion: heltec_meshpocket_v2_companion_radio_ble
  • USB Companion: heltec_meshpocket_v2_companion_radio_usb
  • Repeater: heltec_meshpocket_v2_repeater
  • Room Server: heltec_meshpocket_v2_room_server
    All targets share the same board definition, radio/display/GNSS configuration, ExtraFS layout, and the official HeltecMeshPocketV2Power 0.2.0 dependency.
    Board support
    The new variants/heltec_meshpocket_v2 implementation initializes and manages:
  • SX1262 LoRa radio on the primary SPI bus
  • NV3001B 220×128 color display on SPI1
  • UC6580 GNSS using Serial1
  • HLT331 power controller using Serial2
  • CW221X fuel gauge using I²C
  • Main and secondary buttons
  • C2 USB data switch through the CSA pin
  • Main-button and IO1 wake sources during System OFF
    CSA defaults to LOW for every firmware role. USB Companion, Repeater, and Room Server can enable USB data mode from the power page, while BLE Companion does not expose that action.
    Power monitoring
    PowerBank owns all CW221X and HLT331 communication and keeps this hardware logic outside the generic UI.

It handles:

  • The HLT331 IO1 receive window and serial status frames
  • Normal CW221X sampling and accelerated reads after state changes
  • Independent validity tracking for fuel-gauge and power-controller data
  • C1, C2, Qi2, charge/discharge, fault, and IO1 event detection
  • One-shot page events consumed by the UI
  • Aggregate charger status for the normal Companion battery indicator
    Communication interruptions preserve the last trusted state while displayed values independently expire when their source is no longer valid.
    Power-bank page
    PowerBankPage renders a dedicated 220×128 page showing:
  • Battery percentage, battery bar, and temperature
  • Charge/discharge power and activity indicator
  • C1 and C2 connection state, direction, and protocol
  • Shared-protocol marker
  • Qi2 state and FOD status
  • C2 USB mode: charging remains available; discharging is disabled
    The page uses field-level caching. Its static layout is drawn only when a full restore is required; stable readings generate no repeated pixel updates. Changed values only redraw their corresponding regions.

Normal MeshCore pages continue using the existing 128×64 logical coordinate system. Native 220×128 coordinates are enabled only while rendering the power page and are restored immediately afterward.
Reusable board UI interface
This PR adds an optional BoardUiExtension interface to MainBoard.

Boards without an extension continue using their existing page count and UI behavior. A board extension can:

  • Consume board-owned input and focus events
  • Execute a page-specific action
  • Render a full-screen board page
  • Select its own refresh interval
    Companion adds the optional board page as the final page. Repeater and Room Server use the shared BoardUiScreen helper to switch between their standard status screen and the board page.

Hardware-specific types such as the HLT331 snapshot, C1/C2 state, USB switching, and secondary-button handling remain in the MeshPocket V2 variant.
UI behavior

  • Companion can reach the power page through normal page navigation.
  • Power state events can wake the display and request the power page.
  • Repeater and Room Server can switch between the status page and power page with the main button.
  • The secondary button provides direct access to the power page.
  • On supported roles, a secondary-button long press while on the power page toggles C2 USB mode.
  • Existing startup screens, popup handling, auto-off timing, and Repeater shutdown flow remain in place.
  • The regular battery icon uses real charger activity on supported boards and preserves the existing external-power behavior on other boards.
    Compatibility
    The existing HELTEC_MESH_POCKET_V2 build definition is retained for compatibility, but shared UI and display code no longer depends on board-name conditionals.

Unsupported displays keep their existing behavior because DisplayDriver::setNativePixels() has a default no-op implementation.
Validation

  • Board JSON parsing passes.
  • All four V2 PlatformIO environments expand correctly.
  • BLE does not receive the USB-switchable build flag.
  • USB Companion, Repeater, and Room Server receive the USB-switchable flag.

Follow-up validation

  • Merged upstream dev and retained its NV3001B SPI constructor interface alongside native-pixel mode and nRF52 burst transfers.
  • All four renamed environments expand with official 0.2.0 and expected USB-switchable flags. Board JSON parsing and follow-up diff whitespace checks pass.
  • No local firmware compilation or flashing for this update. The PR build matrix does not include the four V2 targets.
  • Display timing and LoRa packet-loss measurements remain pending hardware testing.

@fdlamotte

Copy link
Copy Markdown
Collaborator

Just got one of those so I'll try it

There are a lot of changes to the UI, so I'll probably have to do a proper review and some checks before merging ;)

@fdlamotte

Copy link
Copy Markdown
Collaborator

Here are my thoughts about this port

Basic function works well, but UI is very slow. I think this was the same when I worked on T114, in the end we finished by switching to monochrome display which (even if not as colorfull) was way more faster (I think the t096 has the same issue, but I used mine as repeater (works great) so don't really care). A side question, does the ui refresh has an incidence on lora communication (can't we miss some packets ?) This was one of the issues that had been brought by @liamcottle and had triggered the change to mono)

I've seen you already integrated with the new GPS framework. How did you find it ? If you have any comments on it you are welcome ;)

I'll go deeper in this contribution, but I now have some other (less interesting) work to do ;)

Comment thread variants/meshpocket_v2/platformio.ini Resolved
@Quency-D

Copy link
Copy Markdown
Contributor Author

Here are my thoughts about this port

Basic function works well, but UI is very slow. I think this was the same when I worked on T114, in the end we finished by switching to monochrome display which (even if not as colorfull) was way more faster (I think the t096 has the same issue, but I used mine as repeater (works great) so don't really care). A side question, does the ui refresh has an incidence on lora communication (can't we miss some packets ?) This was one of the issues that had been brought by @liamcottle and had triggered the change to mono)

I've seen you already integrated with the new GPS framework. How did you find it ? If you have any comments on it you are welcome ;)

I'll go deeper in this contribution, but I now have some other (less interesting) work to do ;)

Thanks for testing and for the feedback!

I've just updated the branch to increase the display SPI clock from 4 MHz to 8 MHz, which should help with transfer time, although I haven't measured the actual improvement yet.

Regarding the UI performance, do you have any specific measurements or a reference for what would be considered an acceptable refresh time? Is the slowness mainly noticeable when switching pages, or during normal screen updates?

I found the earlier T114 monochrome PR #237, but it doesn't seem to include specific timing measurements.

There is also an interesting discussion in #3701 and #3724 about display refresh blocking the main loop.

For MeshPocket V2, the display and LoRa radio use separate SPI buses, but since display operations are still synchronous, they could potentially delay radio processing.

I'll run some tests to measure the actual display refresh time and see how it performs.

The current driver still has room for optimization, particularly by batching pixel writes and avoiding unnecessary full-screen redraws. I'd prefer to investigate these before considering switching to monochrome.

As for the new GPS framework, it's really nice! I like it a lot. :)

Thanks again for taking the time to review this! :)

@Quency-D

Copy link
Copy Markdown
Contributor Author

Measured display refresh times on MeshPocket V2:

Screen / update Median at 4 MHz Median at 8 MHz
Home 185.5 ms 110.4 ms
Radio settings 239.3 ms 156.3 ms
GPS 230.5 ms 150.4 ms
Power page — full redraw 390.6 ms 243.2 ms
Power page — partial update 22.5 ms 17.1 ms

Collected 1,040 samples using a 4 → 8 → 8 → 4 MHz sequence. All 400 unchanged power-page checks produced zero display SPI transfers.

LoRa packet loss has not yet been tested.

@fdlamotte

Copy link
Copy Markdown
Collaborator

refresh is much better now (and I think it should be ok regarding the fact that it blocks the loop)
but it's still very visible to the eye

maybe the same strategy as with gxepddriver could be used ? (computing a crc to see if the screen content changed ?)

to me this is mostly an issue when there is no change on the screen (on screen change, for instance, the redraw does not bother much)

@Quency-D

Copy link
Copy Markdown
Contributor Author

refresh is much better now (and I think it should be ok regarding the fact that it blocks the loop) but it's still very visible to the eye

maybe the same strategy as with gxepddriver could be used ? (computing a crc to see if the screen content changed ?)

to me this is mostly an issue when there is no change on the screen (on screen change, for instance, the redraw does not bother much)

That makes sense, especially when the screen content has not changed.

GxEPD draws into a RAM buffer and uses a CRC of the drawing commands and their parameters to decide whether to refresh the panel. The current NV3001B driver clears the screen in startFrame() and writes pixels immediately, so adding a CRC check in endFrame() alone would be too late—the redraw has already happened.

The power page already compares each displayed field with its previous value and redraws only the fields that changed. It does not use a frame CRC or a framebuffer.

For ordinary pages, comparing the values and states actually shown on screen before drawing may be a better fit than a frame CRC. We could skip the redraw when those remain unchanged, while keeping the power page's existing partial updates.

@fdlamotte

fdlamotte commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

You're right, the crc works on eink because everything is done in a double buffer and the reason we don't want to redraw the screen is different ...

sadly I don't think that we want a refactor of UITask right now to add some hierarchy in the display widget and screen damage for parts to update (which could be an interesting paradigm change but maybe overkill for the small screens that we have ...)

There is clearly room for improvement here (maybe it's time to start working on a ui-new-new interface, which would better accomodate bigger screens and manage widget-damage ...)

But let's first work on integrating this PR. I'll review the changes you propose for the src and example tree mostly (as all that is in the variant won't impact others ;))

edit: most problematic pages are gps and node discovery (while waiting for replies it updates every sec) ... I'll investigate how we can get a better user experience on that pages ;)

@fdlamotte

Copy link
Copy Markdown
Collaborator

Regarding this PR

The most intrusive part is the introduction of BoardUI

It seems it fills an important need for your device, as user of a powerbank needs a way to monitor closely its device and that is very nice.

But I feel we should work together on a more generic way of adding pages to the UI, where the designer for a board or a custom firmware can benefit from the current infrastructure and add his own assets. The issue I see with the approach you've taken is that if someone wants to extend it it has to add more complexity to the base code, with the risk of ending with a spagethi plate

It would be really nice if we had some ways of extending the UI without touching UITask, and let the user choose at buid time which screen (and potentially custom ones) he wants in his UI

@ripplebiz, @recrof, @liamcottle ?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants