stev0760/Vibe-D30

# Vibe-D30 一款从零开始编写的 Linux 驱动 **和 WYSIWYG 标签编辑器**，专为 Phomemo D30 打造。这是一款廉价的、仅支持 BLE 的热敏标签打印机，其官方 App 仅支持 Android/iOS。通过直接扫描设备进行了逆向工程 （参见 [docs/hardware.md](docs/hardware.md) 和 [docs/ble.md](docs/ble.md)）， 并交叉参考了针对同一款打印机的早期开源项目 — 随后将其 vibe-coded（凭直觉编程）为适用于该设备的全功能标签制作应用。 该打印机通过 BLE GATT 传输标准的 Epson ESC/POS "GS v 0" 光栅数据 — 完全不需要操作系统级别的蓝牙配对，这就是为什么它在任何 系统蓝牙 UI 中都无法“配对”的原因（也是为什么在 `lsusb` 中查看 USB 什么也看不到的原因：该接口 仅支持充电）。BlueZ 的情况比这句话所描述的还要糟糕； [docs/ble.md](docs/ble.md) 中记录了关于 bearer 选择的完整曲折历程。 ## Web 编辑器 ``` .venv/bin/uvicorn server.app:app --port 8330 # 然后打开 http://127.0.0.1:8330 ``` - 自由绘制的标签画布：拖拽/缩放/微调元素，适配视图缩放， 真实的打印预览（画布下方的长条是真正的 1-bpp 渲染图 — 像素级还原实际打印效果） - 支持任何已安装**系统字体**的**文本**（通过 fontconfig 枚举， 并使用 FontFace API 加载到浏览器中），支持自适应尺寸调整， 支持粗体/斜体（在画布内合成，从而保证 WYSIWYG） - 支持使用 Floyd–Steinberg 抖动或阈值化处理的**图像** - **图标**：内置 1995 个可搜索的 Lucide 图标 - **打印起始偏移控制与校准**：走纸的起始位置取决于上一张标签被撕下的位置，因此打印工具栏 提供了一个偏移字段和一个“校准”按钮，用于打印一把毫米刻度尺 — 0 刻度处的剩余误差正是你需要输入的校正值 - 支持多份打印、固定/自动标签长度、模拟运行开关，文档将持久化存储在 localStorage 中 在服务器上设置 `D30_DRY_RUN=1` 可以在 开发期间强制所有打印执行模拟运行；设置 `D30_ADDRESS=` 可指向其他设备。 ## CLI ``` .venv/bin/python -m d30 "Hello World!" --length-mm 40 # dry run .venv/bin/python -m d30 "Hello World!" --length-mm 40 --live # print ``` ## 设置 ``` python3 -m venv .venv .venv/bin/pip install -r requirements.txt ``` 要运行 UI 回归测试（`scripts/ui_check.py`），你还需要 安装 Playwright：`.venv/bin/pip install playwright && .venv/bin/playwright install chromium`，然后针对开启了 `D30_DRY_RUN=1` 的服务器运行测试。 ## 状态 - [x] 已识别硬件：Phomemo D30（HVIN D30B），FCC ID 2ASRB-D30C - [x] 已从设备的支持 QR 码中提取出 BLE MAC 地址和序列号 - [x] 已完成 GATT 结构映射；打印协议已与现有技术成果比对 并在物理打印机上验证 - [x] 已诊断出 BlueZ bearer 选择失败的模式，并在 传输层中进行了规避 (docs/ble.md) - [x] `d30/` Python package：协议、BLE 传输、PIL 渲染、CLI - [x] 本地 Web App：FastAPI 服务器 + WYSIWYG 编辑器（文本/图像/图标） - [x] 带有界面内刻度尺校准的打印起始偏移控制 - [ ] QR / 条形码元素 - [ ] 模板管理器（超出 localStorage 范围） - [ ] 其他碳带尺寸（宽度已参数化，目前仅测试了 12mm） - [ ] 解码剩余的协议未知项（`ff01` 内容，通知字节 `02b600` / `1a0f0c`）— 计划抓取 Android HCI snoop 记录 ## 布局 - `d30/` — Python package：`protocol.py`（ESC/POS 封装 + 光栅 打包 + 偏移补偿），`transport.py`（通过 bleak 进行 BLE GATT 通信， BlueZ 坑点处理），`render.py`（PIL 自适应文本），`cli.py` - `server/app.py` — FastAPI：提供编辑器服务，枚举/提供系统 字体，打包客户端 PNG 并打印 - `web/` — 编辑器（无需构建的 vanilla ES modules + canvas） - `docs/` — 硬件/BLE 逆向工程分析文档 - `scripts/` — 侦察 + 校准工具，UI 回归测试 ## 设备标识 基于 Phomemo D30（HVIN D30B，FCC ID `2ASRB-D30C`， IC `29002-D30A`），BLE 名称 `D30` 开发。驱动程序通过 该名称发现打印机；使用 `--address` / `D30_ADDRESS` 固定特定设备（你的 设备的 MAC 地址位于其支持 QR 码中 — 参见 [docs/device-label.md](docs/device-label.md))。 ## 许可证与现有技术成果 Apache-2.0（参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)) — 继承 自 [odensc/phomemo-d30-web-bluetooth](https://github.com/odensc/phomemo-d30-web-bluetooth)， 本项目的协议理解正是与该实现进行验证 比对的。同时还参考了： [polskafan/phomemo_d30](https://github.com/polskafan/phomemo_d30) (MIT) 和 [crabdancing/phomemo-d30](https://github.com/crabdancing/phomemo-d30) (AGPL-3.0，仅文档)。内置的 [Lucide](https://lucide.dev) 图标遵循 ISC 许可证（参见 `web/LUCIDE-LICENSE.txt`）。

标签：ESC/POS协议, Linux驱动, 标签编辑器, 热敏打印机, 特征检测, 硬件逆向工程, 蓝牙低功耗, 逆向工具