Romonaga/PixyPilot

# PixyPilot PixyPilot 是一款专为 EMEET PIXY AI PTZ 摄像头打造的开源 Linux 控制面板。 它提供了 EMEET Studio 的 Linux 替代方案，支持 Ubuntu 24.04+、PTZ 控制、摄像头预设、AI 追踪控制、视频预览、录制、原生 V4L2/HID 集成、UVC 扩展诊断，以及用于逆向工程的 Windows USBPcap 抓包导入功能。 关键词：EMEET PIXY Linux, EMEET PIXY Ubuntu, PTZ 摄像头控制, EMEET Studio 替代方案, Linux 摄像头控制, Home Assistant PTZ 摄像头, Home Assistant 摄像头控制。 ## 截图    目前的实现侧重于已确认的 Linux 控制路径： - 枚举摄像头设备 - 枚举 V4L2 控制项 - 枚举 V4L2 视频格式 - 将控制项公开为 JSON - 通过原生 V4L2 ioctls 验证控制项并设置值 - 通过原生 V4L2 ioctls 切换视频格式 - 预览选定的摄像头流 - 将选定的流录制到本地磁盘 - 检测 Linux video/HID 热插拔事件，并在连接或移除摄像头时刷新 UI - 保存 HID 和 UVC 诊断快照以进行关联分析 - 导入 Windows USBPcap 的 `.pcap` / `.pcapng` 抓包文件，并附带操作笔记和伴生元数据 - 渲染驾驶舱风格的 React UI，用于 PTZ、图像、对焦和曝光控制 厂商特定的 Pixy HID 路径被隔离在其独立的 provider 中，目前涵盖已解码的智能控制、方向/矢量 PTZ 移动、镜像/旋转、测光以及原生 PTZ 预设的保存/加载。原始的 UVC 扩展单元 (extension-unit) 功能记录在 `PIXY_NOTES.md` 中，在其选择器被安全解码之前，将保持只读状态。 当 PixyPilot 可以从局域网内的 Windows 机器访问时，可以通过 `Windows Capture Inbox` 面板上传 Windows USBPcap 文件。上传的抓包文件会连同伴生元数据一起存储在 `pcaps/imports/` 目录下，以用于关联分析。 面向其他 Linux 用户的逆向工程发现收集在 [docs/EMEET_PIXY_REVERSE_ENGINEERING.md](docs/EMEET_PIXY_REVERSE_ENGINEERING.md) 中。抓包文件索引、HID 报告布局以及已确认的命令目录位于 [docs/EMEET_PIXY_HID_REFERENCE.md](docs/EMEET_PIXY_HID_REFERENCE.md)。UVC 扩展单元工作流程记录在 [docs/UVC_EXTENSION_CORRELATION.md](docs/UVC_EXTENSION_CORRELATION.md) 中。Home Assistant 集成计划位于 [docs/HOME_ASSISTANT.md](docs/HOME_ASSISTANT.md)，托盘应用说明位于 [docs/TRAY_APP.md](docs/TRAY_APP.md)，未来的想法追踪于 [docs/ROADMAP.md](docs/ROADMAP.md)。 ## 致谢 PixyPilot 建立在 `rm1138` 发布的公开 EMEET PIXY 逆向工程研究基础之上： - https://gist.github.com/rm1138/ef132c3a39f3c1effabf6354e2eca965 在项目初期，这是我们能找到的唯一公开的、专注于 Linux 的 EMEET PIXY 控制参考资料，它帮助确认了设备实用的控制路径和 HID 报告结构。 PixyPilot 还与 `LarsArtmann/emeet-pixyd` 进行了交叉验证： - https://github.com/LarsArtmann/emeet-pixyd 该项目独立确认了相同的核心追踪/隐私、手势和音频 HID 命令族。它还帮助验证了只读 HID 状态查询的实用性，以及某些 HID 命令所需的较长的 config-to-commit 时间。PixyPilot 目前的实现还包括本仓库中开发的额外本地测试、来自 EMEET Studio 的数据包抓取、原生 V4L2 ioctl 研究以及 UI/应用程序代码。 PixyPilot 还与 `RoseWaveStudio/PixyBar` 进行了交叉验证： - https://github.com/RoseWaveStudio/PixyBar 该项目是一个原生的 macOS 菜单栏控制器和 `pixyctl` HID 助手。它帮助确认了目标追踪模式、基于角度的 PTZ 移动/居中命令、响应组掩码，以及一个实用说明：仅当其他应用打开视频流时，AI 追踪才会明显地进行跟随。 PixyPilot 还与 `nick0413/Emeet_pixy_for_linux` 进行了交叉验证： - https://github.com/nick0413/Emeet_pixy_for_linux 该项目独立确认了标准的 V4L2 与厂商 HID 分离的方案。它虽然没有解码额外的 UVC 扩展选择器，但其 UI 进一步印证了诸如曝光、白平衡和对焦等依赖控制项需要明显的自动/手动解锁操作。 ## 运行应用 ``` ./tools/run-pixypilot.sh ``` 打开 `http://127.0.0.1:8000`。 这是正常用户模式：一条命令和一个本地地址。首次运行会创建 `backend/.venv`，安装后端依赖，安装前端包，并构建 UI。随后 FastAPI 将通过同一个端口同时提供 API 和 React 应用的服务。 ## 配置 普通用户应编辑 `config/pixypilot.yaml`。 ``` server: host: 127.0.0.1 port: 8000 storage: presets: config/presets.yaml recordings: recordings safety: start_in_privacy: true ``` 应用还会在“运行时配置 (Runtime Config)”面板中显示当前使用的配置文件、存储路径和本地 URL。更改主机和端口需要重启 PixyPilot。更多详细信息请参见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。 要直接从 Windows 上传抓包文件，请将 PixyPilot 绑定到您的局域网地址： ``` server: host: 0.0.0.0 port: 8000 ``` 然后从 Windows 打开 `http://:8000`，并使用 `Windows Capture Inbox` 面板。在启用身份验证之前，请仅限局域网内使用。 ## 开发者模式 开发者模式仅适用于在开发 PixyPilot 本身时的前端热重载。普通用户不需要使用此模式。 终端 1： ``` cd backend python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" pixypilot-api ``` 终端 2： ``` cd frontend npm install npm run dev ``` 打开 `http://127.0.0.1:5173` 即可使用 Vite 热重载 UI。它会将 API 请求代理到 `http://127.0.0.1:8000`。 标准的 V4L2 设备检查、控制项枚举、格式枚举、控制项写入以及格式切换均使用原生 Linux V4L2 ioctls。MJPG 实时预览同样使用原生 V4L2 mmap 捕获。 ## 控制预设 图像、对焦和曝光面板可以保存命名的本地预设。预设存储在 `config/presets.yaml` 中，由于这些值特定于用户/工作区，该文件会被 git 忽略。 可以在 `config/pixypilot.yaml` 中的 `storage.presets` 下设置不同的预设文件。 ## 视频预览与录制 PixyPilot 通过后端将实时的监控画面以 MJPEG 格式进行流式传输。 - MJPG 预览使用原生 V4L2 mmap 捕获，且不会通过 shell 调用 `ffmpeg`。 - 非 MJPG 预览（例如 YUYV）仍会回退到 `ffmpeg`，因为这些原始帧需要进行 JPEG 编码才能供浏览器流式传输。 - 录制依然使用 `ffmpeg`，并默认将文件写入 `recordings/` 目录下。 `recordings/` 目录会被 git 忽略，因为摄像头的录像文件既大又涉及隐私。 可以在 `config/pixypilot.yaml` 中的 `storage.recordings` 下设置不同的录制目录。 ## HID 权限 在实验性的智能控制功能生效之前，PixyPilot 需要对 PIXY hidraw 节点的写入权限。请安装一次附带的 udev 规则： ``` sudo install -m 0644 deploy/udev/70-pixypilot-hid.rules /etc/udev/rules.d/70-pixypilot-hid.rules sudo udevadm control --reload-rules sudo udevadm trigger --subsystem-match=hidraw ``` 如果当前的 `/dev/hidrawN` 节点没有立即更新，请拔下摄像头并重新连接。正常工作的节点权限应显示为 `root plugdev` 以及 `crw-rw----`，并且 `/api/pixy-hid/status` 应报告 `readable: true` 和 `writable: true`。 ## 测试 ``` cd backend source .venv/bin/activate pytest cd frontend npm test ```

标签：PTZ, React, Syscalls, V4L2, 协议分析, 摄像头控制, 权限提升, 硬件控制, 自动化攻击, 逆向工具