dropchop/actionCamController
GitHub: dropchop/actionCamController
通过逆向iSmart DV2应用实现的iCatch V11运动相机Python控制库及Flask Web界面，替代官方App在Linux下完成相机WiFi控制与实时预览。
Stars: 0 | Forks: 0
# actionCamController
一款适用于 **Larkfly A6+** 运动相机的 Linux 控制器（内部 iCatch 产品代码 `V11`，固件版本 20251206），通过逆向工程分析 iSmart DV2 Android 应用及真实设备而开发。用于替代官方应用实现单相机控制，并（最终可以实现，见下文注意事项）协调多台相机同时工作。
本项目的诞生源于发现该相机使用了一种不合规范的 PTP/IP “方言”，其中包含三个未公开的怪异行为。本库将这些细节进行了封装，使得普通的 Python 客户端可以轻松驱动相机。
## 状态
**单相机 WiFi 控制功能已可用。** 基于 `larkfly`（客户端库，包含 23 个单元测试）构建，并提供了一个 Flask web UI 用于实时预览和连拍录制。多相机控制在原则上已可行，但需要将相机接入同一共享网络 —— 有关利弊权衡请参阅 `docs/architecture.md`。
已完成的功能：
- 针对相机的 PTP/IP 会话；协议层的线路格式已完成逆向工程和测试
- 枚举了全部 56 个设备属性，并在关键处进行了命名
- 通过 Flask UI 在浏览器中实现 RTSP 实时预览（约 30 fps）
- 通过属性 `0xD604` 实现视频录制的开始 / 停止 / 连拍
- 通过 FTP 访问文件（`wificam` / `wificam`）
- USB UVC 采集（1080p MJPEG）—— 但相机在 UVC 模式下不会同时录制到 SD 卡，因此这仅用于主机串流
遇到的问题：
- 通过 PTP 进行照片拍摄 —— `InitiateCapture` 返回正常但未能生成 JPG 文件。临时替代方案：使用相机本身的物理快门按钮。
- 将多台相机连接至同一个共享 WiFi（STATION 模式）—— 相机端的协议是 Realtek SmartConfig（UDP 广播，AES 加密）。我们已经掌握了默认的 AES 密钥和多播目标地址，但编码算法仍需进一步研究。请参阅 `docs/findings.md`。
## 安装
```
git clone https://github.com/dropchop/actionCamController.git
cd actionCamController
# 仅 Library（核心为纯 stdlib）：
pip install -e .
# Library + web UI 依赖：
pip install -e '.[webui]'
# Library + capture-tool 依赖（用于 pcap 解密的 cryptography）：
pip install -e '.[capture]'
# 全部：
pip install -e '.[all]'
```
运行环境要求 Python 3.10+。
## 快速开始
```
# 与位于 192.168.1.1（出厂默认）的相机进行通信。
# `bind` 是本地源 IP —— 仅当有多个接口
# 共享 192.168.1.0/24 子网时才需要。
from larkfly import Camera
with Camera('192.168.1.1', bind='192.168.1.10') as cam:
info = cam.device_info()
print(info['operations_supported'])
# Read a property
print(cam.get_prop_value(0x501E)) # 'V11' — ProductName
print(cam.get_prop_value(0x501F)) # '20251206' — FwVersion
# Record video for 3 seconds (mode-toggle paradigm)
cam.start_recording() # sets D604=17 (VIDEO_ON)
time.sleep(3)
cam.stop_recording() # sets D604=1 (VIDEO_OFF)
# → .MOV file appears in the camera's /VIDEO/ via FTP
# Browse / download
for handle in cam.list_objects():
print(cam.object_info(handle))
```
## 仓库结构
```
actionCamController/
├── larkfly/ the Python client library (protocol + high-level Camera)
├── webui/ Flask multi-camera controller (preview + burst record)
├── tools/ operational utilities (probe, pcap decryption, monitor capture)
├── analyses/ one-shot RE scripts + their outputs (data/*.json)
├── tests/ unit tests for the protocol codec
├── examples/ library usage demos
├── docs/ findings.md, architecture.md, archived chronology
└── apk-analysis/ APK + decompile artifacts (gitignored — large + copyrighted)
```
## 运行 Web UI
```
# 单相机（默认 IP）：
python3 webui/app.py --bind 192.168.1.10
# 然后打开 http://127.0.0.1:5000
# 混合源 — 一台 WiFi 相机 + 一台 USB UVC 相机：
python3 webui/app.py \
--camera 192.168.1.1 --bind 192.168.1.10 \
--usb /dev/video0
```
有关 API 端点请参阅 `webui/README.md`，有关多相机部署方案请参阅 `docs/architecture.md`。
## docs/ 目录包含什么
| 文件 | 何时阅读 |
| --- | --- |
| `docs/findings.md` | **从这里开始。** 当前状态参考：协议怪异行为、操作码、录制范式以及多相机状态。 |
| `docs/architecture.md` | 决定如何部署 4 台相机（USB UVC 对比 WiFi 多网卡 对比 STATION）。 |
| `docs/archive/investigation-log.md` | 完整的按时间顺序记录的逆向工程故事，包括走通的死胡同。 |
| `docs/archive/original-protocol-notes.md` | 调查前的假设（大部分已被推翻）。 |
## 致谢
- libgphoto2 的 `camlibs/ptp2/ptpip.c` —— 简洁的参考实现，解决了 packet-type-11-vs-12 规范的歧义问题。
- [`clerie/rollei-AC-420`](https://github.com/clerie/rollei-AC-420) —— 相同的 iCatch 硬件系列；早期确认了 RTSP + FTP 的路径。
- [`Linouth/iCatch-V50-Playground`](https://github.com/Linouth/iCatch-V50-Playground) —— 相关芯片组的调试笔记。
## 许可证
MIT —— 详见 `LICENSE`。
标签：AES加密, Flask, iCatch V11, iSmart DV2, Larkfly A6+, PTP/IP协议, Python, RTSP实时预览, SmartConfig, UDP广播, USB UVC, 云资产清单, 单反/相机远程控制, 图像抓取, 多媒体开发, 开源硬件, 插件系统, 文件传输FTP, 无后门, 物联网控制, 硬件黑客, 网络协议分析, 网络摄像机, 视频录制, 运动相机控制, 逆向工具, 逆向工程