From bed8973551c68d6714e57bb8b23c6635dc881e9c Mon Sep 17 00:00:00 2001
From: agent <agent@local>
Date: Fri, 24 Jul 2026 11:27:39 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20architecture.md=20+=20protocol.md=20?=
 =?UTF-8?q?=E4=BA=92=E8=AF=81=E6=A0=87=E6=B3=A8=E4=B8=8E=20SUOTA=20?=
 =?UTF-8?q?=E7=AB=A0=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture.md | 48 ++++++++++++++++++++++++++++++++++++++++++++
 docs/protocol.md     | 23 +++++++++++++++++++--
 2 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..14d86b8
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,48 @@
+# 软硬件架构总述（4.2寸墨水屏设备）
+
+> 证据：docs/protocol.md、analysis/web/protocol-raw.md、analysis/apk/apk-analysis.md、docs/firmware-analysis.md（固件部分）
+
+## 1. 系统全景
+
+```
+┌──────────────┐   BLE GATT   ┌──────────────────────┐   SPI   ┌─────────────┐
+│ 上位机        │ ◄──────────► │ DA14585 (Cortex-M0)   │ ──────► │ 4.2" 墨水屏  │
+│ Web/App/CLI  │              │ 固件 PP_da14585_4.2   │         │ 400x300 BWR │
+└──────────────┘              └──────────────────────┘         └─────────────┘
+```
+
+- **SoC**：Dialog DA14585（ARM Cortex-M0，96KB SysRAM @0x07FC0000，外置 SPI Flash 存固件与图片）
+- **屏**：4.2" 400×300 黑/白/红三色电子纸（1bpp 双平面：bw + red）
+- **广播名**：`NRF-XXXXXX`（固件内模板字符串，地址后缀填充）
+
+## 2. 软件生态（厂商）
+
+| 组件 | 技术 | 云依赖 |
+|---|---|---|
+| Web 上位机 mspppclock.tech | Web Bluetooth JS | 激活 key_generator.php、固件 file_down.php（qicp.vip:8889） |
+| Android App client-qbsg | Kotlin Compose Multiplatform + Rust native | qbsg.top 全家桶（激活/固件/字体/图库/社区/账号） |
+| 固件 PP_da14585_4.2 | Dialog SDK（ble_app_profile 衍生） | 无（WiFi 天气功能经手机中继） |
+
+两代协议并存：本设备固件属"平平"家族（Web 协议）；APK 另支持"扫地/轻舞/时光"家族（帧格式分叉，见 apk-analysis §g）。
+
+## 3. BLE 协议架构（本设备）
+
+双通道：
+- **EPD 通道**（service 13187b10…/char 4b646063…）：图像块（`03|04`+`ff|00`+2B偏移+240B）、刷屏 `00xx/01`、小图结束 `AA`
+- **RXTX 通道**（service 00001f10/char 00001f1f）：全部控制命令（dd 时间、e1xx 模式、EF 族、FB/e901/EA0x、倒计时族、E2 提交）+ notify（设备 ID 应答）
+- **SUOTA**（service 0000fef5 + 5 自定义 UUID）：固件升级（protocol.md §9）
+
+## 4. 图像数据流
+
+图片 → 调整（亮度/对比度/饱和度）→ 抖动量化（6 算法 × 黑白/三色）→
+1bpp MSB-first 行主序双平面（各 15000B）→ 240B 块 ×63×2 → `01` 刷新上屏。
+
+## 5. 本项目交付物在架构中的位置
+
+| 交付物 | 替代的厂商组件 | 去云效果 |
+|---|---|---|
+| `src/ppclock` CLI | Web 上位机 + App 全部设备功能 | 零网络（仅 BLE） |
+| `tools/fw*.py` | file_down.php 固件分发 | 本地解析/修改/重打包 |
+| `ppclock ota` | App 的 SUOTA 客户端 | 本地固件升级 |
+
+详见 docs/protocol.md（协议规范）与 docs/firmware-analysis.md（固件 internals）。
diff --git a/docs/protocol.md b/docs/protocol.md
index a6617ef..4dd895a 100644
--- a/docs/protocol.md
+++ b/docs/protocol.md
@@ -1,7 +1,10 @@
 # BLE 协议规范（4.2寸墨水屏设备 · 实现标准）
 
 > 状态：**单一事实来源**。实现 `src/ppclock` 以本文件为准。
