ChiaraCannolee/thermal-pocket-printer-basic

# thermal-pocket-printer-基础 直接通过蓝牙从电脑打印到 **DP-L1S** 热敏口袋打印机，无需任何 App。 DP-L1S 是由厦门印未来科技制造的一款小型热敏口袋打印机，以多个品牌名称销售（在 NL/EU 地区通过 Craft & Co、Action 商店等渠道销售，品牌名为 Crafts & Co 3128）。其配套 App “Luck Jingle” 要求获取位置权限、持久的互联网连接，以及一大串其他权限——对于一台只是通过蓝牙在 30 厘米外接收图像的打印机来说，这些要求根本毫无道理。 因此，我使用 JADX 反编译了 Android APK，逆向工程了 BLE 协议，并构建了一个 Python CLI 工具和一个 Web 应用程序，可以直接与打印机通信。无需 App，无需账户，无需云服务。 ## 快速开始 **Web 应用（无需安装，只需在 Chrome/Edge/Opera 中打开）：** **https://ChiaraCannolee.github.io/thermal-pocket-printer-basic/** 由于需要使用 Web Bluetooth，因此不支持 Firefox 和 Safari。支持 macOS 和 Linux。Windows 版本还需等待 Web Bluetooth 提供更好的支持。 **Python CLI（用于自动化和批处理任务）：** ``` pip install bleak Pillow python3 print.py test # test pattern python3 print.py image photo.png --dither # photo with Floyd-Steinberg python3 print.py text "Hello World" python3 print.py text "My Label" --label # sticker/label paper mode python3 print.py info # battery, firmware, model ``` ## 功能特性 - 打印图像、文本和测试图案 - 实时预览打印输出效果 - 三种打印浓度级别 - 针对照片和渐变色的 Floyd-Steinberg 抖动算法 - 反色模式（交换黑白颜色） - 标签模式，支持带间隙检测的贴纸纸 - 通过 BLE 通知显示电池电量指示器 ## 工作原理 该打印机运行在 LuckPrinter SDK 上，有超过 159 种打印机型号在使用该 SDK。其 BLE 协议是 ESC/POS 的一个变体。基本流程如下： 1. **连接**到 BLE 服务 `ff00`，向特征值 `ff02` 写入数据，并在 `ff01` 上监听通知 2. **启用打印机**：发送 `10 FF F1 03`（Lujiang 特定命令） 3. **唤醒**：发送 12 个空字节 4. **设置浓度**（可选）：`10 FF 10 00 [0|1|2]` 分别对应 浅/正常/深 5. **发送位图**：GS v 0 光栅图像（宽 384 像素，1 位，MSB 优先） 6. **走纸**：`1B 4A 50`（走纸 80 点） 7. **停止作业**：`10 FF F1 45`（等待响应） 对于带间隙检测的标签/贴纸纸，请将第 6 步替换为 `1D 0C`（定位到下一个标签），并在打印前使用 `1F 11 51`，打印后使用 `1F 11 50` 进行位置调整。 由于 Web Bluetooth 的 MTU 限制，Web 版本采用 100 字节的数据块并带有 50ms 的延迟。Python CLI 则使用 512 字节的数据块和 10ms 的延迟，速度明显快得多。 该打印机广播名称为 `C&Co 3128_BLE`，并且不会广播其服务 UUID，因此仅通过服务过滤器扫描是无法找到它的。 请参阅 [PROTOCOL.md](PROTOCOL.md) 获取完整的命令参考，包括设备信息查询、状态位域以及标签/纹身打印序列。 ## CLI 用法 ``` python3 print.py [options] Commands: scan Scan for nearby BLE printers info Show printer info (model, battery, firmware) test Print a test pattern image Print an image (PNG, JPG, BMP, etc.) text Print text Options: --address, -a Printer BLE address (skip scanning) --density, -d 0|1|2 Print darkness (0=light, 1=normal, 2=dark) --dither Floyd-Steinberg dithering (better for photos) --invert Invert colours (white-on-black) --label Label/sticker mode with gap detection --copies, -c N Number of copies --width, -w N Print width in pixels (default: 384) --feed, -f N Paper feed after print in dots (default: 80) ``` ## 兼容打印机 已确认可与 DP-L1S（作为 Crafts & Co 3128 及其他贴牌名称销售）配合使用。可能也适用于共享相同 SDK 和 `BaseNormalDevice` 类的 LuckPrinter 系列中的其他打印机——如 DP-/LuckP-/MiniPocketPrinter 系列及类似产品。打印宽度可能有所不同；请使用 `python3 print.py info` 进行检查。 对于 Fichero D11s 及其他基于 AiYin 的标签打印机（设备类别不同，但 SDK 相同），请参阅由 0xMH 提供的 [fichero-printer](https://github.com/0xMH/fichero-printer)。 ## 兼容纸张 该打印机使用 56mm 宽的热敏纸和贴纸卷（标签直径 30mm）。它是“免墨”的：热量激活热敏涂层，因此彩色纸张仅会在黑色打印内容下提供彩色背景。 ## 即将推出 我正在开发一个功能扩展的 Web 版本，包含以下特性： - 带有预设尺寸（29×12mm、40×12mm、50×30mm、40×30mm、48mm 圆形及自定义）的可调标签大小 - 在浏览器中本地保存和加载模板 - 直接在预览中拖动文本以实现自由定位 - 撤销/重做 - 包含可调阈值、份数、浓度覆盖和打印后走纸量（以毫米为单位）的打印预览界面 本仓库中的基础功能已趋于稳定，因此优先发布此版本。扩展版本将在后续拥有其独立的仓库。 ## 背景 本项目最初源于一次隐私保护实践。“Luck Jingle” App 要求获取位置权限、互联网访问权限以及其他各种对于蓝牙打印机而言毫无必要的权限。通过使用 JADX 反编译 Android APK 并阅读 LuckPrinter SDK 中的 `PrinterImageProcessor` 和 `BaseNormalDevice` 类，该协议被成功逆向工程，随后并在硬件上得到了验证。 ## 许可证 MIT

标签：Bleak库, BLE协议逆向, DP-L1S, ESC/POS协议, JADX反编译, Pillow库, Python CLI, Web Bluetooth, 免云服务, 协议逆向工程, 后端开发, 图像处理, 图像打印, 安卓APK分析, 开源硬件, 批处理打印, 插件系统, 数据可视化, 无App打印, 本地控制, 标签打印, 桌面自动化, 热敏打印机, 热敏纸, 物联网设备, 直接打印, 网络安全, 自制工具, 菲尔德-斯坦伯格抖动, 蓝牙低功耗, 蓝牙打印机, 蓝牙通信, 逆向工具, 隐私保护