# ppclock — 4.2寸墨水屏设备（DA14585 BLE）离线 SDK

> AI 消费向项目卡（llms.txt v0.2.0-beta）。人用文档见 README.md；签名级 API 见 docs/sdk/API.md；MCP 服务器见 docs/sdk/MCP.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   # 208 全绿
```

- 库：`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` 透明使用）
- MCP 服务器：`ppclock-mcp [--mac X] [--transport http --host 0.0.0.0 --port 8972]`（`PPCLOCK_MCP_TOKEN` 鉴权；extra `.[mcp]`）

## 快速示例

```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()                      # 离线激活（破解厂商云）
```

MCP 挂载（agent 直挂 13 工具）：`claude mcp add ppclock -- ppclock-mcp --mac X`，或 HTTP 端点 `http://<host>:8972/mcp` + Bearer token；详见 docs/sdk/MCP.md。

## 架构（关键不变量）

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 / ppclock-mcp（mcp_server 入口 / device_manager 连接管理 / mcp_tools 13 工具）
- `tools/`：fw_info/fw_pack（镜像工具）、field_test（真机引导测试）、flash_run、gpio_probe、rppclock.sh（守候重试）
- `docs/`：protocol.md（协议规范·唯一事实源）、sdk/API.md、sdk/MCP.md、architecture.md、firmware-analysis.md、firmware-layout.md、field-test-result.md
- `analysis/`：三线逆向证据（web/apk/firmware）
- `tests/`：208 测试

## 设备事实（实测 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.2.0-beta（CHANGELOG.md）。治理：GOVERNANCE.md（证据纪律/门禁）；历史决策：DECISIONS.md。