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…

206 ·GitHub
Papermono-shopping-list
Что это?Прошивка и сопутствующий сервер, которые превращают устройство M5Stack PaperMono с экраном на электронных чернилах в домашний список покупок: он живёт на холодильнике и синхронизируется с веб-приложением на телефоне.
Это только прошивка или в комплекте есть и сервер?Это прошивка на C++ для железа PaperMono плюс небольшой сервер на Python FastAPI, который хранит список и синхронизирует его между устройством с электронными чернилами и веб-интерфейсом на телефоне.
Как это запустить?Сначала запустите сервер и откройте его на телефоне, чтобы добавить отделы вашего магазина, затем соберите и прошейте прошивку на PaperMono с помощью PlatformIO.
Что нужно для сборки и прошивки?PlatformIO и подключённый по USB-C PaperMono для прошивки устройства; серверу достаточно Python/FastAPI, при желании его можно запускать через Docker или systemd.
Какие сейчас есть ограничения?Настройки Wi-Fi на самом устройстве нет, так как учётные данные зашиты в прошивку; у сервера нет аутентификации, поэтому его стоит держать в локальной сети или за обратным прокси; протестирована только модель PaperMono C153.
Список покупок работает без Wi-Fi?Да, отметка и добавление пунктов полностью работают офлайн; Wi-Fi включается примерно раз в час (или сразу после изменения) для синхронизации, а правки до этого момента выстраиваются в очередь во флеш-памяти.
Что представляет собой само железо PaperMono?Это устройство на ESP32-S3 с сенсорным экраном на электронных чернилах диагональю 3,97 дюйма и разрешением 480x800, которое этот проект превращает в дисплей списка покупок.
Новые пункты раскладываются по отделам автоматически?При желании да: когда сервер впервые видит название пункта, он может отправить его в Claude, чтобы отнести к нужному отделу, а если вы переместите его вручную, эта поправка сохранится.
Насколько хорош интерфейс на электронных чернилах на практике?Нажатия, прокрутка и ввод используют быстрое частичное обновление без мерцания; полное обновление принудительно выполняется каждые 10 частичных, чтобы ограничить остаточное изображение, а серые цвета выводятся однобитным точечным узором, поэтому выглядят одинаково в обоих режимах.
Могу ли я переиспользовать это для собственного проекта на PaperMono?Да, автор сделал это и как работающий список покупок, и как компактную, читабельную (~2400 строк на C++) отправную точку для других прошивок под PaperMono.
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
206
Updated
CommitOct 15
Age
21d
Commits · 90 Days