From 9b7d8322a0c6588ddb1ee1bdbb3225622f0642f0 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 26 Aug 2026 10:37:48 +0800 Subject: [PATCH] =?UTF-8?q?Update=20README:=20=E9=A1=B9=E7=9B=AE=E7=BA=A7?= =?UTF-8?q?=E6=80=BB=E8=A7=88=20+=20=E6=9E=B6=E6=9E=84=20+=20=E6=9E=84?= =?UTF-8?q?=E5=BB=BA=E9=83=A8=E7=BD=B2=20+=20=E8=B8=A9=E5=9D=91=E9=80=9F?= =?UTF-8?q?=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容: - 项目组成与架构图(眼镜端 + 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 / 镜像模式 / 加密) --- README.MD | 250 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 198 insertions(+), 52 deletions(-) diff --git a/README.MD b/README.MD index 5e3f03b..068bd6b 100644 --- a/README.MD +++ b/README.MD @@ -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 \ No newline at end of file +``` +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://: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/`