link2ctrl

A small Linux utility to control the advanced (AI / gesture) features of the Insta360 Link 2 / Link 2 Pro family via the UVC Extension Unit (XU) API (UVCIOC_CTRL_QUERY).

Basic controls (pan, tilt, zoom, brightness, white balance) already work natively through the standard V4L2 interface. This tool unlocks the vendor-specific controls that Insta360 normally only exposes through their Windows/macOS "Link Controller" application.

How it works

UVC Extension Units are vendor-defined control blocks embedded in the USB device descriptor. Modern Linux kernels (uvcvideo ≥ 0.2.0) enumerate them automatically, so UVCIOC_CTRL_ADD is no longer needed — the kernel queries the descriptor from the device on its own. We use UVCIOC_CTRL_QUERY directly to read and write the raw XU payloads.

The tool auto-probes unit IDs 1–255 to find the AI control unit, then reads/writes named controls.

Protocol notes

The XU selectors were reverse-engineered from the Windows/macOS driver binaries and the WebSocket protocol documented at dt.in.th.

Selector	Name	Size	Notes
0x02	XU_VIDEO_MODE_CONTROL	61 B	byte[0]: 0=normal 1=auto-composition 2=tracking 4=whiteboard 5=overhead 6=desk-view
0x05	XU_GESTURE_STATUS_CONTROL	1 B	Bitmask GET+SET: bit1=Palm bit2=L bit3=V (e.g. 0x0E = all on)
0x07	XU_NOISE_CANCEL_CONTROL	1 B	0=off 1=on
0x09	XU_EXPOSURE_VALUE_CONTROL	2 B	signed int16 little-endian
0x0B	XU_DEVICE_STATUS_CONTROL	5 B	read-only
0x0C	XU_DEVICE_SN_CONTROL	32 B	serial number string, read-only
0x12	XU_TRACK_SPEED_CONTROL	1 B	1=slow 2=medium 3=fast

Caution: These selectors are derived from reverse-engineering. Some may not be present in all firmware versions. Always read (-s) before setting, and test one control at a time.

Building

make

Requires a C11 compiler and Linux kernel headers (standard on any distro with linux-headers or kernel-devel installed).

Installation

sudo make install      # installs to /usr/local/bin/link2ctrlz
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG video "$USER"   # then log out and back in

Usage

link2ctrl [OPTIONS] [CONTROL=VALUE ...]

Options:
  -d DEVICE    Video device (default: /dev/video0)
  -u UNIT_ID   Force XU unit ID (1–255), skips auto-probe
  -s           Show current settings
  -D           Dump raw XU data for all units (debugging, needs root)
  -h           Help

Controls:
  video_mode=N      0=normal 1=auto-composition 2=tracking
                    4=whiteboard 5=overhead 6=desk-view
  gesture_palm=N    Palm gesture: 0=off 1=on
  gesture_l=N       L gesture: 0=off 1=on
  gesture_v=N       V gesture: 0=off 1=on
  gesture_raw=N     Raw gesture bitmask: bit1=Palm bit2=L bit3=V
                    e.g. 0x0E = Palm+L+V all on, 0x00 = none
  noise_cancel=N    Noise cancellation: 0=off 1=on
  track_speed=N     1=slow 2=medium 3=fast
  exposure_bias=N   Signed 16-bit exposure bias

Examples

# Show all current AI settings
link2ctrl -s

# Enable face/body tracking at medium speed
link2ctrl video_mode=2 track_speed=2

# Enable all gestures
link2ctrl gesture_raw=0x0E

# Disable only the V gesture
link2ctrl gesture_v=0

# Switch to normal webcam mode (no AI)
link2ctrl video_mode=0

# Dump raw XU bytes from all units (useful when adding new selectors)
sudo link2ctrl -D

Finding the right /dev/video device

ls /dev/video*
v4l2-ctl --list-devices

Supported models

USB PID	Model
4c04	Link 2
4c05	Link 2C
4c06	Link 2 Pro
4c07	Link 2C Pro

Troubleshooting

"Could not find the AI extension unit"

• Run sudo link2ctrl -D to dump all XU units and their selectors.
• If you see output, note the unit ID and pass it with -u.
• The camera must not be in "USB Drive Mode" (firmware update mode).

EACCES / permission denied

• Install the udev rule and add yourself to the video group, or run with sudo.

Controls return EINVAL / EPIPE

• The selector may not be supported by your firmware version.
• Use -D to see which selectors actually respond on your device.

ENOENT after UVCIOC_CTRL_QUERY

• The unit ID is wrong. Use -D to find the correct one.

License

MIT