From dd218addce31b289ae45567c3694913c6672fc2a Mon Sep 17 00:00:00 2001
From: "evan.liu" <583229071@qq.com>
Date: Sat, 5 Sep 2026 10:07:14 +0800
Subject: [PATCH] tools: add requirements-ble.txt for the (git-ignored)
 .venv-ble

The venv is a per-machine artifact and stays out of git; the bats
auto-create it on first run but only installed bleak - pyserial
(required by UART OTA) was missing on a fresh machine. Both bats now
install from requirements-ble.txt (bleak==3.0.2, pyserial==3.5).
---
 AGENTS.md                  | 2 +-
 tools/ble_cli.bat          | 2 +-
 tools/ble_ota.bat          | 2 +-
 tools/requirements-ble.txt | 2 ++
 4 files changed, 5 insertions(+), 3 deletions(-)
 create mode 100644 tools/requirements-ble.txt

diff --git a/AGENTS.md b/AGENTS.md
index 7b73d30..5d7cc31 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -151,7 +151,7 @@ mcm-ddc-ble/
 - `merge_image.py` — 纯 Python 无三方依赖；合并 boot+bootsetting(缺省记录，脚本生成)+APP 为整片 hex/bin，同时产出 `_ota.bin`/`_ota.json`（bank1 载荷）；`--ota-app2` 追加 bank2 载荷 `_ota_app2.bin/.json`；`--app2 <bin> --with-appdata` 生成双 bank 整包（make_dual_package.bat 使用）；自动从 `app_version.h` 取 `APP_FW_VERSION_NUM` 写入清单（含 `target_bank` 字段）
 - `make_package.bat` / `flash_package.bat` — 一键出包 / NSpyocd 整片烧录（脚本会自动找 Python312 全路径，本机 `python` 可能是商店占位 stub）
 - `make_dual_package.bat` — 双 APP 整包（Boot+bootsetting 双 bank+APP_DATA+APP1+APP2，APP2 升一版链接 0x01024000），用于 appsw 切换测试
-- `ble_cli_test.py` + `ble_cli.bat` — PC 端 bleak 蓝牙 CLI 测试客户端（帧协议模式 + `-rw` 读写特征模式，交互模式 `-i`，venv 在 `tools/.venv-ble`，首次运行 bat 自动创建）
+- `ble_cli_test.py` + `ble_cli.bat` — PC 端 bleak 蓝牙 CLI 测试客户端（帧协议模式 + `-rw` 读写特征模式，交互模式 `-i`，venv 在 `tools/.venv-ble`，不入库；首次运行 bat 按 `tools/requirements-ble.txt`（bleak+pyserial）自动创建）
 - `ble_ota_update.py` + `ble_ota.bat` — BLE OTA 升级器（解析单文件升级包 `mothercup_ble_ota.bin`、按 CUR_BANK 选对侧 bank 载荷、经 OTA 特征 `...e0005` 逐帧锁步、复位检测+重连校验；`--uart COMx` 走串口二进制模式：握手标记进入/ABORT 退出；V1.00.24 起默认流式（8KB 窗口+扇区 ack+go-back-N），`--lockstep` 或旧固件自动回退锁步）。**BLE 与 UART 双通道均已实测通过（§42/§44），流式见 §47**
 - `ble_temp_watch.py` — 温度监测小工具
 
diff --git a/tools/ble_cli.bat b/tools/ble_cli.bat
index b157c81..1bd6d4a 100644
--- a/tools/ble_cli.bat
+++ b/tools/ble_cli.bat
@@ -24,7 +24,7 @@ if not exist "%PYEXE%" (
     )
     if not defined PYREAL set PYREAL=python
     %PYREAL% -m venv "%TOOLS%.venv-ble" || goto :fail
-    "%PYEXE%" -m pip install --quiet bleak || goto :fail
+    "%PYEXE%" -m pip install --quiet -r "%TOOLS%requirements-ble.txt" || goto :fail
 )
 
 set MODE=-rw
diff --git a/tools/ble_ota.bat b/tools/ble_ota.bat
index 28523b6..8b2b8fe 100644
--- a/tools/ble_ota.bat
+++ b/tools/ble_ota.bat
@@ -24,7 +24,7 @@ if not exist "%PYEXE%" (
     )
     if not defined PYREAL set PYREAL=python
     %PYREAL% -m venv "%TOOLS%.venv-ble" || goto :fail
-    "%PYEXE%" -m pip install --quiet bleak || goto :fail
+    "%PYEXE%" -m pip install --quiet -r "%TOOLS%requirements-ble.txt" || goto :fail
 )
 
 "%PYEXE%" "%TOOLS%ble_ota_update.py" %1 %2 %3
diff --git a/tools/requirements-ble.txt b/tools/requirements-ble.txt
new file mode 100644
index 0000000..002cd30
--- /dev/null
+++ b/tools/requirements-ble.txt
@@ -0,0 +1,2 @@
+bleak==3.0.2
+pyserial==3.5