docs: README 使用文档
This commit is contained in:
agent committed
1 parent
5ff399673a
commit
0e2a6a351f
1 file changed
+84
@@ -0,0 +1,84 @@
|
|||||||
|
# ppclock — 4.2寸墨水屏设备离线 CLI 上位机
|
||||||
|
|
||||||
|
替代厂商 Web 上位机（mspppclock.tech）与 Android App 的**完全离线**命令行工具，
|
||||||
|
面向 agent 编排设计：所有命令支持 `--json` 机器可读输出，`batch` 子命令支持 JSONL 批量执行。
|
||||||
|
|
||||||
|
设备：4.2" 400×300 黑/白/红三色墨水屏，Dialog DA14585 BLE SoC（广播名前缀 `NRF-`）。
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 -m venv .venv
|
||||||
|
.venv/bin/pip install -e . # 依赖：bleak、pillow（离线 wheel 即可，运行零网络）
|
||||||
|
.venv/bin/ppclock --help
|
||||||
|
```
|
||||||
|
|
||||||
|
运行环境要求：Linux + 蓝牙适配器（bleak/D-Bus）。**不需要互联网**。
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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：
|
||||||
|
|
||||||
|
```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` 命令仅透传配置。
|
||||||
|
|
||||||
|
## 开发
|
||||||
|
|
||||||
|
```bash
|
||||||
|
.venv/bin/python -m pytest tests/ -q # 104 测试
|
||||||
|
```
|
||||||
|
|
||||||
|
治理规则见 `GOVERNANCE.md`；计划见 `PLAN.md`；协议规范见 `docs/protocol.md`。
|
||||||
Reference in new issue
Block a user