Skip to content

Add Link 2C digital framing via Host PTZ - #2

Draft
p0ns wants to merge 2 commits into
illegalstudio:mainfrom
p0ns:feat/link2c-digital-framing
Draft

p0ns wants to merge 2 commits into
illegalstudio:mainfrom
p0ns:feat/link2c-digital-framing

Conversation

@p0ns

@p0ns p0ns commented Sep 13, 2026

Copy link
Copy Markdown

Stack / review order

Depends on #1. Please merge the basic Link 2C support first.

This branch is stacked on feat/link2c-support. Both branches live in a fork, so GitHub cannot use that fork-only branch as the base of an upstream PR. This is a draft against upstream main; its full diff temporarily includes #1. After #1 merges, the branch can be rebased onto upstream main to leave only the framing commit.

Framing-only review: p0ns/linkctl@feat/link2c-support...feat/link2c-digital-framing

Framing commit: 1923457.

Summary

Add an explicit frame command for the fixed-lens Link 2C, separate from degree-based gimbal controls:

linkctl frame
linkctl frame --zoom 2 --center
linkctl frame --x 0.6
linkctl frame --y 0.4
linkctl frame --center
linkctl frame --json
  • X/Y are normalized crop-center coordinates in 0..1; zoom is 1..4. Omitted fields retain their exact current values.
  • Use the existing kernel UVC ioctl path, with no proprietary runtime dependency or driver detach.
  • Validate model, extension GUIDs, command length, SET capability, finite input ranges, and activity before writing.
  • Emit actual readback and a warning if the requested state has not been confirmed.
  • Recognize the official SDK's 0x07 Auto Framing mode; reject unsupported/special/idle coordinate layouts.
  • Add command/parser/protocol tests and document protocol evidence, usage, and safety constraints.

Protocol evidence

Recovered by static inspection of the official Insta360 Linux SDK, revision 2dd2c78186b0335a530042ae49accbef249d6a95. Full source links, binary SHA-256, symbol addresses, and decoding evidence are in docs/link2c-framing.md.

  • Write: image XU (unit 10 on this camera), selector 0x13, SET_CUR; eight bytes: LE uint16 zoom/X/Y followed by movement/zoom step bytes.
  • Position readback: info XU (unit 9), selector 0x02; LE uint16 X/Y at offsets 38/40, not the setter's selector.
  • The SDK's GetHostPTZ does not populate zoom, so zoom is read separately through V4L2.
  • Unit 9's mode payload is never written.

Hardware validation

On a physical Link 2C (2e1a:4c03):

  • Coordinate/zoom readback works.
  • Host PTZ GET_LEN returns 8 and GET_INFO returns 0x03 (GET/SET).
  • The camera owner confirmed that framing writes work in manual testing. This is user-reported hardware validation, not an automated visual-motion assertion.
  • Edge clamping, screen-direction polarity, timing, and interactions with Auto Framing still need broader validation. The overall model validation flag remains conservative.

Tests

  • cargo fmt --check
  • cargo test — 72 passed
  • cargo test --features hardware-tests -- --ignored readonly — 5 passed
  • cargo clippy --all-targets --all-features -- -D warnings
  • Release build succeeds.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant