PICKLERICK2005/PyKS2

# pyks2 [](https://github.com/PICKLERICK2005/pyks2/actions/workflows/test.yml) [](https://www.python.org/) [](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE) 一个 Python 库和 CLI，用于通过其内置的 WiFi 控制 **Pentax K-S2**。该项目建立在对相机未公开的 HTTP API 进行完整且经硬件验证的逆向工程基础之上。（Web GUI 正在计划中；见下文。） K-S2 拥有一个 WiFi 遥控 API，但 Pentax 从未公开其文档。本项目针对物理相机映射了 K-S2 API 的**整个面**，将其整理为一份详尽的剖析文档，并提供了一个比厂商自带的 Image Sync 应用更轻量、更强大的纯净客户端。 访问网页网站 。 ## 包含内容 ``` pyks2/ the library (camera-only HTTP client, typed models, WS events) ├─ client.py K_S2_WiFi, the API client ├─ models.py typed response models (defensive parsing) ├─ events.py /v1/changes WebSocket client (stdlib, zero-dep) ├─ constants.py endpoints + capability enums ├─ errors.py typed exceptions (errCode-aware) └─ cli.py the command-line interface docs/ the reverse-engineering write-up (GitHub Pages source) ├─ PROTOCOL.md the complete API dissection └─ METHODOLOGY.md how it was probed (approach, false trails, traffic capture) examples/ real captured JSON responses + the machine-readable API reference ``` ## 快速开始 ``` pip install pyks2 # or: pip install -e . from a clone ``` 加入相机的 WiFi (`PENTAX_XXXXXX`)，然后： ``` from pyks2 import K_S2_WiFi cam = K_S2_WiFi() # defaults to 192.168.0.1 assert cam.ping() # 安全地拍摄一张照片：记录 baseline，触发，等待 NEW 文件， # 并在一次调用中完成全部下载 (af="off" 是 MF 安全的：必定释放) info = cam.capture(af="off", download_to="shot.dng") print("captured:", info.path) # 更改设置 (由相机验证；非法值会引发异常) cam.set_camera_params(av="8.0", sv="400") # 浏览 card for photo in cam.list_photos(): print(photo.path) ``` 事件驱动，无需轮询： ``` with cam.events() as ev: # /v1/changes WebSocket for change in ev: if change.is_storage: # a frame just landed print("captured:", cam.latest_info().path) elif change.is_camera: # a setting changed on the body print("settings:", cam.get_camera_params()) ``` 实时取景 (MJPEG)： ``` for jpeg in cam.iter_liveview_frames(max_frames=1): open("frame.jpg", "wb").write(jpeg) ``` ## CLI 库提供的所有功能，均可通过终端实现： ``` pyks2 ping pyks2 info # model, firmware, battery, storage pyks2 shoot --af off --wait --download shot.dng pyks2 settings # show current settings pyks2 settings av=8.0 sv=400 # set them pyks2 lists # capability lists (dropdown sources) pyks2 browse --limit 20 # list photos pyks2 download 100_1507/IMGP1974.DNG --size view -o preview.jpg pyks2 liveview -o frame.jpg pyks2 watch --resolve # stream camera events live ``` ## Web GUI 我们正在计划开发一个基于浏览器的控制面板，实现完全对标 Image Sync 的功能，并提供更多扩展（实时取景、远程拍摄、点击对焦、由相机自身的功能列表驱动的设置面板、安全的闲置图库以及事件驱动的更新）。该面板将由一个轻量级的本地后端提供服务，该后端复用了此库，因此可以在任何操作系统的任何浏览器中运行。*此版本尚未包含该功能，目前发布的是库和 CLI。* ## 逆向工程 本项目的核心是这份文档。亮点包括： - **完整的 API 包含 40 个 endpoint**，组织结构为五个读取*组*（`constants`/`params`/`variables`/`status`/`props`） × 四个*子系统*（`camera`/`lens`/`liveview`/`device`），外加拍摄/对焦/照片/实时取景操作以及一个 WebSocket。 - 每个客户端必须遵守的**两条协议定律**：真实状态包含在响应体的 `errCode` 中（而不是 HTTP 状态码中），并且 datetime/数值格式在不同 endpoint 之间不一致。 - 映射并解释了**硬件互锁**：AF/MF 拨杆、模式转盘和影片模式仅限物理操作；影片模式会*完全禁用 WiFi*；打开 SD 卡槽盖会中断连接；相机的 WiFi 接入点使用客户端隔离（这决定了官方应用流量的抓取方式）。 - **Image Sync 的实际工作原理**，通过网络抓包获取——以及为什么此客户端的事件驱动设计更好。 请从 **[docs/PROTOCOL.md](https://picklerick2005.github.io/PyKS2/PROTOCOL.html)** 开始阅读，然后是 **[docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html)**。原始证据位于 **[examples/](https://github.com/PICKLERICK2005/pyks2/tree/main/examples)** 中，而机器可读的规范位于 **[examples/API_REFERENCE.json](https://github.com/PICKLERICK2005/pyks2/blob/main/examples/API_REFERENCE.json)**。 ## 开发与测试 ``` git clone https://github.com/PICKLERICK2005/pyks2.git cd pyks2 pip install -e ".[dev]" # installs pytest, mypy, ruff pytest -q # 37 tests, no camera required ``` 测试套件完全通过 `tests/conftest.py` 中的 mock 相机针对已捕获的 fixture (`examples/*.json`) 运行，因此不需要任何硬件。测试还作为 API 行为的可执行文档——包括那些较为复杂的发现（异步拍摄、B 门校正、动态功能列表）。 ## 兼容性 已在 **Pentax K-S2, 固件版本 01.10** 上验证。其他 Pentax 机身（K-1、 KP、K-70、K-3……）共享了此 API 家族的大部分内容，但在细节上有所不同。在另一台机身上运行 [docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html) 中的探测方法并发送差异，将是你能做出的最有用的贡献！ ## 许可证 MIT — 详见 [LICENSE](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE)。 ## 致谢 antiguru wiki 上 2016 年的 K-1 WiFi 分析是提出假设的一个有用起点。这里的所有内容均已通过物理 K-S2 独立验证。本项目仅检查了相机自身的网络行为和作者自己的硬件；不包含任何厂商代码或未提及的参考资料。

标签：HTTP API, Python, 云资产清单, 无后门, 物联网, 相机控制, 逆向工具, 逆向工程