docs+release: CHANGELOG/llms.txt/SDK README/API.md，0.1.0 候选

2026-07-30 14:58:18 +00:00
1 parent 122023cdf4
commit 2b90d3891f
@@ -0,0 +1,63 @@
+# ppclock — 4.2寸墨水屏设备（DA14585 BLE）离线 SDK
+
+> AI 消费向项目卡（llms.txt v0.1.0）。人用文档见 README.md；签名级 API 见 docs/sdk/API.md。
+
+## 一句话
+
+ppclock 是 4.2" 400×300 黑白红三色墨水屏设备（Dialog DA14585，广播名 `NRF-` 前缀）的**完全离线** Python SDK 与 CLI：BLE 协议三线逆向（Web JS/APK/固件反汇编）+ 真机互证，覆盖厂商全部功能 + 离线激活 + SUOTA 工具链 + BLE bridge 远程蓝牙。
+
+## 安装与运行
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests/ -q   # 165 全绿
+```
+
+- 库：`from ppclock import PPClient`
+- CLI：`ppclock [--json] [--mac X] [--via bridge://host[:port]] <cmd>`
+- BLE 桥：`ppclock-bridge --host 0.0.0.0 --port 8971`（在他机蓝牙物理所在机运行，本机经 `--via` 透明使用）
+
+## 快速示例
+
+```python
+async with PPClient.via_bridge("192.168.61.35:8971", mac="18:BC:5A:5D:BF:28") as dev:
+    await dev.set_time(tz=8)                       # 北京时间
+    await dev.upload_image("photo.jpg", slot=0)    # 传图（默认 atkinson 三色抖动）
+    await dev.set_mode("image0")                   # 显示图一
+    await dev.render_template("custom", {"text": "你好【红字】"})
+    await dev.activate_auto()                      # 离线激活（破解厂商云）
+```
+
+## 架构（关键不变量）
+
+1. **命令走 331f（alt 通道）**：1f1f 只 ATT-ACK 不执行（实机证据，勿用）。
+2. 图像：400×300，1bpp MSB-first 行主序双平面（bw 15000B + red 15000B）；块 244B（`03|04`+`ff|00`+2B BE 偏移）；整图 `01` 结束、小图 `AA`。
+3. BCD 字段（休眠小时/倒计时月日）与真 hex 字段（dd 时间帧）严格区分。
+4. 离线激活：`code[i] = ror2(((MAC[i]<<1)&0xFF)^0xEF) % 101`；MAC 由 EFEF 设备 ID（14hex，参数序 MAC5 在前）无损反解。
+5. 零网络依赖（除本机 BLE / LAN bridge）。
+
+## 目录
+
+- `src/ppclock/`：client.py（门面）/ protocol / image_pipeline / templates / transports(base,local,bridge) / firmware(image,ota) / cli / bridge_server
+- `tools/`：fw_info/fw_pack（镜像工具）、field_test（真机引导测试）、flash_run、gpio_probe、rppclock.sh（守候重试）
+- `docs/`：protocol.md（协议规范·唯一事实源）、sdk/API.md、architecture.md、firmware-analysis.md、firmware-layout.md、field-test-result.md
+- `analysis/`：三线逆向证据（web/apk/firmware）
+- `tests/`：165 测试
+
+## 设备事实（实测 NRF-5DBF28）
+
+- GATT：EPD svc `13187b10-…`/char `4b646063-…`(h=48,notify+write)；RXTX svc `00001f10`；**活命令 char `0000331f`(h=57)**；`00001f1f`(h=53,write-only,不执行)；SUOTA svc `0000fef5`（自定义 6 特征）。
+- 闪存：本机裸布局（app@0x0，无 'pP' 引导、0x38000 无 'pR' 产品头）→ SUOTA 止于产品头门禁（状态 20）；工厂布局与恢复路径见 docs/firmware-layout.md。
+- 睡眠：广播窗口短（约 30-60s），连接态保持清醒；批量操作用单连接（PPClient 或 `ppclock batch`）。
+- no-op 命令（本固件）：轮播 e9xx/EA0x、WiFi 配置。
+- 停车牌 EF：命令被收但不显示（K1 待查）。
+
+## 扩展点
+
+- 自定义传输：实现 `ppclock.transports.base.Transport`（鸭子类型协议），注入 `PPClient(transport)`。
+- 新模板：`ppclock.templates.RENDERERS[name] = fn(payload) -> PIL.Image`。
+- bridge 协议：docs/sdk/API.md §Bridge RPC。
+
+## 版本
+
+0.1.0（CHANGELOG.md）。治理：GOVERNANCE.md（证据纪律/门禁）；历史决策：DECISIONS.md。