Openterface Mini-KVM QT Edition

Control your target computer remotely with keyboard, video, and mouse over a single USB connection.

What is This?

Openterface Mini-KVM is a compact KVM (Keyboard-Video-Mouse) switch that lets you control a target computer remotely from your host machine using a single USB connection. No network required. Ideal for:

• 💻 Managing headless servers and embedded systems
• 🎮 Controlling IoT devices and Raspberry Pi systems
• 🔧 Hardware debugging and development
• 🏢 Data center and lab management
• 📱 Controlling phones, tablets, and ARM devices

Note: This is the QT version for Linux & Windows. Currently in active development with feature parity improvements underway.

---

Table of Contents

• Quick Start
• Features
• Supported OS
• Installation
  • Windows
  • Linux
• Build from Source
• Development
• Firmware Flashing (CH32 KeyMod)
• Troubleshooting
• Support & Community
• License

---

Quick Start

🪟 Windows

1. Download the latest installer from Releases
2. Run the installer (it installs drivers + app automatically)
3. Launch Openterface Mini-KVM from your Start Menu
4. Connect your Mini-KVM device via USB

🐧 Linux (Ubuntu/Debian)

Fastest way (~30 seconds):

curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/main/build-script/install-release.sh | bash

Then run:

openterfaceQT

For other methods and detailed setup, see Installation section below.

---

Features

• Basic KVM operations
• Mouse control absolute mode
• Mouse relative mode
• Audio playing from target
• Paste text to Target device
• OCR text from Target device
• Other feature request? Please join the Discord channel and tell me

For a detailed list of features, please refer to the Features Documentation.

Supported OS

OS	Version	Architecture	Status
Windows	10+	x64	✅ Supported
Ubuntu	22.04+	x64, ARM64	✅ Supported
Fedora	42+	x64, ARM64	✅ Supported
Linux Mint	21.3+	x64	✅ Supported
openSUSE	Tumbleweed	x64	✅ Supported
Arch Linux	Rolling	x64, ARM64	⚠️ Build from source only
🔋 Raspberry Pi OS	64-bit	ARM64	✅ Supported
🔋 Raspberry Pi OS	32-bit	ARM32	❌ Not supported (Qt too old)

---

Installation

Windows Installation

1. Download the latest installer from GitHub Releases (x86 architecture)
2. Run the installer — it will automatically install drivers and the application
3. Launch Openterface Mini-KVM from your Start Menu or application folder
4. Connect your Mini-KVM device via USB

Note: On Windows 11 Version 22H2, some users report driver installation issues. If keyboard/mouse don't respond, manually install the CH340 driver from the WCH website or use the repository driver with pnputil -a CH341SER.INF (run as Administrator).

---

Linux Installation

Choose the method that best suits your needs:

Method	Speed	Effort	Best For
Pre-built Binary	⚡ ~30 sec	Minimal	Most users — fastest & easiest
Build from Source	5-30 min	Medium	Custom modifications needed
Manual Install	Varies	High	Advanced users & troubleshooting

Option 1: Pre-built Binary (Recommended for Most Users)

Install in ~30 seconds (no compilation):

curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/main/build-script/install-release.sh | bash

Supported distributions: Ubuntu/Debian, Fedora/RHEL, openSUSE, Arch Linux

What it does automatically:

• ✅ Downloads pre-built binary for your architecture (x86_64 or ARM64)
• ✅ Installs runtime dependencies (Qt6, FFmpeg, USB libraries)
• ✅ Configures device permissions (udev rules, user groups)
• ✅ Creates desktop menu integration

To install a specific version:

VERSION="v0.5.17" bash <(curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/main/build-script/install-release.sh)

Then launch:

openterfaceQT

---

Option 2: Build from Source (for Custom Modifications)

Quick automated build (5-30 minutes depending on hardware):

curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/main/build-script/install-linux.sh | bash

By default, this builds the stable version. To build a specific version:

# Build a specific version/tag
BUILD_VERSION="v1.0.0" bash <(curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/refs/heads/main/build-script/install-linux.sh)