-> 证据来源：`analysis/web/protocol-raw.md`（Web JS），APK/固件互证结果以"互证"标注；未互证项以 ⚠ 标注。
+> 证据来源：`analysis/web/protocol-raw.md`（Web JS）+ `analysis/apk/apk-analysis.md`（APK 反编译互证）。
+> **互证结论**：GATT UUID、NRF- 前缀、240B 分块、ff/00 平面码、dd 时间帧、e2 收尾、e100/e101/e102 模式族、倒计时 04/0n/990/ff00/ffff 帧、6 种抖动（Bayer 矩阵逐值一致）、红色判定、灰度系数 —— 三线一致。
+> Web 独有（APK 未实现）：WiFi 配置、EFEF 取设备 ID、2300/2301、14/15、e3/e4/e5、E6、FB、e901/EA000、EA0x —— 本规范以 Web 证据为准。
+> APK 独有：`$IMG(0,0)`、8000/8001 图像起始帧（属扫地/轻舞固件家族分叉，本设备不适用）。
 
 ## 1. 设备与 GATT
 
@@ -134,11 +137,27 @@ ASCII UTF-8 直发：`WIFI_SSID:{ssid};WIFI_PASS:{pass};CITY:{城市代码}`（
 | 云依赖 | 本地化方案 |
 |---|---|
 | key_generator.php 激活码 | 分析固件校验逻辑（见 docs/firmware-analysis.md），本地实现算法或固件补丁绕过 ⚠待固件分析 |
-| file_down.php 固件下载 | 固件已本地存档 app/ |
+| file_down.php 固件下载 | 固件已本地存档 app/；SUOTA 由 `ppclock ota` 实现（§9） |
 | qbsg.top 自助激活 | 同上激活方案 |
 | 天气（CITY 代码） | 本地化=不依赖天气；CLI 提供 `wifi-config` 透传 |
 | qrcodejs CDN（模板用） | CLI 用本地 qrcode 库 |
 
+## 9. SUOTA 固件升级（证据：APK §e）
+
+| 项 | 值 |
+|---|---|
+| Service | `0000fef5-0000-1000-8000-00805f9b34fb` |
+| SERV_STATUS（notify） | `64b4e8b5-0de5-401b-a21d-acc8db3b913a` |
+| MEM_DEV | `8082caa8-41a6-4021-91c6-56f9b954cc34` |
+| GPIO_MAP | `724249f0-5ec3-4b5f-8804-42345af08651` |
+| PATCH_DATA（自定义映射） | `457871e8-d516-4ca1-9116-57d0b17b9cb2` |
+| PATCH_LEN（自定义映射） | `9d84b9a3-000c-49d8-9183-855b673fda31` |
+
+流程：MEM_DEV←`{00,00,00,13}`（SPI Flash）→ GPIO_MAP←`{00,00,06,05}` →
+镜像+尾 1B XOR 校验 → 240B 块（PATCH_LEN 2B LE + 20B 无响应写块 + 等 SERV_STATUS==2）→
+MEM_DEV←`{00,00,00,FE}` → 等 ==2 → `{00,00,00,FD}` 重启。
+状态码：2=成功，3-9/17-22/0xFFFF/0xFFFE=各类错误（见 ota.py STATUS_ERRORS）。
+
 ## 8. 测试向量（实现前必须写入 tests/）
 
 > 来源：analysis/web/protocol-raw.md 各节；标 ⚠ 的待 APK/固件互证确认。