eteriall/katasymbol-e12-lab

# KATASYMBOL E12 实验室 用于逆向工程和打印至 KATASYMBOL/SUPVAN E12 风格蓝牙标签机的开源 Python 工具。 该项目目标很简单：让打印机在没有官方移动应用的情况下也能使用。它提供了一个轻量级的协议库、一个命令行工具、一个 Tkinter GUI，以及一个原始 BLE 实验框架，让开发者能够检查打印机、渲染标签，并通过低功耗蓝牙直接发送打印任务。 这不是 KATASYMBOL 或 SUPVAN 的官方 SDK。这是一个基于公开协议笔记和对真实硬件的实测而构建的社区逆向工程项目。 ## 功能说明 - 扫描附近的 BLE 设备并识别可能的打印机候选。 - 探测打印机特性、状态和标签材质元数据。 - 打印文本标签。 - 打印图像标签。 - 打印 QR 标签。 - 在发送任务前使用 GUI 进行预览。 - 批量打印：每次点击生成一个递增的 QR 标签，适用于类似 `COB-1`, `COB-2`, `COB-3` 的 ID。 - 当打印机表现异常时，调整实验性协议设置。 目前测试最可靠的路径是： - E12 级 BLE 打印机 - BLE service `0000fee7-0000-1000-8000-00805f9b34fb` - characteristic `0000fec1-0000-1000-8000-00805f9b34fb` - 96 点打印头 - 12 mm 标签带宽度 - 以压缩的 512 字节帧发送的光栅数据 ## 项目初衷 这些小型标签打印机很实用，但官方工作流程通常依赖于一个闭源的移动应用。本项目记录了足够多的蓝牙协议细节，让你能够通过自己的脚本和工具进行打印。 它也旨在成为一个实用的逆向工程工作区。GUI 保持显示调试控件，因为不同的打印机固件版本可能需要略微调整命令发送时机、状态处理或停止行为。 ## 项目布局 - `katasymbol_e12.py` - 协议代码、光栅渲染、压缩、CLI。 - `katasymbol_e12_gui.py` - 用于手动和批量打印的 Tkinter 桌面 UI。 - `e12_reverse_lab.py` - 用于协议测试的原始 BLE 实验运行器。 - `requirements.txt` - 直接运行脚本的运行时依赖。 - `pyproject.toml` - 包元数据和控制台入口点。 ## 安装说明 ``` python3 -m venv .venv . .venv/bin/activate pip install -e . ``` 这会安装三个命令： ``` katasymbol-e12 katasymbol-e12-gui e12-reverse-lab ``` 对于仅使用脚本进行开发，以下方式也可行： ``` pip install -r requirements.txt ``` ## GUI 使用说明 启动 GUI： ``` katasymbol-e12-gui ``` 或： ``` python katasymbol_e12_gui.py ``` 推荐的首次运行步骤： 1. 打开 Devices 选项卡。 2. 点击 Scan 并选择打印机。 3. 点击 Probe 并确认 `check=True`。 4. 打开 Manual Print。 5. 使用 Dry Run 验证渲染后的 payload 大小。 6. 在打印自定义标签前先进行 Print Test。 7. 当你需要每次点击生成一个递增的 QR 标签时，使用 Batch QR。 GUI 会将记忆的设备、设置、批量计数器和日志存储在代码仓库之外的位置： ``` ~/.katasymbol-e12/gui_state.json ``` 使用以下命令覆盖该路径： ``` KATASYMBOL_E12_STATE=/path/to/gui_state.json katasymbol-e12-gui ``` ## CLI 使用说明 扫描： ``` katasymbol-e12 scan ``` 探测： ``` katasymbol-e12 probe ``` 打印文本： ``` katasymbol-e12 print-text "HELLO E12" \ --label-width-mm 12 \ --length-mm 40 \ --printhead-width-dots 96 ``` 打印图像： ``` katasymbol-e12 print-image label.png \ --label-width-mm 12 \ --length-mm 40 \ --printhead-width-dots 96 ``` 渲染但不打印： ``` katasymbol-e12 dry-run "HELLO E12" \ --label-width-mm 12 \ --length-mm 40 \ --printhead-width-dots 96 ``` ## 原始 BLE 实验室 `e12-reverse-lab` 发送低级命令/数据序列。这对于协议研究很有用，但它可能会使打印机卡在忙碌或打印状态。请将打印机放在手边，并准备好对其进行断电重启。 使用明确地址运行： ``` e12-reverse-lab --address \ --pattern full_band \ --length-mm 40 ``` 或者设置一次地址： ``` export KATASYMBOL_E12_ADDRESS= e12-reverse-lab --pattern columns ``` ## 协议背景 该项目基于公开的 SUPVAN 协议研究成果，特别是： - https://github.com/heeen/supvan-cups - https://github.com/heeen/supvan-cups/blob/master/docs/PROTOCOL.md 打印机使用 `0x7E 0x5A` 命令帧和压缩的光栅数据帧。 已知的类似 KATASYMBOL/SUPVAN BLE 打印机曾使用以下 GATT 模式： - service `0000fee7-0000-1000-8000-00805f9b34fb`, characteristic `0000fec1-0000-1000-8000-00805f9b34fb` - service `0000e0ff-3c17-d293-8e48-14fe2e4da212`, notify `0000ffe1-0000-1000-8000-00805f9b34fb`, write `0000ffe9-0000-1000-8000-00805f9b34fb` - service `0000ff00-0000-1000-8000-00805f9b34fb`, notify `0000ff01-0000-1000-8000-00805f9b34fb`, write `0000ff02-0000-1000-8000-00805f9b34fb` ## 已知特性 - 即使安装了可打印的标签纸，一些打印机仍会报告 `ribbon_end=True`。在这种情况下，GUI 提供了 `Ignore ribbon_end status` 选项。 - 某些固件版本需要不同的 `STOP_PRINT` 时机，以减少尾部多余的空白走纸。 - macOS 会将 BLE 设备公开为类似 UUID 的标识符，而不是公共 MAC 地址。 - 如果打印任务冻结，请先使用 Stop Print。如果这无法清除状态，请对打印机进行断电重启。 ## 安全说明 请从短标签和低浓度开始测试。该协议仍处于实验阶段，错误的命令序列可能会浪费标签纸，或使打印机一直处于忙碌状态，直到将其重启。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：Python, Tkinter, 云资产清单, 文档结构分析, 无后门, 标签打印机, 硬件接口, 蓝牙低功耗(BLE), 逆向工具, 逆向工程