Files
admin 9b7d8322a0 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 / 镜像模式 / 加密)
2026-08-26 10:37:48 +08:00

10 KiB
Raw Permalink Blame History

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)

cd glass-mouse/android
./gradlew assembleDebug --no-daemon
# 产物: glass-mouse/android/app/build/outputs/apk/debug/app-debug.apk

安装: 把 APK 拷到 Mac 共享目录,启动 HTTP server,在眼镜浏览器扫码下载并安装(覆盖安装保留数据)。

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+)

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)

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 桥接调试(走同一套命令)

cd glass-mouse/scripts
python3 ble_proxy.py  # 命令行收发,代理到 WebSocket / 蓝牙

5.3 扫局域网找眼镜 IP

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 扫描

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/