papermono-shopping-list README

The project's README from github.com/seamusc/papermono-shopping-list. As one markdown file: README.md.

PaperMono Shopping List

Firmware for the M5Stack PaperMono e-paper device. It turns the device into a household shopping list that lives on the fridge and stays in sync with a phone web app.

The PaperMono on a fridge, showing a shopping list grouped by aisle    The PaperMono settings screen: frontlight, sync now, Wi-Fi, last sync and battery

The PaperMono is an ESP32-S3 with a 3.97" 480×800 e-paper touchscreen. This project is a complete, working app for it that's small enough to read: about 2,400 lines of C++. You can use it as a shopping list, or as a starting point for your own PaperMono firmware.

What it shows on the PaperMono

How it works

The device shows the list grouped by aisle, in the order you walk the shop. Tap an item to tick it off, or add one with the on-screen keyboard. Everyone else adds things from their phone.

The phone web app showing the shopping list grouped by aisle    The phone web app's aisle editor, for setting the order you walk the shop

A small server in between stores the list. It remembers which aisle every item belongs to and can optionally sort brand-new items into the right aisle with Claude.

flowchart LR
    device["PaperMono<br/>(firmware/)"] -- "Wi-Fi, hourly or on tap<br/>and after each edit" --> server
    phone["Phone browser"] -- HTTP --> server
    subgraph server["Server (server/)"]
        api["FastAPI + SQLite"]
        web["Web UI"]
    end
    api -. "new item names only" .-> claude["Claude Code CLI<br/>(optional)"]

Repository layout

firmware/   PlatformIO project for the PaperMono (C++ / Arduino)
server/     FastAPI server, SQLite store, phone web UI, tests
docs/       Hardware notes, architecture, API, build and deploy guides, design notes

Quick start

1. Run the server

cd server
python3 -m venv .venv && .venv/bin/pip install -e .
SHOPPING_LIST_CLASSIFIER=none .venv/bin/uvicorn shopping_list.main:app --host 0.0.0.0 --port 8000

Open http://<server-ip>:8000/ on your phone, tap Aisles, and add your shop's aisles in the order you walk them. See docs/server.md for systemd and Docker deployment and for turning on auto-sorting.

2. Build and flash the firmware

You need PlatformIO and a PaperMono connected over USB-C.

cd firmware
cp src/secrets.example.h src/secrets.h   # set Wi-Fi SSID/password and the server URL
pio run -t upload

Back up your device's flash before the first flash. It holds that unit's factory calibration data. docs/firmware.md covers the backup, download mode and flashing from a browser.

Documentation

Doc What's in it
Hardware notes Pin map, I²C devices, bring-up sequence, display, touch and power details; reusing the drivers
Firmware Building, configuring, flashing and recovering the device; using it; troubleshooting
Architecture Components, data model, the sync protocol, offline behaviour, display refresh policy
Server Running and deploying the server, configuration, auto-sorting, security
HTTP API Every endpoint, request and response
Design notes Where the firmware came from, decisions and trade-offs, known limitations

Status

A personal project, running on one device at home. It works, but it isn't a product. There's no on-device Wi-Fi setup (credentials are compiled in), no authentication on the server (keep it on your LAN or behind an authenticating reverse proxy), and only the PaperMono C153 has been tested. See known limitations.

Author

Built by Seamus Cawley, who builds Bronto, the logging and observability platform, by day.

Credits

The firmware's board support, e-paper and touch drivers, keyboard layout and widget style are adapted from MonoMesh by andrecolz, an independent Meshtastic-compatible firmware for the same hardware. docs/design-notes.md lists exactly what was reused.

License

GNU General Public License v3.0, the same license as MonoMesh, which parts of the firmware derive from.

papermono-shopping-list (seamusc/papermono-shopping-list)

Searching Database…

205 ·GitHub
Papermono-shopping-list
What is this?Firmware and a companion server that turn the M5Stack PaperMono e-paper device into a household shopping list that lives on the fridge and stays in sync with a phone web app.
Is this just firmware, or does it include a server too?It is C++ firmware for the PaperMono hardware plus a small Python FastAPI server that stores the list and syncs it between the e-paper device and a phone web UI.
How do I get it running?Run the server first and open it on your phone to add your shop's aisles, then build and flash the firmware onto the PaperMono with PlatformIO.
What do I need to build and flash the firmware?PlatformIO and a PaperMono connected over USB-C to flash the device; the server side just needs Python/FastAPI, optionally run with Docker or systemd.
What are the current limitations?There's no on-device Wi-Fi setup since credentials are compiled in, the server has no authentication so it should stay on your LAN or behind a reverse proxy, and only the PaperMono C153 model has been tested.
Does the shopping list still work without Wi-Fi?Yes, ticking off and adding items works fully offline; Wi-Fi only turns on roughly hourly (or right after an edit) to sync, and edits queue on flash until then.
What is the PaperMono hardware itself?It's an ESP32-S3 device with a 3.97-inch, 480x800 e-paper touchscreen, which this project turns into a shopping list display.
Can new items be sorted into aisles automatically?Optionally yes: the first time the server sees an item name it can send it to Claude to file it under the right aisle, and if you move it manually that correction sticks.
How good is the e-paper interface in practice?Taps, scrolling and typing use fast partial refreshes with no flashing, a full refresh is forced every 10 partial updates to limit ghosting, and greys are rendered as 1-bit dot patterns so they look consistent either way.
Can I reuse this for my own PaperMono project?Yes, the author built it both as a working shopping list and as a compact, readable (~2,400 lines of C++) starting point for other PaperMono firmware.
What are similar projects?tiny-engineer, RuView, kindle-wall-display, esp-sdr, WLED, ESP32Marauder, cardputer-ai, arduino-esp32
Which topics is it in?display, wifi, home-automation, esp32, embedded-systems, reverse-proxy, firmware, offline-first, iot, fastapi, embedded, hardware
Creator
seamusc
Size
1 MB
Stars
205
Updated
CommitOct 15
Age
20d
Commits · 90 Days