lucasoskorep/insta360-link-controller
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Rename project, crates, and binaries to open-360-link

Browse Source
This commit is contained in:
Lucas Oskorep committed 2026-10-27 11:27:30 -04:00
1 parent ef641ac31b
commit bbdcde3f0f
28 files changed
+219 -207
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+38 -39
View File
@@ -1,4 +1,4 @@
# Insta360 Link Open Controller
# Open 360 Link
A pure-Rust, cross-platform (**Linux**, **Windows**, **macOS**) hardware controller suite for the **Insta360 Link**, **Insta360 Link 2**, **Insta360 Link 2C**, and **Insta360 Link 2 Pro (PUC3)** 4K AI webcams.
@@ -12,10 +12,10 @@ Built by reverse-engineering the proprietary USB & UVC Extension Unit (`XU1` and
| Crate / Binary | Description |
| :--- | :--- |
| **`insta360-link-protocol`** | Core Rust library implementing USB device discovery, UVC VideoControl descriptor parsing, standard UVC `CT_*`/`PU_*` controls, proprietary `XU1`/`XU2` codecs, `NusbTransport` (pure-Rust USB via `nusb`), and a stateful `MockCameraTransport` simulator. |
| **`insta360-link-ctl`** (`insta360-link-cli`) | Command-line tool for scripting PTZ movement, presets, video modes (`Normal`, `AutoTracking`, `WhiteBoard`, `OverheadShot`, `DeskView`, `AutoFraming`, `SmartWhiteBoard`), exposure/ISO, white balance, audio beamforming modes, filters, and extended hardware switches. |
| **`insta360-link-server`** | Asynchronous HTTP REST & WebSocket daemon (`axum` + `tokio`) for remote control, Stream Deck / OBS integration, and real-time state synchronization. |
| **`insta360-link-gui`** | Native cross-platform desktop GUI (`egui` / `eframe`) featuring a virtual gimbal PTZ joystick, preset slots, AI mode switcher, image adjustment sliders, audio & filter controls, and built-in simulated camera mode. |
| **`open-360-link-protocol`** | Core Rust library implementing USB device discovery, UVC VideoControl descriptor parsing, standard UVC `CT_*`/`PU_*` controls, proprietary `XU1`/`XU2` codecs, `NusbTransport` (pure-Rust USB via `nusb`), and a stateful `MockCameraTransport` simulator. |
| **`open-360-link-ctl`** (`open-360-link-cli`) | Command-line tool for scripting PTZ movement, presets, video modes (`Normal`, `AutoTracking`, `WhiteBoard`, `OverheadShot`, `DeskView`, `AutoFraming`, `SmartWhiteBoard`), exposure/ISO, white balance, audio beamforming modes, filters, and extended hardware switches. |
| **`open-360-link-server`** | Asynchronous HTTP REST & WebSocket daemon (`axum` + `tokio`) for remote control, Stream Deck / OBS integration, and real-time state synchronization. |
| **`open-360-link-gui`** | Native cross-platform desktop GUI (`egui` / `eframe`) featuring a virtual gimbal PTZ joystick, AI mode switcher, image adjustment sliders, audio & filter controls, and live camera preview/recording. |
---
@@ -61,9 +61,9 @@ cargo build --release
```
The compiled binaries will be placed in `target/release/`:
- `target/release/insta360-link-ctl`
- `target/release/insta360-link-server`
- `target/release/insta360-link-gui`
- `target/release/open-360-link-ctl`
- `target/release/open-360-link-server`
- `target/release/open-360-link-gui`
---
@@ -71,12 +71,12 @@ The compiled binaries will be placed in `target/release/`:
### Linux (`V4L2` & `uvcvideo`)
On Linux, `insta360-link-protocol` communicates directly with the primary V4L2 video capture node (`/dev/video*`) using `UVCIOC_CTRL_QUERY` for proprietary Insta360 Extension Unit (`XU1`/`XU2`) commands and standard V4L2 `VIDIOC_G_CTRL`/`VIDIOC_S_CTRL` ioctls for Processing Unit / Camera Terminal controls, while reading USB descriptors from sysfs. Because `systemd-logind` automatically grants the active desktop user session access to `/dev/video*`, **no custom `udev` rules or `sudo` privileges are required**.
On Linux, `open-360-link-protocol` communicates directly with the primary V4L2 video capture node (`/dev/video*`) using `UVCIOC_CTRL_QUERY` for proprietary Insta360 Extension Unit (`XU1`/`XU2`) commands and standard V4L2 `VIDIOC_G_CTRL`/`VIDIOC_S_CTRL` ioctls for Processing Unit / Camera Terminal controls, while reading USB descriptors from sysfs. Because `systemd-logind` automatically grants the active desktop user session access to `/dev/video*`, **no custom `udev` rules or `sudo` privileges are required**.
#### Arch Linux (AUR)
#### Arch Linux & Arch Linux ARM (AUR)
```bash
yay -S insta360-link-controller-bin
yay -S open-360-link-bin
```
### macOS
@@ -87,74 +87,73 @@ On macOS, `nusb` uses `IOKit` to send UVC class-specific control requests direct
## Usage Examples
### 1. Command-Line Interface (`insta360-link-ctl`)
### 1. Command-Line Interface (`open-360-link-ctl`)
> **Tip**: Pass `--mock` (and optionally `--mock-model link2`, `link2c`, or `link`) to test any command against the simulated camera without physical hardware attached.
> **Tip**: Pass `--mock link2` (`link`, `link2`, or `link2c`) to test any command against the simulated camera without physical hardware attached.
```bash
# List connected Insta360 Link cameras and discovered UVC unit IDs
cargo run -p insta360-link-cli -- list
cargo run -p open-360-link-cli -- list
# Show complete camera status, firmware version, PTZ angles, and active features
cargo run -p insta360-link-cli -- status
cargo run -p open-360-link-cli -- info
# Move gimbal to absolute pan/tilt angles (in degrees) and set zoom (100 = 1.0x, 200 = 2.0x)
cargo run -p insta360-link-cli -- ptz --pan 15.0 --tilt -10.0 --zoom 150
# Move gimbal to absolute pan/tilt angles and set zoom (100 = 1.0x, 200 = 2.0x)
cargo run -p open-360-link-cli -- ptz set-abs --pan 54000 --tilt -36000
cargo run -p open-360-link-cli -- ptz zoom 150
# Center / home the gimbal
cargo run -p insta360-link-cli -- home
cargo run -p open-360-link-cli -- ptz reset
# Save and recall gimbal preset slots (0..5)
cargo run -p insta360-link-cli -- preset save 0
cargo run -p insta360-link-cli -- preset recall 0
# Switch AI Video Mode (normal, tracking, whiteboard, overhead, deskview, auto-framing, smart-whiteboard)
cargo run -p insta360-link-cli -- mode tracking
cargo run -p insta360-link-cli -- tracking --speed fast --composition half-body
# Switch AI Video Mode (normal, auto-tracking, whiteboard, overhead, deskview, auto-framing, smart-whiteboard)
cargo run -p open-360-link-cli -- mode set auto-tracking
cargo run -p open-360-link-cli -- tracking speed fast
# Configure image settings (brightness, contrast, saturation, sharpness, white balance, HDR)
cargo run -p insta360-link-cli -- image --brightness 60 --contrast 55 --hdr on --wb-kelvin 5600
cargo run -p open-360-link-cli -- image brightness 60
cargo run -p open-360-link-cli -- image hdr true
# Configure microphone beamforming mode (voice-focus, noise-suppression, music-balance, original, sound-wall)
cargo run -p insta360-link-cli -- audio --mode voice-focus --denoise on
# Configure microphone beamforming mode (voice-focus, noise-reduction, music-mode, original, sound-wall)
cargo run -p open-360-link-cli -- audio mode voice-focus
cargo run -p open-360-link-cli -- audio denoise true
```
### 2. HTTP & WebSocket Server (`insta360-link-server`)
### 2. HTTP & WebSocket Server (`open-360-link-server`)
Start the daemon on `127.0.0.1:8360` (use `--mock` if no physical camera is connected):
Start the daemon on `127.0.0.1:9360` (use `--mock link2` if no physical camera is connected):
```bash
cargo run -p insta360-link-server -- --bind 127.0.0.1:8360 --mock
cargo run -p open-360-link-server -- --bind 127.0.0.1:9360 --mock link2
```
Example REST API calls:
```bash
# List discovered cameras
curl http://127.0.0.1:8360/api/cameras
curl http://127.0.0.1:9360/api/cameras
# Fetch full camera state snapshot
curl http://127.0.0.1:8360/api/state
curl http://127.0.0.1:9360/api/state
# Set PTZ pan, tilt, or zoom
curl -X POST http://127.0.0.1:8360/api/ptz \
curl -X POST http://127.0.0.1:9360/api/ptz \
-H "Content-Type: application/json" \
-d '{"pan_deg": 20.0, "tilt_deg": -5.0, "zoom": 180}'
# Switch video mode
curl -X POST http://127.0.0.1:8360/api/mode \
curl -X POST http://127.0.0.1:9360/api/mode \
-H "Content-Type: application/json" \
-d '{"mode": "DeskView"}'
```
Connect to `ws://127.0.0.1:8360/ws` over WebSockets to receive real-time JSON state broadcasts and send low-latency PTZ/control commands.
Connect to `ws://127.0.0.1:9360/ws` over WebSockets to receive real-time JSON state broadcasts and send low-latency PTZ/control commands.
### 3. Desktop GUI (`insta360-link-gui`)
### 3. Desktop GUI (`open-360-link-gui`)
Launch the native cross-platform GUI (automatically connects to a physical Insta360 Link camera if found, or falls back to the interactive simulator):
Launch the native cross-platform GUI (automatically connects to a physical Insta360 Link camera if found):
```bash
cargo run -p insta360-link-gui
cargo run -p open-360-link-gui
```
---