# Build latest development version
BUILD_VERSION="main" bash <(curl -fsSL https://raw.githubusercontent.com/TechxArtisanStudio/Openterface_QT/refs/heads/main/build-script/install-linux.sh)

For detailed build instructions and developer setup, see Build from Source and Development sections below.

---

Option 3: Manual Installation

For advanced users who prefer manual control:

1. Download the pre-built .deb package from GitHub Releases
2. Install dependencies:

sudo apt install -y \
    libqt6core6 libqt6dbus6 libqt6gui6 libqt6network6 \
    libqt6multimedia6 libqt6multimediawidgets6 libqt6serialport6 \
    libqt6svg6 libqt6concurrent6t64 libusb-1.0-0-dev libssl-dev \
    libavutil58 libavformat60 libavdevice60 libturbojpeg0 \
    libva1 libva-drm2 libva-x11-2 libgstreamer1.0-0

Note for Ubuntu 24.04+ users: the package libturbojpeg0 was renamed to libturbojpeg. If the install command above fails, replace libturbojpeg0 with libturbojpeg.

3. Configure permissions:

```bash
# Add serial and video permissions
sudo usermod -a -G dialout,video $USER
# On Arch Linux, use 'uucp' instead of 'dialout'
sudo usermod -a -G uucp $USER

# Setup udev rules for device access
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", TAG+="uaccess"
SUBSYSTEM=="ttyUSB", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"' | sudo tee /etc/udev/rules.d/51-openterface.rules 

sudo udevadm control --reload-rules
sudo udevadm trigger

4. Install the package:

unzip openterfaceQT.deb.zip
sudo dpkg -i openterfaceQT.deb

5. Run the application:

openterfaceQT

Note: You may need to log out and log back in for group permissions to take effect.

💡 Permission issues? See the Linux Permission Access Guide on our Wiki for detailed troubleshooting of device permissions.

---

Build from Source

For detailed build instructions, see docs/BUILD.md.

Quick links:

• 🪟 Windows Build Guide
• 🐧 Linux Build Guide
  • Automated Script (Recommended)
  • Manual Build Process
• 🔧 Troubleshooting

---

Development

Want to contribute? We'd love your help! Here's how to get started:

Setting Up Your Development Environment

1. Clone the repository:

   git clone https://github.com/TechxArtisanStudio/Openterface_QT.git
   cd Openterface_QT

2. Install build dependencies: See Build from Source section for your OS

3. Build locally:

   mkdir build && cd build
   cmake ..
   make
   ./openterfaceQT

Contributing Code

• Report bugs: Open an issue
• Suggest features: Discuss in Issues
• Submit changes: Create a Pull Request

For detailed contribution guidelines, see CONTRIBUTING.md.

We welcome contributions including:

• 🐛 Bug fixes
• ✨ Feature implementations
• 📖 Documentation improvements
• 🌍 Translations
• 🧪 Test coverage

---

Firmware Flashing (CH32 KeyMod)

If you need to flash or update the firmware on the CH32V208 controller chip of your KeyMod, Openterface provides a built-in WCH ISP Flash Tool — no external programmer needed.

📖 Full guide: docs/ch32_firmware_flashing.md

Quick Steps

Step	Action	Details
1️⃣	Download firmware	Get the firmware from Openterface_KM Releases
2️⃣	Enter ISP mode	⚠️ Unplug KeyMod → Hold BOOT button → Plug in USB → Release BOOT
3️⃣	Open flash tool	In the app: Menu → Advanced → WCH ISP Flash
4️⃣	Scan & Connect	Click Scan Devices, select your device, click Connect
5️⃣	Select firmware	Click Browse... and choose the firmware file
6️⃣	Flash	Click Flash, Verify & Reset and wait for completion
7️⃣	Reconnect	Unplug and re-plug the KeyMod normally (no BOOT button needed)

⚠️ Important: You MUST hold the BOOT button on the KeyMod before plugging it into the computer to enter ISP/bootloader mode. Otherwise the flash tool will not detect the device.

Supported Chips

Chip	VID:PID (Normal)	VID:PID (ISP Mode)
CH32V208	1A86:FE0C	1A86:55E0 / 4348:55E0

---

Troubleshooting

Keyboard and Mouse Not Responding

Windows

1. Ensure the CH340 serial chip driver is installed. Download from WCH website
2. Alternatively, install from the repository driver:

   pnputil -a path\to\CH341SER.INF

   (Run as Administrator)

Linux

1. Download the CH340 driver from WCH website
2. Extract and compile:

   tar -xzf CH341SER_LINUX.tar.gz
   cd CH341SER
   make
   sudo make install

3. Load the driver:

   sudo modprobe ch341

4. Unplug and reconnect the device
5. If still not working, check permissions using the Linux Installation - Manual section or see the Linux Permission Access Guide on our Wiki

Other Issues

For more troubleshooting, see docs/BUILD.md#troubleshooting.

---

Support & Community

Have questions or found a bug? We're here to help!

• 💬 Discord: Join our community for real-time discussions
• 🐛 GitHub Issues: Report bugs or request features
• 📧 Email: techxartisan@gmail.com

---

License

This project is licensed under AGPL-3.0 (Affero General Public License).

Key Terms

• ✅ Free to use, modify, and distribute
• ✅ Source code must be made available to recipients
• ✅ Modifications must be released under AGPL-3.0
• ❌ No warranty provided

For full license details, see LICENSE file in this repository.

Third-Party Libraries

This project uses excellent open-source libraries:

Library	Version	License
Qt Framework	6.4+	LGPL v3
libusb	1.0.26+	LGPL v2.1
FFmpeg	Latest	LGPL v2.1+ / GPL v2
FreeType	2.13.2+	GPL v2 / FreeType License
Fontconfig	2.14.2+	MIT License
PulseAudio	16.1+	LGPL v2.1+
libxkbcommon	1.7.0+	MIT License

For detailed license compliance information and LGPL library linking details, see LICENSE.

---

Questions about licensing? Email us or open an issue.