Update README: 项目级总览 + 架构 + 构建部署 + 踩坑速查

新增内容:
- 项目组成与架构图(眼镜端 + iPhone 端 + Mac PPT 宏三条路径)
- BLE GATT / HTTP 关键协议常量集中表
- 构建部署步骤(Android Gradle + iOS Xcode + HTTP 分发)
- 踩坑速查:
  * iPhone 7 天签名过期 + deploy.sh 重签流程
  * 锁屏/账号掉线/provisioning 缓存
  * iOS 26 stale GATT handle 现象(实验结论 + 撤回 BootReceiver 的原因)
  * 眼镜端权限矩阵 + 无障碍重置
  * INMO Air3 ROM 限制
  * Mac 工具链缺失(adb/libimobiledevice 替代方案)
  * 编译环境速查表(IP / Xcode / Android / Python / 端口 / Gitea)
- 调试速查(devicectl 拉 iPhone 日志 / Mac BLE 桥接 / 局域网扫描)
- 路线图(TestFlight / SurfaceView / 镜像模式 / 加密)
This commit is contained in:
admin committed 2026-08-26 10:37:48 +08:00
1 parent 2840e82685
commit 9b7d8322a0
1 file changed
+198 -52
+198 -52
View File
@@ -1,56 +1,202 @@
这是一个通过 websockect 将ppt演示时备注信息推送到智能眼镜的程序
# GlassMouse + GlassRemote — INMO Air3 智能眼镜遥控项目
# 对应ppt脚本示例
' 声明全局变量:接口地址、推送)
Dim apiUrl As String
> 在 INMO Air3 眼镜端装原生接收 App,iPhone 用 BLE 直连遥控 + 投屏;Mac 上 PPT 宏把演讲备注推到眼镜全屏显示。
> 避开官方「仅 Android 手机伴侣可做鼠标 / 投屏」限制。无需 root,无需 Mac 长期在线。
Sub OnSlideShowPageChange()
' 获取当前幻灯片编号
Dim currentSlide As Integer
currentSlide = ActivePresentation.SlideShowWindow.View.CurrentShowPosition
remarkText = ActivePresentation.SlideShowWindow.View.Slide.NotesPage.Shapes.Placeholders(2).TextFrame.TextRange.Text
---
' 显示提醒(例如:显示当前页数)
' MsgBox "现在是第 " & currentSlide & " 页是第 " & remarkText & " 页"
## 1. 项目组成
Dim postData As String
Dim curlCommand As String
Dim escapedPostData As String
apiUrl = "http://192.168.1.18/ppt/remark"
' ========== 关键修正:分步转义特殊字符 ==========
' 1. 构造原始JSON(先不转义,统一处理)
postData = "{""pageNum"":" & currentSlide & ",""remark"":""" & remarkText & """}"
'apiUrl = "https://rest-hz.goeasy.io/v2/pubsub/publish"
'postData = "{""appkey"":""BC-671cf99a73a942748b856a6bd0d5ea7e"",""channel"":""test_channel"",""content"":""" & remarkText & """}"
' 2. 针对Mac终端的转义规则:
' - 先替换JSON中的双引号为 \\"" (终端需要双层转义)
' - 避免直接拼接空格,用单引号包裹整个-d参数
escapedPostData = Replace(postData, """", "\""")
escapedApiUrl = apiUrl ' 地址无特殊字符可直接用,若有空格需额外转义
' 3. 构造正确的curl命令(核心修正)
' /bin/bash -c 后必须用单引号包裹整个命令,内部双引号双层转义
curlCommand = "/bin/bash -c '" & _
"curl --silent --show-error -X POST " & _
"-H ""Content-Type: application/json;charset=utf-8"" " & _
"-d """ & escapedPostData & """ " & _
apiUrl & "'"
' 调试用:弹出构造后的curl命令,可复制到终端手动测试
'MsgBox "最终curl命令:" & vbCrLf & curlCommand, vbInformation, "调试信息"
' 执行curl命令(Mac下Shell返回值>0代表执行成功,不代表接口返回成功)
Dim shellResult As Double
On Error Resume Next ' 捕获Shell执行错误
shellResult = Shell(curlCommand, vbHide)
On Error GoTo 0
' 验证执行结果
'If shellResult > 0 Then
' MsgBox "curl命令执行成功!请检查Python接口是否接收到数据", vbInformation, "执行成功"
'Else
' MsgBox "curl命令执行失败!请复制上方调试命令到终端手动测试", vbCritical, "执行失败"
' End If
End Sub
```
glass/
├── glass-mouse/ # 眼镜端原生 Kotlin App(前台服务 + 自定义 BLE GATT)
│ ├── android/
│ ├── docs/ # 协议 / BLE 调试指南
│ ├── macros/ # WPS / PowerPoint 宏(POST :8000/ppt/remark)
│ └── scripts/ # Mac 端 BLE 桥接 / 扫描 / 调试工具
│
└── ios/GlassRemote/ # iPhone 原生 SwiftUI App(CoreBluetooth 中心设备)
└── Sources/ # GlassBLEManager + Views (ControlView/CastView/ContentView)
```
子目录 `glass-mouse/README.md`、`ios/GlassRemote/README.md` 有更细节的命令映射和子模块说明,本文件给**项目级总览**。
---
## 2. 架构
```
iPhone (GlassRemote) ──BLE GATT (UUID A9E0ABCD…)──▶ ProxyBleServer ──▶ handleCommand
│ (眼镜端前台服务 MouseService)
│ • 控制指令(光标/点击/返回/主页/拍照) │
│ • 投屏长文本分片(无密码、无需 WiFi) ▼
│ ┌──────────────────────┐
│ │ 悬浮光标 + 文字投屏 │
│ │ 无障碍 GestureDesc 注入 │
│ │ Camera2 拍照 │
│ └──────────────────────┘
│
▼
iOS App UI(触控板 = 光标/真实 touch 滑动;投屏页 = 翻页大字 + 自动滚动)
Mac(WPS/PPT 宏) ──http POST :8000/ppt/remark──▶ HttpRemoteServer ──▶ 自动滚动提词
```
### 关键协议常量(全平台一致)
| 项 | 值 |
|---|---|
| BLE Service UUID | `A9E0ABCD-0000-1000-8000-00805F9B34FB` |
| BLE Write UUID | `A9E0ABCD-0001-1000-8000-00805F9B34FB` |
| BLE Notify UUID | `A9E0ABCD-0002-1000-8000-00805F9B34FB` |
| BLE CCCD | `00002902-0000-1000-8000-00805F9B34FB` |
| HTTP 投屏端口 | `8000` |
| HTTP 投屏路径 | `POST /ppt/remark` body: `{"pageNum":N,"remark":"…"}` |
| 命令 JSON 形状 | 见 `glass-mouse/README.md` / `ios/GlassRemote/README.md` 的命令映射表 |
| 投屏长文本分片 | `_frag=true&seq=N&total=M&data=chunk` JSON object,逐片 `withResponse` |
---
## 3. 构建 & 部署
### 3.1 眼镜端 (Android / INMO Air3)
```bash
cd glass-mouse/android
./gradlew assembleDebug --no-daemon
# 产物: glass-mouse/android/app/build/outputs/apk/debug/app-debug.apk
```
**安装:** 把 APK 拷到 Mac 共享目录,启动 HTTP server,在眼镜浏览器扫码下载并安装(覆盖安装保留数据)。
```bash
cd glass-mouse/../download
python3 -m http.server 18000 --bind 0.0.0.0
# 下载页: http://<Mac LAN IP>:18000/
```
**首次启动:** 眼镜点开 GlassMouse App,授权悬浮窗权限(`SYSTEM_ALERT_WINDOW`),iPhone 即可连接 BLE。
### 3.2 iPhone 端 (iOS 17+)
```bash
cd ios/GlassRemote
bash deploy.sh
# 内部: xcodebuild → xcrun devicectl device install app
```
`deploy.sh` 默认 TEAM=`H2C3YSR973`、UDID=`D469A28E-D29F-54A0-8936-0EA41BA02DA2`(苏苏的 iPhone 12 Pro Max)。Xcode 需登录对应 Apple ID,Provisioning Profile 自动拉取。
### 3.3 拉起完整链路
1. 眼镜打开 GlassMouse App(屏幕显示 BLE 状态 + WiFi IP)
2. iPhone 打开 GlassRemote(自动连接 BLE,顶栏显示状态)
3. 触控板拖动 → 光标跟着移动;按底部「主页 / 返回 / 拍照」按钮 → 眼镜响应
4. Mac 端 PPT 宏会在翻页时自动 `POST http://<眼镜IP>:8000/ppt/remark`,眼镜投屏层自动滚动显示备注
---
## 4. 关键踩坑与注意事项
### 4.1 iPhone BLE 签名过期(每 7 天重签)
- **现象:** 装了 GlassRemote 一周后 iPhone 突然提示「未受信任的开发者」
- **根因:** 免费 Apple ID 的 Team Provisioning Profile 有效期 7 天,过期被系统清
- **解决:** 跑 `bash ios/GlassRemote/deploy.sh` 重签,Xcode 会自动拉新 profile 并装到 iPhone
- **预防:** 把 deploy.sh 加到周历提醒;或升级 $99/年 Apple Developer Program 走 TestFlight(90 天/构建)
### 4.2 iPhone BLE 重连 / 锁屏 / Xcode 账号掉线
- **锁屏阻断:** iPhone 锁屏 → `xcodebuild` 报 `kAMDMobileImageMounterDeviceLocked`,需解锁后才能跑 deploy
- **账号掉线:** Xcode 里 Apple ID 被注销 → `No Accounts` 错,需 `Settings → Accounts → +` 重登
- **stub 缓存:** 装 APK 后 provisioning profile 目录会被清空,跑 deploy 时 Xcode 自动重拉
### 4.3 iOS 26 stale GATT handle(实验结论)
- **现象:** 眼镜 Android 端重启/重装 APK 后,iPhone GlassRemote 出现 `ATT error: handle is invalid (0x01)`,且**`cancelPeripheralConnection + reconnect` 在 iOS 26 上无法强制重建 GATT 数据库快照**,stale handle 自动重试 2 次仍失败
- **缓解:** 手动 `设置 → 蓝牙 → INMO AIR3 5876 → 忽略此设备`,App 内点刷新按钮重新扫描
- **结论:** iOS 26 CoreBluetooth 在 cached peripheral 上的 GATT handle 是 process-level 强缓存,**没有任何代码路径能让 iOS 自动 invalidate**(包括强制 cancel、删除 identifier、重启 App),唯一可靠恢复是用户在系统设置层「忽略此设备」
- **设计影响:** 项目**当前未做开机自启动**(`BootReceiver` 实验已撤回),因为它会引入 stale handle 副作用(每次重启眼镜 iPhone 都要点忽略此设备)。用户每次重启眼镜 → 手动点开一次 App → iPhone 无需任何操作,链路稳定。如果将来要做自启动,需在 iOS 端配套「一键忽略此设备」按钮。
### 4.4 眼镜端关键权限
- `BLUETOOTH_CONNECT` + `BLUETOOTH_ADVERTISE`(Android 12+,用于 BLE GATT)
- `SYSTEM_ALERT_WINDOW`(悬浮光标,首次启动要在系统设置里手动开)
- `CAMERA`(拍照,可拒绝,只影响相机功能)
- `POST_NOTIFICATIONS`(Android 13+,前台服务通知)
- **无障碍(GlassMouseService)** 用于点击 / 返回注入,**可选**;未开启时 iPhone 仍能移动光标,只是点击/返回失效
- **重装 APK 后无障碍会被系统重置关闭**,需在眼镜「设置 → 无障碍 → GlassMouse」重新打开(约 3 秒恢复)
### 4.5 INMO Air3 ROM 限制
- **自启动管理默认禁用第三方**,即使 APK 装了 BOOT_COMPLETED receiver,系统也会拦截(本项目已撤回该方案)
- **通知栏权限可能被禁用**,导致前台服务的通知不显示(对功能不影响,只影响 UX)
- **电源优化激进**,长时挂后台的服务可能被 doze 杀掉。本项目通过 `FOREGROUND_SERVICE_SPECIAL_USE` + 持久通知规避
### 4.6 Mac 工具链缺失
- **`adb` 不在 PATH**:Mac 上没装 Android Studio,没 adb。要看 Android logcat 用 Android Studio 或 `idevicesyslog`(后者对 iOS 26 部分 lockdown 接口不可用,优先用项目里 `HttpRemoteServer` 加诊断 endpoint 的方案)
- **`libimobiledevice` 在 iOS 26 部分失效**:`ideviceinfo` / `idevicesyslog` 等工具在 iOS 26 上报 `ConnectionFailedError (Number 3)`,不可用。**替代方案:用 Xcode 自带的 `devicectl device copy from --domain-type appDataContainer`** 从 iOS App 的 Documents 目录拉文件(本项目 iOS 端 `GlassBLEManager.writeLogToFile` 专门写 `ble_log.txt` 到 App Documents 供此场景使用)
- **`xcrun log show` 在 Claude Code 沙箱里被拦**(`Cannot run while sandboxed`),即使用 `dangerouslyDisableSandbox` 也不行,因为这需要 Full Disk Access
### 4.7 编译环境速查
| 项 | 当前值 |
|---|---|
| Mac IP(苏苏家用 LAN) | `192.168.1.18`(眼镜实际 IP 通常 `192.168.1.193`) |
| Mac Xcode | 26.5 (17F42),SDK iOS 26.5 |
| iPhone | 12 Pro Max (iPhone13,4) iOS 26.6.1 (build 23G83) |
| Android Gradle | 8.14.4,compileSdk 34,minSdk 24,Java 17,Kotlin |
| Android SDK | `~/Library/Android/sdk`,build-tools 34.0.0,aapt 可用 |
| Xcode 管理 Python | 3.13.12(/Users/xs/.workbuddy/binaries/python/versions/3.13.12) |
| HttpRemoteServer 端口 | 8000(投屏) |
| 本地 APK 分发端口 | 18000(python3 -m http.server,download/ 目录) |
| Gitea 仓库 | http://127.0.0.1:13300/ssw/glass(账号 ssw/sswsswssw) |
### 4.8 PPT 宏配置
- **WPS:** 启用宏后,把 `glass-mouse/macros/ppt-remark-macro.bas` 导入 `OnSlideShowPageChange` 事件
- **PowerPoint:** 用 `glass-mouse/macros/ppt-remark-macro-wps.js` 通过 Shell 调 curl
- **目标地址:** 改宏里的 `apiUrl = "http://<眼镜IP>/ppt/remark"`,眼镜 App 屏上会显示当前 WiFi IP 直接抄
---
## 5. 调试速查
### 5.1 拉 iPhone App 日志(ble_log.txt,Mac → devicectl)
```bash
xcrun devicectl device copy from \
--device D469A28E-D29F-54A0-8936-0EA41BA02DA2 \
--domain-type appDataContainer \
--domain-identifier com.glassmouse.GlassRemote \
--source Documents/ble_log.txt \
--destination /tmp/ble_log.txt
```
### 5.2 Mac 端 BLE 桥接调试(走同一套命令)
```bash
cd glass-mouse/scripts
python3 ble_proxy.py # 命令行收发,代理到 WebSocket / 蓝牙
```
### 5.3 扫局域网找眼镜 IP
```bash
for ip in $(seq 1 50); do
ping -c1 -W1 192.168.1.$ip >/dev/null 2>&1 && echo "alive: 192.168.1.$ip"
done
```
### 5.4 BLE 扫描
```bash
cd glass-mouse/scripts
python3 ble_scan.py # 找 INMO AIR3 5876,确认广播
```
---
## 6. 路线图(留白)
- [ ] TestFlight 长期分发(需 $99/年 Apple Developer Program,本项目目前走 7 天重签)
- [ ] 投屏层改成 SurfaceView 渲染(当前 Activity 全屏文字层,翻页大字 + 自动滚动已稳定)
- [ ] 镜像模式(iOS 端分享屏幕 → 眼镜全屏播放,受 iOS 沙箱限制未实现)
- [ ] 加密:WebSocket 走 WSS、BLE 加 PIN 配对(目前 BLE 通道无密码,但 INMO ROM 不让陌生设备配对,实际安全)
---
## 7. 相关链接
- 眼镜端协议详细文档:`glass-mouse/docs/ble_protocol.md`
- 眼镜端 BLE 探测 / 抓包指南:`glass-mouse/docs/ble_probe_guide.md`
- iOS 端命令 / 构建细节:`ios/GlassRemote/README.md`
- 历史踩坑 / 每次重签记录:`.workbuddy/memory/`