pyks2 1.0.0__tar.gz

pyks2-1.0.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to **pyks2** are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] — 2026-07-16
+
+First stable release: a complete, hardware-verified reverse-engineering of the
+Pentax K-S2's built-in WiFi HTTP API, with a Python library, a CLI, and a full
+protocol write-up. Every one of the camera's 38 API endpoint templates is
+characterised — confirmed working, confirmed read-only, or confirmed
+unsupported — with zero remaining unknowns.
+
+### The dissection
+- Complete map of the `/v1/*` API: five read groups
+  (`constants`/`params`/`variables`/`status`/`props`) × four subsystems
+  (`camera`/`lens`/`liveview`/`device`), plus capture, focus, photo, live view,
+  and the `/v1/changes` WebSocket.
+- Two protocol laws documented: `errCode` lives in the body (not the HTTP
+  status), and datetime/numeric formats vary by endpoint.
+- Full mode-dial characterisation (P/Sv/Tv/Av/TAv/M/**Bulb**/U1/U2/auto/scene/
+  HDR/movie), with a per-mode value-writability matrix driven by list emptiness.
+- Hardware interlocks mapped and explained: AF/MF lever, mode dial, movie mode
+  disabling WiFi, the SD-door disconnect, device/lens read-only params, and the
+  WiFi AP's client isolation.
+- 40 real captured responses in `examples/`, plus a machine-readable
+  `examples/API_REFERENCE.json`.
+
+### Key findings that corrected earlier assumptions
+- **`/v1/photos` does not hang.** The long-standing "it hangs indefinitely"
+  belief was a client-side artifact; the endpoint is reliable and scales gently
+  with file count. It also supports an undocumented `?limit=N`.
+- **`shoot/start` / `shoot/finish` are Bulb exposure controls, not movie**, and
+  they work over WiFi when the dial is on B. (`bulb_start()`, `bulb_finish()`,
+  `bulb_exposure(seconds)`.)
+- **`storages[].remain` is a frame count, not bytes.**
+- **Lens identity is not exposed** over WiFi.
+- **`/v1/liveview/zoom` is a no-op over WiFi** — accepts any param, returns 200,
+  but never changes the frame.
+
+### Library
+- `K_S2_WiFi` a camera-only HTTP client with typed models, defensive parsing
+  for the datetime/numeric quirks, and `errCode`-aware exceptions.
+- Race-free capture via `capture()` (baseline → shoot → wait for the new file).
+- Event-driven workflow via the `/v1/changes` WebSocket (`events()`), replacing
+  the official app's polling.
+- Correct handling of dynamic capability lists (e.g. `avList`) and the
+  list-emptiness writability signal for `av`/`tv`.
+
+### CLI
+- `pyks2 ping | info | apis | lists | shoot | settings | focus | browse |
+  download | liveview | bulb | watch`.
+
+### Not included (planned)
+- A web GUI is planned for a later release; this version ships the library, CLI,
+  and documentation.

pyks2-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamal El Siblany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyks2-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include LICENSE
+recursive-include docs *.md *.yml
+recursive-include examples *.json *.jsonl *.md
+recursive-include tests *.py

