新增内容: - 项目组成与架构图(眼镜端 + 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 / 镜像模式 / 加密)
203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
# GlassMouse + GlassRemote — INMO Air3 智能眼镜遥控项目
|
||
|
||
> 在 INMO Air3 眼镜端装原生接收 App,iPhone 用 BLE 直连遥控 + 投屏;Mac 上 PPT 宏把演讲备注推到眼镜全屏显示。
|
||
> 避开官方「仅 Android 手机伴侣可做鼠标 / 投屏」限制。无需 root,无需 Mac 长期在线。
|
||
|
||
---
|
||
|
||
## 1. 项目组成
|
||
|
||
```
|
||
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/`
|