The Shelf for Heltec V4 (and V3, and plain ESP32 boards)
The Shelf, running on a Heltec WiFi LoRa 32 V4, a V3, or a plain ESP32 dev board (NodeMCU-32S / DevKitC). The board serves The Shelf's own web app (the same page you get on a PC or a Pi), with your files on a microSD card. Anyone on your home Wi-Fi opens it in a browser, and it shows up in Messages on every other Shelf in the house.
Installing replaces Meshtastic on that board. You can put Meshtastic back any time from flasher.meshtastic.org.
What works on the board
| ✅ Included | 💻 Needs The Shelf on a computer |
|---|
Pictures (grid, slideshow, photo editor), Music (shuffle, play counts, artist and cover art read from your MP3s' own tags), MIDI (its own shelf: .mid, .midi, .kar files played by a built-in General MIDI synth, with the same player, shuffle and play counts), Videos, Games (.html and zipped HTML games play in the page), Programs, Books (PDF reader and cover thumbnails) | The AI assistant and Create with AI |
| Home: bulletin board with notes, pasted pictures and videos, quick links, weather | Remote desktop (VNC) |
| Notes, Docs, Sheets, Slides, Draw | Online album-art lookup, tag editing, Standardize names, Remove duplicates, Export |
| Tidy Suite | Big Transfer, backup/restore zips, spreadsheet import |
| Messages: finds and chats with your other Shelves (PCs, Pis, other boards), pictures included | User accounts (the board has one admin password instead) |
| 900MHz Coms: LoRa text mesh between boards, every board a relay, 12-hour catch-up, list of boards and remote admin | |
| Read-only mode with an admin password to unlock changes | |
The buttons for those computer-only features are hidden on the board, and the AI and Big Transfer tabs are left out.
Hardware
| Part | Notes |
|---|
| Heltec WiFi LoRa 32 V4 or V3 | The standard V4 (ESP32-S3R2, 2 MB PSRAM), the V4-R8 (8 MB PSRAM), or the V3 (8 MB flash, no PSRAM). Each has its own install button |
| 3.3 V SPI microSD module | The small blue 6-pin module whose pins read 3v3 · CS · MOSI · CLK · MISO · GND (square pad = 3v3). It has no voltage regulator, so it goes to 3V3, never 5V |
| microSD card | FAT32. A 32 GB card works out of the box |
Wiring the microSD card (V4 and V3)
From v1.6.0 the card uses four neighbouring pins on the J3 row, the same layout as Heltec V4 MP3 + BT:
| microSD module | Heltec V4 / V3 |
|---|
| 3v3 | 3V3 |
| GND | GND |
| CS | GPIO 42 |
| MOSI | GPIO 41 |
| CLK (SCK) | GPIO 40 |
| MISO | GPIO 39 |
The V3's J3 row is laid out the same way (V3 diagram). On a V4, GPIO 39–42 are shared with the GNSS connector, so leave the GNSS kit unplugged.
Easier: plug it straight in. CS · MOSI · CLK · MISO sit on 42 · 41 · 40 · 39 in the same order as the module's pins, so the module plugs straight into the header. Bend up (or clip) its 3v3 and GND pins so they skip GPIO 45 and 38, then add two short jumpers to the GND and 3V3 pins at the start of the row.
Heltec V4-R8: its GPIO 40 switches the screen's power, so the R8 build keeps the older layout: CS 4, MISO 6, CLK 47, MOSI 48 (R8 diagram).
Upgrading from v1.5 or earlier on a V4 or V3? The card moved from CS 4 · MISO 6 · CLK 47 · MOSI 48 to the pins above. Move the four signal wires, or the board won't find the card and will use its own flash instead.
With no card, The Shelf keeps files in the board's own flash: about 9 MB on a V4, about 2.5 MB on a V3. The screen shows SD or FLASH in the corner.
On a Heltec V3
The V3 gets the same Shelf, the same tabs and the same 900MHz Coms. Its mesh settings match the V4's, so V3 and V4 boards are on one mesh, relaying and catching each other up. The differences:
- Transmit power. The V3 has no front-end amplifier, so its levels are Low ~11, Normal ~17 and High ~22 dBm (the V4 reaches ~27). The tab shows the right numbers for each board.
- Memory. The V3 has no PSRAM, so it keeps the newest 150 Coms messages on screen (the V4 keeps 300). The full log stays on the card. Give it a little longer with lots of people browsing at once.
- Storage without a card is about 2.5 MB, so fit a microSD card.
- Screen says V3 in the top bar, and its address is
shelf-v3-xxxx.local.
On the card
Your shelves are normal folders at the top of the card: Pictures, Music, MIDI, Videos, Games, Programs, Books. Pop the card into a computer and copy music or photos straight in. Put files directly in those folders, because subfolders inside a shelf aren't shown (the same as The Shelf). Notes, docs, drawings, play counts, thumbnails and messages live in the hidden .shelf folder.
First-time setup
- Install with the web installer (Chrome or Edge).
- Power the board. The screen shows Join The-Shelf-XXXX. Join it from your phone with the password
theshelf.
- The setup page opens (or go to
http://192.168.4.1). Tap Find networks, pick your Wi-Fi and enter its password.
- Back on your home Wi-Fi, open the address on the screen, or
http://shelf-v4-xxxx.local.
900MHz Coms (LoRa mesh between boards)
A 900MHz Coms tab in The Shelf's Tools lets Shelf boards (V4 and V3) text each other over their LoRa radios, with no Wi-Fi or internet between them.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
