openterface-rs

A native-Linux, Wayland-only host application for the Openterface Mini-KVM, written entirely in Rust.

openterface-rs lets you control a target computer's keyboard, video, and mouse over a single USB connection — no network required — using the Openterface hardware (MS2109 HDMI capture + CH9329 USB-serial HID bridge).

Status: v1.0 targets the core KVM workflow — video plus keyboard/mouse over one USB cable. Real-hardware validation runs in a VM via the closed-loop harness. See docs/ for full documentation.

Why Rust?

• Fast builds and lean dependencies. A device-agnostic core library plus a thin CLI and an optional winit/wgpu display frontend.
• Testable without hardware. Every hardware interaction is a trait, so the full pipeline runs against simulated devices — the test-suite needs no device.
• Linux + Wayland native. No XWayland.

Install

Prebuilt binaries for x86_64 and aarch64 (64-bit Pi) are published on the Releases page once a version is tagged (the first tag is cut after real-hardware validation — until then, build from source or use Nix):

curl -fsSL https://raw.githubusercontent.com/vicondoa/openterface-rs/main/packaging/install.sh -o install.sh
sh install.sh                         # verifies its own download checksums

Or with Cargo / Nix:

cargo install --git https://github.com/vicondoa/openterface-rs openterface-cli --features hardware --locked
nix run github:vicondoa/openterface-rs

See the install guide and permissions & udev for non-root device access.

Usage

openterface-rs scan        # list Openterface devices
openterface-rs status      # show device status
openterface-rs connect     # open the KVM session (auto-detects)
openterface-rs reset --serial /dev/ttyACM0   # CH9329 factory reset

While the session window is focused, Ctrl+Shift+V pastes the local Wayland clipboard to the target by typing it as HID keystrokes. This is not target clipboard sync; unsupported non-US-layout characters are reported and skipped. Middle-click is forwarded normally by default, and can optionally be configured as a host-side primary-selection or clipboard paste. Because the paste shortcut is host-local, it is not forwarded to the target while paste is enabled; set OPENTERFACE_PASTE_SHORTCUT (for example ctrl-alt-shift-v) or OPENTERFACE_ENABLE_PASTE=0 if you need Ctrl+Shift+V inside the target.

Runtime behavior is tunable via OPENTERFACE_* environment variables (mouse pacing, idle-decode throttling, fullscreen, paste controls) — see the CLI reference and environment variables.

Workspace layout

Crate	Role
openterface-core	Device-agnostic core: CH9329 protocol, V4L2 capture, decode, discovery, input, pacing, session. No GUI, no async runtime.
openterface-cli	The openterface-rs command-line frontend.
openterface-gui	Native Wayland display: winit + wgpu.
openterface-test-support	Simulated devices and fixtures for hardware-free tests.

Building

cargo build --workspace
cargo test --workspace        # runs with no hardware, no system libraries

A Nix dev shell (toolchain + system libraries) is provided:

nix develop

See the build guide for the hardware features and the full set of CI gates.

Hardware

Endpoint	Chip	Linux node	Carries
Video	MS2109 HDMI capture	/dev/videoN (UVC / MJPEG)	the target's screen
Input	CH9329 USB-serial HID	/dev/ttyACM0 (115200 8N1)	mouse + keyboard

Documentation

Full docs live in docs/: the CLI reference, CH9329 protocol, environment variables, install / udev / troubleshooting guides, and the architecture explanation.

Acknowledgements

Thanks to @bresilla, author of the original C++ Openterface version, for pioneering the hardware support that made this Rust implementation possible.

License

Licensed under the Apache License, Version 2.0.

Contributing

See CONTRIBUTING.md and AGENTS.md (development process, panel review, versioning, and test layout).