PocketMage PDA: an ESP32-S3 handheld OS that still lists the e-reader as planned

E-Ink holds the page, the OLED strip holds the cursor

PocketMage is a handheld PDA built around an ESP32-S3 WROOM1 running a custom operating system written in C++ and built with PlatformIO. The interesting decision is not the processor but the display pairing. A 3.1 inch 320x240px 1-bit SPI E-Ink panel (GDEQ031T10) carries the interface, and a 256x32px 1-bit SPI OLED (SSD1326, ER-OLED018-1W) sits next to it with its own integrated driver.

E-Ink holds its pixels once drawn, which is what makes an always-visible page practical on a battery-powered device, and it is also why every redraw is slow. Moving fast-changing content onto the OLED is the mitigation the hardware offers.

That strip is 256 pixels wide and 32 tall, which makes it a status band rather than a second screen. Anything you would want to scroll has to go on the E-Ink side and wait for the panel, while cursors, status text and anything that must not blink belong on the OLED. For anyone writing firmware for this board, that is the first constraint to internalise: layout code decides which of two very different refresh behaviours a widget inherits.

The audience is narrow. You need the parts, a soldering iron and time, because nothing published here orders hardware for you.

Sixteen megabytes of flash, and a microSD slot rated to 2 TB

The module carries 16 MB of flash and 8 MB of RAM, with WiFi and Bluetooth on board. That is the whole budget for the operating system, the apps and any file the device holds in memory, which explains the MicroSD slot: the card side is documented as supporting up to 2 TB, so the intended split is code in flash and storage on the card.

Power comes from a 1200 mAh pouch-style LiPo on a JST PH (2 mm) connector, with a power button and a USB Type-C port used for charging and by the USB file transfer app.

No charge current, runtime figure or battery gauge reading appears anywhere in the documentation. How long a charge actually lasts on this hardware cannot be read off the repository, and the planned battery expansion add-on module is the only acknowledgement that the cell size is a constraint.

The keyboard matrix and the real-time clock share the I2C bus

Input runs through a TCA8418 I2C keyboard matrix IC, and timekeeping through a PCF8563T I2C RTC module. Both devices sit on I2C, alongside the two I2C lines the expansion port exposes, so any add-on board has to coexist with the key scanner and the clock on the same bus.

The expansion port is the most useful entry in the hardware list because it is enumerated rather than implied: `+3.3V`, `GND`, `I2C SDA`, `I2C SCL`, `SPI MOSI`, `SPI SCK`, `SPI MISO`, `GPIO A`, `GPIO B`, `GPIO C`, `GPIO D / UART TX`, `GPIO E / UART RX`. Twelve lines, and the last two are switchable with a solder jumper, the defaults being TX on GPIO D and RX on GPIO E. Set the jumper before wiring a serial console to those pins, because the alternative mapping puts transmit and receive on different pins than a board that assumes the usual pairing.

A piezo buzzer covers simple tones, and the power button is the only other control on the bill of materials.

The project summary names three apps, the software list names twelve

This README contradicts itself about scope, and the two halves of the file sit within a few lines of each other. The project summary says the device currently amounts to a simple GUI for navigating between apps, a text (.txt) file editor, and a basic file manager. Three pieces of software.

Further down, the software list runs to twelve entries: the text editor app (TXT), FileWiz file-management app, Calendar app, USB file transfer app, COMM mesh chat app, Settings app, Tasks app, Journal app, Dictionary app (Lexicon), App loader for OTA apps, Terminal app (Wrench scripting), SSH. Each of those is a named artefact rather than a wish, and the Code/ directory in the repository holds the source that backs them.

The gap reads as a summary that stopped tracking the software list, not as a hidden roadmap. What the summary does get right is the finish line: the project is called a work in progress, and the stated plan is to bring the software and hardware to maturity before anything else gets attention.

The home menu doubles as a launcher and a command line

Not every action needs an app icon. Commands supported through the home menu include a dice roll where N is the number of sides, setting the time and date, and typing a filename to open that file directly in TXT or FileWiz instead of navigating to it. The dice syntax is a single token:

roll dN

Nothing in the documentation says which values are accepted after the letter d, or what the screen does with a malformed entry, so the Command Manual page is where to look before scripting anything around that parser.

The direct-open behaviour is the practical half. On a device whose storage is a MicroSD card holding long filenames, typing the name beats thumb-scrolling through a file manager on a 320x240 panel. Tasks and Journal are the two entries in the software list that write text you create back to that card.

An e-book reader sits on the planned list, not the shipped one

E-Ink hardware invites the assumption that this is an e-reader. The dictionary app exists, and Lexicon is the name it ships under, but the e-book reader appears only under planned features. The rest of that list reads the same way: timers and alarms, WiFi notes and calendar sync through Google Docs and Calendar, a LoRa or Meshtastic add-on module, a battery expansion add-on module, custom abbreviations, and Bluetooth keyboard support. Seven items, none of them dated or assigned to a version.

COMM mesh chat is the one place where the shipped list and the planned list meet, because Meshtastic is a mesh protocol and the planned hardware for it is an add-on module. Whether the existing COMM app talks to that module or only over WiFi is not stated anywhere, so treat the radio path as unverified until you read the source.

Lexicon and a book reader are also different problems. A dictionary resolves a word and needs a fast lookup surface, which is exactly what the OLED strip provides. A book reader needs paging on a slow panel and a storage format the software list never names.

No install command exists, so the build starts on the docs site

There is no install command anywhere in this project, and no package manager entry either. Firmware is a PlatformIO build, and the instructions route you to a documentation site with separate pages for build environments, the command manual, an FAQ, scripting and an App API Reference. Among the repository's top-level entries are .github/, .gitignore, CONTRIBUTING.md, Code/, Docs/, README.md and Resources/.

The concrete first step for anyone extending the firmware is one file. App authors are pointed at Code/PocketMageOS/src/APP_TEMPLATE.cpp and paired with the App API Reference, so the template and that API document are what a new app has to fit inside. A walkthrough video exists for a first pass, and the FAQ page is the only other written guidance.

What the repository does not contain is board design data. The KiCad schematics and 3D files the summary promises to open source once the device matures are not among those top-level entries, so the PCB cannot be rebuilt from what is published today.

OTA apps and SSH are the alternative to reflashing over USB

Reflashing firmware over USB Type-C is one route in. The App loader for OTA apps is another, and SSH is a third: a machine on the same network can open a shell instead of tapping through a 256x32 OLED strip, and the Terminal app exposes Wrench scripting between the home-menu commands and the OS. No competing handheld project is named anywhere in the documentation, so the only approach comparison available is between these two routes and the bench cable.

Two facts about where the code stands. The last push was on 2026-10-06, while the newest tagged build is BETA_V1.8.3 from 2026-05-25, so the firmware has moved since that tag. Every file is distributed under Apache-2.0, and the kits the author intends to sell are not in this repository yet.

Editorial conclusion

PocketMage is worth reading if you want a complete handheld operating system built on an ESP32-S3, and pointless if you need an e-reader this month, since the reader is still a planned feature. Verify three things before investing time: open Code/PocketMageOS/src/APP_TEMPLATE.cpp and the App API Reference to see the surface your own app must fit, confirm you can source the GDEQ031T10 panel and the TCA8418 keyboard IC on your own, and budget for firmware flashes, because no kit is published and no board files are either.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. TalismanDesign/PocketMage_PDA on GitHub