chenwei/qianbian
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
qianbian/docs/superpowers/plans/2026-07-24-eink-4.2-reverse.md
T

8.4 KiB
Raw Permalink Blame History

4.2寸 e-ink 设备逆向与本地化改造 · 总体实现计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking. 工作准则见根目录 GOVERNANCE.md；进度记录于 PROGRESS.md。

Goal: 摸清 4.2寸墨水屏设备（DA14585 BLE SoC）软硬件架构，交付离线可用的 agent 友好 CLI 上位机，并获得固件级可控能力。

Architecture: 三条证据线（Web 上位机 JS / Android APK / DA14585 固件镜像）互证还原 BLE GATT 协议与图像协议 → 以 Python+bleak 实现离线 CLI（JSON I/O，面向 agent）→ 固件镜像解析/修改/SUOTA 工具链实现软硬件可控。

Tech Stack: Python 3.12、bleak（BLE）、Pillow（图像抖动）、jadx/androguard（APK）、capstone（固件反汇编）、pytest。

Global Constraints

  • 交付物运行零互联网依赖（仅本机 BLE）。（任务说明 目标2）
  • CLI 面向 agent：所有命令支持 --json 机器可读输出。
  • 功能集必须先对齐 Web 上位机现有功能，再谈增强。（任务说明 目标2）
  • 固件指 DA14585 镜像；可控 = 能解析、能修改、能重生成可烧录镜像、SUOTA 流程文档化。（任务说明 目标3 + GOVERNANCE G4）
  • app/ 原始输入只读；所有结论须附证据。

阶段总览与门禁

阶段 内容 门禁
P0 治理+工具链 git 就绪；jadx/androguard/capstone/bleak 可用
P1 三线逆向（Web→APK→固件） G1：architecture.md + protocol.md，三线互证
P2 CLI 上位机（功能对齐） G2、G3：测试全绿，功能清单逐项覆盖
P3 增强 + 固件可控 G4、G5：镜像工具+SUOTA 文档；离线验收

P0：工具链（Task 1）

Task 1: 分析环境搭建

Files:

  • Create: requirements.txt, tools/check_env.py

  • Step 1: 创建 venv 并安装依赖

