seamusc/papermono-shopping-list

来源：https://github.com/seamusc/papermono-shopping-list

PaperMono 购物清单固件

适用于 M5Stack PaperMono 电子墨水屏设备。它能将设备转变为贴在冰箱上、与手机网页应用保持同步的家用购物清单。

PaperMono 是一款搭载 3.97 英寸 480×800 电子墨水触摸屏的 ESP32-S3 设备。本项目为其提供了一个完整、可运行的应用程序，代码量精简易读：约 2,400 行 C++ 代码。你可以将其用作购物清单，或作为开发自己 PaperMono 固件的起点。

PaperMono 上显示的特性

• 正确处理电子墨水屏刷新。 点击、滚动和输入均采用无闪烁的快速局部刷新。每执行 10 次局部刷新后，会强制进行一次全屏刷新，以减少残影并保护屏幕面板。灰度以 1 位点阵模式绘制，因此在两种刷新模式下视觉效果一致。
• 在电子墨水屏上实现可用的触摸 UI。 点击、滑动和侧边按钮均可正常使用。屏幕键盘仅重绘输入时变化的部分，并能推荐你之前添加过的商品。
• 低功耗网络连接。 Wi-Fi 仅在同步时开启：每小时一次，若点击屏幕且上次同步超过 5 分钟，则会提前同步；每次编辑后也会立即同步。其他操作均离线进行，编辑内容会暂存至闪存，待下次同步时处理。
• 高效的电源管理。 通过电源按钮关机；当 USB 供电导致电源 IC 无法正常关闭时，设备会进入深度睡眠模式。设备在安全的电池电压下自动关闭。前光默认关闭。
• 有记录的初始化流程。 电源 IC、IO 扩展器、屏幕面板和触摸控制器均按已验证的顺序启动。docs/hardware.md 包含引脚映射、I2C 地址以及过程中发现的特殊问题。

工作原理

设备按购物通道分组显示购物清单，并按照你逛超市的顺序排列。点击商品可将其标记为已购买，或使用屏幕键盘添加新商品。其他家庭成员可通过手机添加商品。中间的小型服务器负责存储清单。服务器会记住每个商品所属的通道，并可选择使用 Claude 将新商品自动归类到正确的通道。

flowchart LR
    device["PaperMono（固件）"] -- "Wi-Fi，每小时同步或点击时同步\n以及每次编辑后同步" --> server
    phone["手机浏览器"] -- HTTP --> server
    subgraph server["服务器（server）"]
        api["FastAPI + SQLite"]
        web["网页界面"]
    end
    api -. "仅新商品名称" .-> claude["Claude Code CLI\n（可选）"]

• 按购物通道分组，按行走顺序排列。 你在手机上设置一次通道顺序，两个界面都会遵循该顺序。
• 支持离线工作。 商品清单、推荐、标记已购买和添加商品均可在无网络连接时使用，即使在信号不佳的商店也能正常操作。
• 记忆你的商品。 你添加的每个商品名称都会进入商品库，用于在设备和手机上提供推荐。
• 可选自动分类。 当服务器首次看到某个商品名称时，可将其发送给 Claude 归类到相应通道。若你手动将商品移至其他通道，此修正会保持有效。

仓库结构

firmware/        PaperMono 的 PlatformIO 项目（C++ / Arduino）
server/          FastAPI 服务器，SQLite 存储，手机网页界面，测试
docs/            硬件笔记、架构、API、构建与部署指南、设计说明

快速开始

1. 运行服务器

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

在手机上打开 http://:8000/，点击 Aisles，按你逛超市的顺序添加各通道。关于 systemd 和 Docker 部署，以及启用自动分类，请参阅 docs/server.md。

2. 构建并刷写固件

你需要 PlatformIO 和通过 USB-C 连接的 PaperMono 设备。

cd firmware
cp src/secrets.example.h src/secrets.h  # 设置 Wi-Fi SSID/密码和服务器地址
pio run -t upload

刷写前请备份设备的闪存。 其中包含该设备的出厂校准数据。docs/firmware.md 介绍了备份、进入下载模式以及从浏览器刷写的方法。

文档

项目状态

个人项目，在家中的一台设备上运行。功能正常，但并非正式产品。设备端不支持 Wi-Fi 配置（凭证已编译入固件），服务器无认证功能（请确保其处于局域网内或受认证反向代理保护），且仅在 PaperMono C153 型号上测试过。详见 已知限制。

作者

由 Seamus Cawley 构建，他白天开发 Bronto（https://bronto.io），一款日志与可观测性平台。

致谢

固件的开发板支持、电子墨水屏与触摸驱动、键盘布局和小组件样式改编自 MonoMesh，这是 andrecolz 开发的适用于同一硬件的独立 Meshtastic 兼容固件。docs/design-notes.md 列出了具体复用内容。

许可证

GNU 通用公共许可证 v3.0，与 MonoMesh 相同，本固件部分代码衍生自该项目。