ppclock — 4.2寸墨水屏设备离线 CLI 上位机

替代厂商 Web 上位机（mspppclock.tech）与 Android App 的完全离线命令行工具，面向 agent 编排设计：所有命令支持 --json 机器可读输出，batch 子命令支持 JSONL 批量执行。

设备：4.2" 400×300 黑/白/红三色墨水屏，Dialog DA14585 BLE SoC（广播名前缀 NRF-）。

安装

python3 -m venv .venv
.venv/bin/pip install -e .        # 依赖：bleak、pillow（离线 wheel 即可，运行零网络）
.venv/bin/ppclock --help

运行环境要求：Linux + 蓝牙适配器（bleak/D-Bus）。不需要互联网。

快速开始

ppclock scan                                # 扫描设备（NRF- 前缀）
ppclock --mac AA:BB:CC:DD:EE:FF time        # 对时（免扫描直连）
ppclock mode clock1                         # 时钟模式一
ppclock image photo.jpg --slot 0            # 传图到图一（默认 atkinson 抖动+三色）
ppclock template custom --data '{"text":"你好【世界】"}'
ppclock countdown 2026-12-31 --prefix "目标"  # 倒计时
ppclock batch job.jsonl --json              # 批量执行（单连接）

命令一览

命令	功能	对应 Web 上位机功能
`scan`	扫描设备	搜索设备
`time [ISO]`	对时	设置时间
`mode NAME`	clock1-3/calendar1-3/image0-3/tricolor/mono	时钟/日历/图片模式、三色/黑白
`toggle NAME`	invert/font/rotate180/hour_format/clock_color	反色/字体/旋转/12-24h/颜色
`clear`	刷屏	刷屏
`image PATH`	传图（6 种抖动+亮度/对比度/饱和度/旋转/缩放+槽位）	4.2传图/上传图片
`template NAME`	本地渲染 6 模板并上传	模板系统
`countdown`	倒计时日期/前缀文字/日历中文字/关闭	倒计时
`sleep`	休眠时段	休眠
`parking NUM`	停车牌	停车牌
`rotation`	轮播数量/间隔	轮播
`lut HEX`	红/黑 LUT 校准	LUT
`activate`	激活码下发/读取设备 ID	激活
`wifi`	WiFi+城市配置	WiFi 配置
`raw HEX`	高级命令直发	高级命令
`batch FILE`	JSONL 批量（单连接）	—（增强）

JSON 输出契约（`--json`）

成功：{"ok": true, "cmd": "<cmd>", "data": {...}} 失败：{"ok": false, "cmd": "<cmd>", "error": "<msg>"} 退出码：0 成功 / 1 参数错误 / 2 传输（BLE）错误 / 3 其他错误。

batch JSONL 格式

每行一条命令：{"argv": ["mode", "clock1"]}，输出 {"ok":true,"cmd":"batch","data":{"results":[...]}}。整个批量在一次 BLE 连接内完成；--stop-on-error 遇错即停。

定时推送（增强）

CLI 全部为单次执行语义，调度交给系统 cron：

# 每小时整点更新倒计时画面
0 * * * * /path/.venv/bin/ppclock --mac AA:BB:CC:DD:EE:FF countdown 2026-12-31 --prefix 目标 --json >> /var/log/ppclock.log 2>&1

离线说明

激活：原厂流程依赖云端 key_generator.php。本工具的本地化方案见 docs/firmware-analysis.md（激活校验分析）与 docs/protocol.md §7。
模板渲染、二维码生成（本地 qrcode 库）、抖动算法全部本地实现，无任何 CDN/服务器依赖。
天气（CITY 代码）属原厂云功能，本地化范围外；wifi 命令仅透传配置。

开发

.venv/bin/python -m pytest tests/ -q    # 104 测试

治理规则见 GOVERNANCE.md；计划见 PLAN.md；协议规范见 docs/protocol.md。

3.5 KiB Raw Blame History Unescape Escape