python3 -m venv .venv && .venv/bin/pip install -q --upgrade pip
.venv/bin/pip install bleak pillow pytest capstone androguard
apt-get install -y jadx 2>/dev/null || (cd /opt && curl -sL -o jadx.zip https://github.com/skylot/jadx/releases/download/v1.5.1/jadx-1.5.1.zip && unzip -qo jadx.zip)
  • Step 2: 写环境自检 tools/check_env.py（导入 bleak/pillow/capstone/androguard；检查 jadx 可执行；打印版本表）
  • Step 3: 运行自检，预期全 OK
  • Step 4: 冻结 requirements.txt 并提交

P1：三线逆向（Task 2–4）

Task 2: Web 上位机协议提取（最快路径，先做）

Files:

  • Create: analysis/web/fetch.sh, docs/protocol.md

  • Step 1: 抓取站点全部 JS/HTML 到 analysis/web/（curl 递归，含 file_down.php 固件列表）

  • Step 2: 提取并记录：BLE service/characteristic UUID、通知/写入选项、命令字节格式、图像分块与应答协议、模板/时钟/倒计时命令

  • Step 3: 写入 docs/protocol.md（每条注明来源文件与行号）

  • Step 4: 提交

Task 3: APK 反编译与互证

Files:

  • Create: analysis/apk/notes.md, 修改 docs/protocol.md

  • Step 1: jadx 反编译到 analysis/apk/jadx-out/（不入库）；搜索 BluetoothGattCharacteristic、writeCharacteristic、UUID 常量、激活码网络请求

  • Step 2: 与 Web 端逐项比对协议字段；差异写 DECISIONS.md

  • Step 3: 整理功能清单（时钟模式/倒计时/传图抖动算法/6 模板/睡眠/停车牌/WiFi 配置/高级命令）入 docs/protocol.md 附录

  • Step 4: 提取图像处理参数（4.2寸=400x300，三色屏 B/W/R 通道编码方式）

  • Step 5: 提交

Task 4: DA14585 固件分析

Files:

  • Create: analysis/firmware/disasm.py, docs/firmware-analysis.md, 修改 docs/architecture.md

  • Step 1: 解析镜像头（0x70 0x51 'pQ' 签名、长度、校验），定位加载基址（向量表显示 0x07FCxxxx）

  • Step 2: capstone 反汇编（Thumb, Cortex-M0），定位：GATT 属性表（UUID 字节型匹配）、命令解析跳转表、SPI 墨水屏驱动初始化序列、SUOTA 服务

  • Step 3: 与 protocol.md 互证命令集；记录墨水屏型号线索（4.2" 400x300 三色 → SSD16xx/UC81xx 系驱动 IC 初始化序列比对）

  • Step 4: 写 docs/firmware-analysis.md（内存布局、关键函数偏移、镜像校验算法）+ docs/architecture.md

  • Step 5: 提交；G1 门禁检查

P2：CLI 上位机（Task 5–9）

Task 5: BLE 传输层 + 协议编解码（TDD）

Files:

  • Create: src/ppclock/protocol.py, src/ppclock/transport.py, tests/test_protocol.py

Interfaces:

  • Produces: encode_command(cmd: int, payload: bytes) -> bytes、decode_notification(data: bytes) -> dict、BLETransport.open/close/write/notify（UUID 常量全部来自 docs/protocol.md）

  • Step 1: 用 Task 2/3 的真实测试向量写失败测试（编解码往返、分块序号、校验字节）

  • Step 2: 跑测试确认失败

  • Step 3: 实现 protocol.py（纯函数，无 BLE 依赖）

  • Step 4: 实现 transport.py（bleak 封装：扫描按名称/MAC 过滤、连接、MTU 协商、写+等通知）

  • Step 5: 测试全绿后提交

Task 6: 图像管线

Files:

  • Create: src/ppclock/image_pipeline.py, tests/test_image.py

  • Step 1: 失败测试：400x300 输入 → 设备原生位平面字节流（对照 APK 提取的编码：B/W/R 通道映射、扫描方向、字节序）

  • Step 2: 实现六种抖动（Floyd-Steinberg/Atkinson/Bayer/Stucki/Jarvis-Judice-Ninke/无抖动阈值）+ 亮度/对比度/饱和度/旋转/缩放

  • Step 3: 全绿提交

Task 7: 功能命令层（时钟/日历/倒计时/模板/睡眠/停车牌/高级命令）

Files:

  • Create: src/ppclock/commands.py, tests/test_commands.py

  • Step 1: 逐功能写失败测试（参数→字节流，向量来自 protocol.md）

  • Step 2: 实现全部功能命令

  • Step 3: 全绿提交

Task 8: CLI 入口（agent 友好）

Files:

  • Create: src/ppclock/cli.py, src/ppclock/__main__.py, tests/test_cli.py

  • Step 1: argparse 子命令：scan / clock / calendar / countdown / image / template / sleep / parking / wifi-config / raw / ota；全局 --json、--mac、--timeout

  • Step 2: --json 输出 schema 固定（{"ok":bool,"cmd":str,"data":...,"error":...}），错误码文档化

  • Step 3: mock transport 的 CLI 集成测试全绿；提交；G2 门禁检查

Task 9: 真机功能对齐验证 —— ✅ 完成（2026-07-28/29 实机）

  • Step 1: 对照 protocol.md 功能清单逐项在真机执行 CLI（每步记录结果与抓包）——2026-07-28/29 经 bridge 实机完成（六步全过+扩展 12 步+六抖动+六模板，记录 docs/field-test-result.md；K1 停车牌待查为唯一遗留）
  • Step 2（降级）: 以 FakeTransport 逐帧断言 + 三线证据互证替代（tests/test_cli.py、test_commands.py）；G3 以协议级达标记录于 PROGRESS.md

P3：增强与固件可控（Task 10–12）

Task 10: 功能增强

  • Step 1: 本地模板渲染（Pillow 离屏渲染 6 模板 → image 推送，摆脱 App 画布）
  • Step 2: schedule 子命令：定时/周期推送（cron 友好，单次执行语义，调度交给系统）
  • Step 3: batch 子命令：JSONL 批量执行，面向 agent 编排
  • Step 4: 测试+提交

Task 11: 固件可控工具链

Files:

  • Create: tools/fw_info.py, tools/fw_pack.py, tests/test_fw.py

  • Step 1: 失败测试：解析原始镜像头字段与校验；重打包字节级一致

  • Step 2: 实现 fw_info（解析/校验）与 fw_pack（修改后重算校验生成可烧录镜像）

  • Step 3: SUOTA 流程写入 docs/firmware-analysis.md（服务 UUID、握手、分块、CRC）

  • Step 4: 全绿提交；G4 门禁检查

Task 12: 最终验收

  • Step 1: 断网环境跑通 CLI 全部命令（除 apt/pip 外）→ G5
  • Step 2: 写 README.md（安装/使用/离线说明）与 docs/architecture.md 终稿
  • Step 3: 对照任务说明三条目标逐项验收，更新 PROGRESS.md，提交

Self-Review 记录

  • 规格覆盖：任务说明目标1→P1；目标2→P2+P3-Task10；目标3→P1-Task4+P3-Task11。✔
  • 已知风险：真机不在手时 Task 9 降级为协议仿真测试（以 APK/Web 证据为准），在 PROGRESS.md 显式标注。
  • 占位符扫描：无 TBD/TODO。
Reference in new issue View Git Blame Copy Permalink