pyks2-1.0.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: pyks2
+Version: 1.0.0
+Summary: A Python client and CLI for the Pentax K-S2's undocumented WiFi HTTP API, plus a reverse-engineering write-up. (Web GUI planned.)
+Author-email: Jamal El Siblany <jamalsiblani@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PICKLERICK2005/pyks2
+Project-URL: Documentation, https://PICKLERICK2005.github.io/pyks2/
+Project-URL: Repository, https://github.com/PICKLERICK2005/pyks2
+Project-URL: Issues, https://github.com/PICKLERICK2005/pyks2/issues
+Project-URL: Changelog, https://github.com/PICKLERICK2005/pyks2/blob/main/CHANGELOG.md
+Keywords: pentax,k-s2,camera,wifi,reverse-engineering,tethering,remote-control,mjpeg
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics :: Capture
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# pyks2
+
+[![tests](https://github.com/PICKLERICK2005/pyks2/actions/workflows/test.yml/badge.svg)](https://github.com/PICKLERICK2005/pyks2/actions/workflows/test.yml)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![license](https://img.shields.io/badge/license-MIT-green)](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE)
+
+A Python library and CLI for controlling the **Pentax K-S2** over its
+built-in WiFi, built on a complete, hardware-verified reverse-engineering of
+the camera's undocumented HTTP API. (A web GUI is planned; see below.)
+
+The K-S2 has a WiFi remote-control API, but Pentax never documented it. This
+project maps the **entire surface** of the K-S2's API against a physical camera,
+writes it up as a proper dissection, and ships a clean client that is lighter
+and more capable than the vendor's own Image Sync app.
+
+Visit the pages website ![here](https://picklerick2005.github.io/PyKS2/).
+
+> **Two things make this more than "another camera library":**
+> 1. A full [protocol dissection](https://picklerick2005.github.io/PyKS2/PROTOCOL.html) and
+>    [reverse-engineering methodology](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html), every endpoint,
+>    every quirk, every hardware limitation, with the raw captures to prove it.
+> 2. A design that **beats the official app**: event-driven via the camera's
+>    WebSocket instead of the poll-storm Image Sync uses (~90% of its total
+>    requests were just polling one endpoint while interacting with app actively).
+
+---
+
+## What's here
+
+```
+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
+```
+
+---
+
+## Quick start
+
+```bash
+pip install pyks2            # or: pip install -e .  from a clone
+```
+
+Join the camera's WiFi (`PENTAX_XXXXXX`), then:
+
+```python
+from pyks2 import K_S2_WiFi
+
+cam = K_S2_WiFi()            # defaults to 192.168.0.1
+assert cam.ping()
+
+# take one photo safely: records the baseline, fires, waits for the NEW file,
+# and downloads it all in one call (af="off" is MF-safe: always releases)
+info = cam.capture(af="off", download_to="shot.dng")
+print("captured:", info.path)
+
+# change settings (validated by the camera; illegal values raise)
+cam.set_camera_params(av="8.0", sv="400")
+
+# browse the card
+for photo in cam.list_photos():
+    print(photo.path)
+```
+
+Event-driven, no polling:
+
+```python
+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())
+```
+
+Live view (MJPEG):
+
+```python
+for jpeg in cam.iter_liveview_frames(max_frames=1):
+    open("frame.jpg", "wb").write(jpeg)
+```
+
+---
+
+## CLI
+
+Everything the library does, from a terminal:
+
+```bash
+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
+
+A browser-based control panel is planned, full Image-Sync parity plus
+extensions (live view, remote capture, touch-to-focus, a settings panel driven
+by the camera's own capability lists, an idle-safe gallery, and event-driven
+updates), served by a thin local backend that reuses this library so it runs on
+any OS in any browser. *Not yet included in this release, the library and CLI
+are the shipping surfaces.*
+
+---
+
+## The reverse engineering
+
+The heart of this project is the write-up. Highlights:
+
+- **The full API is 40 endpoints**, organised as five read *groups*
+  (`constants`/`params`/`variables`/`status`/`props`) × four *subsystems*
+  (`camera`/`lens`/`liveview`/`device`), plus capture/focus/photo/liveview
+  actions and a WebSocket.
+- **Two protocol laws** every client must respect: the real status is in the
+  body's `errCode` (not the HTTP status), and datetime/numeric formats are
+  inconsistent across endpoints.
+- **Hardware interlocks** mapped and explained: the AF/MF lever, mode dial, and
+  movie mode are physical-only; movie mode *disables WiFi entirely*; opening the
+  SD-card door kills the connection; and the camera's WiFi access point uses
+  client isolation (which shaped how the official app's traffic had to be
+  captured).
+- **How Image Sync actually works**, captured off the wire — and why this
+  client's event-driven design is better.
+
+Start with **[docs/PROTOCOL.md](https://picklerick2005.github.io/PyKS2/PROTOCOL.html)**, then
+**[docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html)**. The raw evidence is in
+**[examples/](https://github.com/PICKLERICK2005/pyks2/tree/main/examples)** and the machine-readable spec is
+**[examples/API_REFERENCE.json](https://github.com/PICKLERICK2005/pyks2/blob/main/examples/API_REFERENCE.json)**.
+
+---
+
+## Development & tests
+
+```bash
+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
+```
+
+The test suite runs entirely against captured fixtures (`examples/*.json`) via a
+mock camera in `tests/conftest.py`, so it needs no hardware. Tests also serve as
+executable documentation of the API's behaviour — including the trickier
+findings (async capture, the Bulb correction, dynamic capability lists).
+
+## Compatibility
+
+Verified against a **Pentax K-S2, firmware 01.10**. Other Pentax bodies (K-1,
+KP, K-70, K-3…) share much of this API family but differ in specifics. Running
+the probing approach in [docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html) on another
+body and sending the diffs is the most useful contribution you could make!
+
+## License
+
+MIT — see [LICENSE](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE).
+
+## Acknowledgements
+
+The 2016 K-1 WiFi analysis on the antiguru wiki was a useful starting point for
+hypotheses. Everything here was independently verified against a physical K-S2.
+This project inspects only the camera's own network behaviour and my own hardware;
+it contains no vendor code or any unmentioned references.

pyks2-1.0.0/README.md

@@ -0,0 +1,179 @@
+# pyks2
+
+[![tests](https://github.com/PICKLERICK2005/pyks2/actions/workflows/test.yml/badge.svg)](https://github.com/PICKLERICK2005/pyks2/actions/workflows/test.yml)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![license](https://img.shields.io/badge/license-MIT-green)](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE)
+
+A Python library and CLI for controlling the **Pentax K-S2** over its
+built-in WiFi, built on a complete, hardware-verified reverse-engineering of
+the camera's undocumented HTTP API. (A web GUI is planned; see below.)
+
+The K-S2 has a WiFi remote-control API, but Pentax never documented it. This
+project maps the **entire surface** of the K-S2's API against a physical camera,
+writes it up as a proper dissection, and ships a clean client that is lighter
+and more capable than the vendor's own Image Sync app.
+
+Visit the pages website ![here](https://picklerick2005.github.io/PyKS2/).
+
+> **Two things make this more than "another camera library":**
+> 1. A full [protocol dissection](https://picklerick2005.github.io/PyKS2/PROTOCOL.html) and
+>    [reverse-engineering methodology](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html), every endpoint,
+>    every quirk, every hardware limitation, with the raw captures to prove it.
+> 2. A design that **beats the official app**: event-driven via the camera's
+>    WebSocket instead of the poll-storm Image Sync uses (~90% of its total
+>    requests were just polling one endpoint while interacting with app actively).
+
+---
+
+## What's here
+
+```
+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
+```
+
+---
+
+## Quick start
+
+```bash
+pip install pyks2            # or: pip install -e .  from a clone
+```
+
+Join the camera's WiFi (`PENTAX_XXXXXX`), then:
+
+```python
+from pyks2 import K_S2_WiFi
+
+cam = K_S2_WiFi()            # defaults to 192.168.0.1
+assert cam.ping()
+
+# take one photo safely: records the baseline, fires, waits for the NEW file,
+# and downloads it all in one call (af="off" is MF-safe: always releases)
+info = cam.capture(af="off", download_to="shot.dng")
+print("captured:", info.path)
+
+# change settings (validated by the camera; illegal values raise)
+cam.set_camera_params(av="8.0", sv="400")
+
+# browse the card
+for photo in cam.list_photos():
+    print(photo.path)
+```
+
+Event-driven, no polling:
+
+```python
+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())
+```
+
+Live view (MJPEG):
+
+```python
+for jpeg in cam.iter_liveview_frames(max_frames=1):
+    open("frame.jpg", "wb").write(jpeg)
+```
+
+---
+
+## CLI
+
+Everything the library does, from a terminal:
+
+```bash
+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
+
+A browser-based control panel is planned, full Image-Sync parity plus
+extensions (live view, remote capture, touch-to-focus, a settings panel driven
+by the camera's own capability lists, an idle-safe gallery, and event-driven
+updates), served by a thin local backend that reuses this library so it runs on
+any OS in any browser. *Not yet included in this release, the library and CLI
+are the shipping surfaces.*
+
+---
+
+## The reverse engineering
+
+The heart of this project is the write-up. Highlights:
+
+- **The full API is 40 endpoints**, organised as five read *groups*
+  (`constants`/`params`/`variables`/`status`/`props`) × four *subsystems*
+  (`camera`/`lens`/`liveview`/`device`), plus capture/focus/photo/liveview
+  actions and a WebSocket.
+- **Two protocol laws** every client must respect: the real status is in the
+  body's `errCode` (not the HTTP status), and datetime/numeric formats are
+  inconsistent across endpoints.
+- **Hardware interlocks** mapped and explained: the AF/MF lever, mode dial, and
+  movie mode are physical-only; movie mode *disables WiFi entirely*; opening the
+  SD-card door kills the connection; and the camera's WiFi access point uses
+  client isolation (which shaped how the official app's traffic had to be
+  captured).
+- **How Image Sync actually works**, captured off the wire — and why this
+  client's event-driven design is better.
+
+Start with **[docs/PROTOCOL.md](https://picklerick2005.github.io/PyKS2/PROTOCOL.html)**, then
+**[docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html)**. The raw evidence is in
+**[examples/](https://github.com/PICKLERICK2005/pyks2/tree/main/examples)** and the machine-readable spec is
+**[examples/API_REFERENCE.json](https://github.com/PICKLERICK2005/pyks2/blob/main/examples/API_REFERENCE.json)**.
+
+---
+
+## Development & tests
+
+```bash
+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
+```
+
+The test suite runs entirely against captured fixtures (`examples/*.json`) via a
+mock camera in `tests/conftest.py`, so it needs no hardware. Tests also serve as
+executable documentation of the API's behaviour — including the trickier
+findings (async capture, the Bulb correction, dynamic capability lists).
+
+## Compatibility
+
+Verified against a **Pentax K-S2, firmware 01.10**. Other Pentax bodies (K-1,
+KP, K-70, K-3…) share much of this API family but differ in specifics. Running
+the probing approach in [docs/METHODOLOGY.md](https://picklerick2005.github.io/PyKS2/METHODOLOGY.html) on another
+body and sending the diffs is the most useful contribution you could make!
+
+## License
+
+MIT — see [LICENSE](https://github.com/PICKLERICK2005/pyks2/blob/main/LICENSE).
+
+## Acknowledgements
+
+The 2016 K-1 WiFi analysis on the antiguru wiki was a useful starting point for
+hypotheses. Everything here was independently verified against a physical K-S2.
+This project inspects only the camera's own network behaviour and my own hardware;
+it contains no vendor code or any unmentioned references.

pyks2-1.0.0/docs/METHODOLOGY.md

@@ -0,0 +1,131 @@
+---
+title: Methodology
+nav_order: 3
+---
+
+# How this was reverse-engineered
+
+The [protocol dissection](PROTOCOL.md) presents the finished map. This document
+is about *how* the map was made. The approach, the tools, the false trails, and
+the traffic capture to find out how the official Image Sync app works. If you 
+want to replicate this on your own non-KS2 Pentax body, start here.
+
+There was no documentation to work from. Everything below is the process of
+turning a black-box camera into a fully characterised API.
+
+---
+
+## Principle: confirmed, not inferred
+
+The guiding rule throughout: **a behaviour isn't "known" until the hardware
+demonstrates it.** The official Pentax Image Sync android app, forum posts, and a 
+partial 2016 write-up of the related K-1 on the pentax forums were useful for coming up with 
+hypotheses, but every claim in the final map rests on a response captured from the actual camera body. 
+Several "facts" inherited from prior assumptions turned out to be wrong (see the `/v1/photos`
+myth below), which is exactly why the this rule and methedology mattered most throughout
+this project. The KS2 being very different from it's predecessors (post-ricoh acquisition)
+is the main reason why this whole project was initiated, not to mention the fact that the 
+already-existing PKTRIGGERCORD does not support the KS2.
+
+---
+
+## Stage 1: find the surface
+
+The break came from `GET /v1/apis`, which the camera answers with a list of all
+its own endpoint templates. That turned an open-ended search into a finite
+checklist of ~40 endpoints to characterise.
+
+From there, the read endpoints were easy, and pleasantly so! because the
+camera serves plain JSON that a browser renders directly (all hail firefox). 
+Navigating to `http://192.168.0.1/v1/props`, `/v1/constants/camera`, and so on in 
+Firefox showed each response formatted and readable, no tooling required. Hitting 
+each `/v1/{group}/{facet}` combination and diffing the results is where the
+five-groups-×-four-facets structure became clear.
+
+## Stage 2: an automated scrubber
+
+Hitting 40 endpoints by hand doesn't scale and isn't fun, so the
+probing was scripted. A single sequenced scrubber:
+
+- fired every endpoint in a defined order,
+- captured status, headers, timing, and body for each,
+- wrote every response to disk (the curated results became
+  [`examples/`](../examples/)),
+- snapshotted the camera's settings before write-tests and restored them after
+  (so probing never left the camera in a weird state),
+- and paused at the handful of probes that need physcial changes to the camera body or observations.
+
+That last point became a core technique, using claude's help to make the scrubber script and instead
+focusing on physically manipulating the camera when prompted.
+
+The main methodology for these automated scripts is: human drives the hardware; 
+the script reads and correlates and logs any changes.**
+
+This is how the event vocabulary was mapped. With the `/v1/changes` WebSocket
+open, the script prompted through a scripted sequence of physical actions: "turn
+the mode dial," "half-press the shutter," "flip the AF/MF lever," "open the SD
+door" etc... and logged which `changed` events each action produced.
+
+---
+
+## Stage 5: capturing traffic from Pentax's Image Sync app on android
+
+One question resisted every direct probe: how does the official app populate its
+image gallery grid efficiently given that `?size=thumb` returns `400`? 
+The only way to know for certain was to watch the app's own traffic.
+Because the camera speaks plain HTTP and does not verify it's being controlled by the 
+app whatsoever, no TLS interception was needed, only running an android phone's traffic through
+a machine running mitmproxy was needed.
+
+Although I was able to connect more than one device to the camera's hotspot, 
+**The camera's WiFi access point uses client isolation.** With the phone and a
+PC both joined to the camera's network, so they cannot see each other, every
+attempt to route the phone's traffic through a proxy on the PC timed out. 
+The PC could reach the camera (`192.168.0.1`) but not the phone on the same network. 
+Device-to-device traffic is blocked at the AP.
+
+The fix was to change the topology so the phone→PC link doesn't go through the
+camera at all:
+
+```
+Phone ──(PC's own hotspot)──> Windows Computer ──(camera WiFi)──> Camera
+                                    │
+                              proxy sits here
+```
+
+The PC hosts a WiFi hotspot, the phone joins *that* (no isolation on the
+PC's own network), and the PC bridges to the camera over its separate
+WiFi connection with the proxy in the middle. Right away, even before setting up
+the proxy, just by having the android device connected to the PC's hotspot which was
+in turn connected to the KS2's hotspot, the Image Sync app was able to control the camera
+just fine.
+
+With the phone's proxy pointed at the PC, the app's requests were thoroughly recorded and
+used to verify earlier findings. The gallery turned out to use exactly the documented endpoints 
+(`/v1/photos` →per-file `/info` → `?size=view` thumbnails), and the capture also revealed the
+app's poll-heavy architecture (618 of 691 requests were `/v1/props` over a couple minutes).
+No secret endpoints, just confirmation, plus the architectural insight that `pyks2` could
+do better with the WebSocket due to the native app's poor performance.
+
+> This technique was the least intrusive and didn't decompile or direclty modify any vendor software.
+
+---
+
+## Replicating on your own body
+
+1. Enable the camera's WiFi and join its network (`PENTAX_XXXXXX`).
+2. Confirm reachability by opening `http://192.168.0.1/v1/ping` in a browser
+   the camera serves readable JSON, so most reads can be explored this way.
+3. Walk the `/v1/{group}/{facet}` endpoints and the `/v1/apis` list; capture
+   each response. Scripting this (fire in sequence, save body + headers +
+   timing, snapshot/restore settings around any write-tests, and pause for
+   operator observation on the physical probes) makes it reproducible on different 
+   bodies or firmware versions.
+4. Compare your captures against [`examples/`](../examples/). Different bodies
+   (K-1, KP, K-70) share this API family and will most likely differ in multiple ways
+   contributions documenting those differences are more than welcome!
+
+---
+
+*Back to the [protocol dissection](PROTOCOL.md), or on to the library and CLI in
+the [README](../README.md).*