🧾 ThermPrint

一个轻量级、开源的 Web 应用，用于将图像和二维码打印到 BLE 热敏打印机。无广告，无臃肿，绝不废话。

## 🤔 问题背景 我从 Shopee 上随便买了一台便携式热敏图像打印机，打算为我的手账打印一些图片。收到货后，我安装了官方应用——尽管它的用户界面很漂亮，但充斥着我根本不需要的臃肿功能。作为一个极客，我必须深入研究一下。于是我下载了 APK 并将其反编译，在 ChatGPT、Claude Opus 和 Deepseek 的帮助下，我逆向工程了 BLE 数据传输协议，并开发了自己的替代应用。 ## ✅ 解决方案 最终的成果是一个轻量、整洁且极简的 Web 应用，让你可以直接从浏览器将图像和二维码打印到 BLE 热敏打印机。无广告，无臃肿，绝不废话。完全开源——你可以随心所欲地进行修改。 ## ✨ 功能特性 - **图像打印** - 上传任意图像，调整对比度/伽马值/旋转角度，预览结果后将其发送到打印机 - **二维码打印** - 从 URL 生成二维码，支持自定义尺寸、样式（方形、圆形、圆角、间隙、垂直/水平条纹）以及可选的内嵌 Logo - **实时队列** - 通过 WebSocket 实时更新任务状态，并为正在进行的打印任务提供进度条 - **持久化历史** - 得益于 SQLite 存储，打印任务在服务器重启后依然保留，支持分页浏览和预览缩略图 - **BLE 设备管理** - 扫描附近的打印机，选择并持久化保存你的设备名称 - **主题切换** - 从 35+ 种内置的 daisyUI 主题中进行选择，并持久化保存到 localStorage - **整洁极简的 UI** - 使用 React + Tailwind + DaisyUI 构建，对移动端和桌面端均有完美的响应式支持 ## 🖥 屏幕截图 ## 🔬 技术栈         **前端:** React, TypeScript, Tailwind CSS, DaisyUI, TanStack Query **后端:** Python, FastAPI, Uvicorn, Bleak (BLE), Pillow (图像处理), aiosqlite **协议:** 从官方 APK 逆向工程的 BLE GATT 通信协议 ## ⌨️ 设置说明 ### 前置条件 - Python 3.10+ - Node.js 18+ - 支持此特定协议的热敏打印机 ### 后端 ``` cd server uv venv source .venv/bin/activate uv pip install -r requirements.txt uvicorn server.app.main:app --reload --port 8000 ``` ### 前端 ``` cd client bun install bun run dev ``` 在浏览器中打开 `http://localhost:5173`。 ## 🧪 运行测试 ``` cd server source .venv/bin/activate pytest ``` ## 🔌 API 接口 | 方法 | 接口 | 描述 | |--------|----------|-------------| | `POST` | `/api/print` | 打印图像 | | `POST` | `/api/preview` | 预览图像 | | `POST` | `/api/qrcode` | 打印二维码 | | `POST` | `/api/qrcode/preview` | 预览二维码 | | `GET` | `/api/jobs` | 列出打印任务（分页） | | `DELETE` | `/api/jobs/{id}` | 取消任务 | | `DELETE` | `/api/jobs/{id}/delete` | 删除任务 | | `GET` | `/api/device` | 获取已配置的设备名称 | | `PUT` | `/api/device` | 更新设备名称 | | `GET` | `/api/devices` | 扫描 BLE 打印机 | | `GET` | `/api/status` | 获取连接状态 | | `GET` | `/api/settings` | 获取打印设置 | | `PUT` | `/api/settings` | 更新打印设置 | | `WS` | `/api/ws/jobs` | 实时任务更新 | | `WS` | `/api/ws/status` | 实时连接状态 | 当后端服务器运行时，可以通过访问 `http://localhost:8000/docs` 来使用交互式的 Swagger UI，它提供了一种便捷的方式来直接从浏览器探索和测试每一个接口。 ## 📈 项目状态 该项目的所有核心功能均已完成。如果你碰巧发现了任何错误，欢迎在此 GitHub 仓库中提交 issue。 ## 🙏 鸣谢 如果没有以下几款 AI 工具和资源的帮助，这个项目就不可能存在： - **[ChatGPT](https://chatgpt.com)** - 协助进行了初步的 APK 反编译分析和 BLE 协议发现 - 通过 Antigravity 使用的 **[Claude Opus](https://antigravity.ai)** - 深入研究代码库，实现了从反编译 APK 中提取的算法和协议移植 - 通过 OpenCode 使用的 **[Deepseek](https://opencode.ai)** - 协助构建了后端服务器和前端界面 - **[这篇文章](https://github.com/erkanybekov/BlutoothLan)** - 一个与我类似的项目，不过它是一个基于 Swift 构建的 iOS 应用。它给了我动力并证明了可行性 ## 🛒 购买打印机 本项目专为这款[Shopee 上在售的便携式热敏打印机](https://shopee.com.my/product/12011726/19010120735)而开发。如果你想亲自尝试，可以买一台并按照上面的设置说明进行操作。 ## 📄 许可证 本项目基于 MIT 许可证授权。

标签：BLE热敏打印机, DaisyUI, React, SQLite, Syscalls, Tailwind CSS, WebSocket, Web打印应用, 个人项目, 二维码生成, 二进制发布, 云资产清单, 依赖分析, 图像打印, 图片处理, 开源工具, 打印队列管理, 无冗余功能, 无广告, 极简主义, 物联网设备, 移动端响应式, 自定义主题, 蓝牙低功耗, 蓝牙打印机, 跨平台Web应用, 轻量级应用, 逆向工具, 逆向工程