fmontes/insta360-link-cli

# insta360-link-cli [](https://github.com/fmontes/insta360-link-cli/actions/workflows/build.yml) 一个用于控制 **Insta360 Link 2** 摄像头的微型 macOS CLI —— 可以使云台回中、进行平移/俯仰/缩放，以及切换 AI 目标追踪 —— **无需打开缓慢的官方应用**。 ``` linkcam # recenter the gimbal (pan=0, tilt=0) linkcam ai # toggle AI subject tracking on/off linkcam status # show pan/tilt, zoom, and tracking state ``` 甚至不需要运行官方应用。 ## 安装说明 需要 macOS（Apple Silicon 或 Intel —— 这些二进制文件是通用的）以及一台 Insta360 Link 2。 ``` git clone https://github.com/fmontes/insta360-link-cli.git cd insta360-link-cli ./install.sh # symlinks `linkcam` onto your PATH linkcam status ``` 已包含预编译的二进制文件，因此无需编译。（如需自行编译，请参阅[构建说明](#building)。） ## 使用方法 ``` linkcam # center the gimbal (pan=0, tilt=0) [default] linkcam status # show pan/tilt, zoom, and ai-tracking state linkcam ai # toggle AI subject tracking linkcam ai on # force AI tracking on linkcam ai off # force AI tracking off linkcam zoom 150 # set zoom (100 = 1x) linkcam pan -30000 # pan only (tilt unchanged) linkcam tilt 20000 # tilt only (pan unchanged) linkcam set 0 0 # set pan and tilt explicitly ``` 应对 AI 漂移问题的实用组合：`linkcam ai off` 可停止追踪并防止摄像头偏移，随后使用 `linkcam` 使其回中。 ## 工作原理 Link 2 是一台标准的 **UVC** (USB Video Class) 摄像头。 - **云台 / 缩放**使用*标准* UVC 控制。回中只需将 **PanTilt Absolute** 设置为其默认值 `pan=0, tilt=0`。 - **AI 追踪** *并非*标准功能 —— 这是一个专有的 **Extension Unit (XU)** 命令，必须对其进行逆向工程（见下文）。 在 macOS 上，你**无法**使用 libusb/pyusb 来驱动它们：系统摄像头驱动程序会占用 USB 接口并且不会释放它（`detach_kernel_driver` → *Access denied*）。诀窍是通过 **IOKit** 发出 UVC 控制传输，它可以与摄像头驱动程序*协同*工作。本项目通过两个小型的 Objective-C 辅助工具实现了这一点： - **`uvc-util`** —— [Jeffrey Frey 的工具](https://github.com/jtfrey/uvc-util) (MIT)，用于标准控制。 - **`xu-probe`** —— 为本项目编写的一个小工具，通过 unit-id + selector 添加了*原始* XU 的 get/set/scan 功能，并复用了 uvc-util 的 IOKit 机制。 ### AI 追踪逆向工程 AI 追踪并未作为标准控制公开，因此其开启/关闭命令是通过经验性测试发现的： 1. 在追踪**关闭**的状态下，**扫描**所有 XU 控制（在所有 3 个 extension unit 上对所有 selector 执行 `GET_CUR`）。 2. 在官方应用中**切换**追踪开启，然后**重新扫描**并执行 **diff**。 3. **过滤掉噪声** —— 某些寄存器（云台位置、曝光）会自行发生漂移，因此通过第二次空闲扫描可以识别并移除它们。 4. 剩下的是一个稳定的字节，它会随着开关状态在 `00`↔`01` 之间精确翻转，随后通过写入该字节并观察摄像头追踪情况来**确认**。 **结果：** USB 描述符中的三个供应商 extension unit： | Unit | GUID | 作用 | |------|------|------| | 9 | `FAF1672D-B71B-4793-8C91-7B1C9B7F95F8` | 设备信息 / 状态 | | 10 | `E307E649-4618-A3FF-82FC-2D8B5F216773` | (图像/AE 参数) | | 11 | `A8BD5DF2-1A98-474E-8DD0-D92672D194FA` | **AI 功能** | 使用原始工具进一步探索： ``` bin/xu-probe -V 0x2e1a:0x4c04 scan 11 # dump all controls on unit 11 bin/xu-probe -V 0x2e1a:0x4c04 get 11 0x02 1 # read AI-tracking state bin/xu-probe -V 0x2e1a:0x4c04 set 11 0x02 01 # tracking on ``` ## 构建说明 仅需 macOS **Command Line Tools**（不需要完整的 Xcode）： ``` make # builds bin/uvc-util and bin/xu-probe from src/ ``` uvc-util 的源代码属于 MRC 时代的 Objective-C，因此构建时使用了 `-fno-objc-arc`。 ## 项目布局 ``` linkcam the CLI (bash) bin/ prebuilt arm64 helpers (uvc-util, xu-probe) src/xu-probe.m raw XU tool (this project) src/vendor/ uvc-util sources, MIT (jtfrey/uvc-util) Makefile builds the helpers install.sh symlinks linkcam onto your PATH ``` ## 兼容性与注意事项 - 预编译的二进制文件是**通用的** (arm64 + x86_64)，可在 Apple Silicon 和 Intel Mac 上运行。 - 已在 **Insta360 Link 2** (USB `0x2e1a:0x4c04`) 上测试通过。其他 Insta360 摄像头可能使用不同的 XU selector —— 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何使用 `xu-probe scan` 查找它们。 - 基于观察到的行为进行逆向工程；与 Insta360 没有关联或受其认可。使用风险自负。 ## 致谢 - [uvc-util](https://github.com/jtfrey/uvc-util) 作者 Jeffrey Frey (MIT) —— 这是本项目构建所依赖的 IOKit UVC 控制基础。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。内置的 uvc-util 同样遵循 MIT 协议 ([src/vendor/LICENSE.uvc-util](src/vendor/LICENSE.uvc-util)).

标签：CVE监控, UVC, 云资产清单, 应用安全, 摄像头控制, 硬件控制, 逆向工程