Skip to content

OpenterfaceQT‐Linux‐Environment‐Setup

Jump to bottom
Kevin Peng edited this page Aug 21, 2026 · 4 revisions

This guide walks through setting up a Linux host to run (and optionally build) Openterface QT.

Supported Distributions

Distribution Version Architecture Notes
Ubuntu 22.04+ x64, ARM64 .deb and AppImage available
Debian 12+ x64, ARM64 .deb available
Fedora 42+ x64, ARM64 .rpm available
Linux Mint 21.3+ x64 .deb available
openSUSE Tumbleweed x64 .rpm available
Arch Linux Rolling x64, ARM64 ✅ Supported — native .pkg.tar.zst (see Arch Linux Installation)
Raspberry Pi OS 64-bit ARM64 ✅ Supported
Raspberry Pi OS 32-bit ARM32 ❌ Not supported (Qt too old)
NixOS 25.11+ x64, ARM64 Nix flake available

1. Install the Application

Three methods — pick the one that fits your needs:

Method Time Effort When to use
Pre-built binary ~30 s Minimal Most users — fastest & easiest
Build from source 5–30 min Medium Custom modifications needed
Manual package install Varies Higher Advanced users & troubleshooting

Option 1 — Pre-built Binary (Recommended)

Installs the latest release in ~30 seconds, no compilation:

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

To pin a specific version:

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

The script automatically:

  • Downloads the pre-built binary for your architecture (x86_64 / ARM64)
  • Installs runtime dependencies (Qt6, FFmpeg, USB libraries)
  • Configures device permissions (udev rules, user groups)
  • Creates desktop menu integration
  • Sets up a Qt environment wrapper (prevents "Qt platform plugin" errors)

Supported distros: Ubuntu/Debian (apt), Fedora/RHEL (dnf), openSUSE (zypper), Arch (pacman).

Option 2 — Flatpak (Sandboxed)

flatpak install flathub com.openterface.openterfaceQT
flatpak run com.openterface.openterfaceQT

If the Flatpak cannot see the device, grant full device access:

flatpak run --device=all com.openterface.openterfaceQT

The Flatpak uses the KDE 6.9 runtime (org.kde.Platform).

Option 3 — Nix / NixOS

The repo ships a Nix flake for reproducible builds and NixOS integration:

# Build
nix build github:TechxArtisanStudio/Openterface_QT
# Run
nix run github:TechxArtisanStudio/Openterface_QT
# Dev shell
nix develop github:TechxArtisanStudio/Openterface_QT

NixOS module — add to configuration.nix:

{
  inputs.openterface-qt.url = "github:TechxArtisanStudio/Openterface_QT";
  # ...
  imports = [ inputs.openterface-qt.nixosModules.default ];
  services.openterface-qt.enable = true;
}

The module installs the package, udev rules, and the dialout/video groups automatically.

Option 4 — Build from Source

See §4 Build from Source below.

Option 5 — Manual Package Install

For users who want full control:

  1. Download the .deb or .rpm from GitHub Releases.
  2. Install runtime dependencies (Ubuntu/Debian example):
sudo apt install -y \
    libqt6core6 libqt6dbus6 libqt6gui6 libqt6network6 \
    libqt6multimedia6 libqt6multimediawidgets6 libqt6serialport6 \
    libqt6widgets6 libqt6svg6 libgstreamer1.0-0 \
    libgstreamer-plugins-base1.0-0 libusb-1.0-0 libturbojpeg0

Ubuntu 24.04+ note: libturbojpeg0 was renamed to libturbojpeg. Use the new name on 24.04+.

  1. Install the package:
sudo dpkg -i openterface-qt_*.deb
sudo apt -f install   # resolve any missing deps

2. Device Permissions (Mandatory on Linux)

Linux enforces access control on every /dev node. Before the app can see the Mini-KVM, three things must be set up:

  1. udev rules for the hardware
  2. User group membership
  3. BRLTTY conflict resolved

One-command setup

This block covers V1/V2/V3 hardware, both serial chips, and BRLTTY. Paste it, then log out and back in.

# 1. Groups
sudo usermod -a -G dialout,video,uucp $USER

# 2. udev rules for all Openterface devices
sudo tee /etc/udev/rules.d/51-openterface.rules > /dev/null <<'EOF'
# V1 (534D:2109) — USB + hidraw
SUBSYSTEM=="usb",    ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", TAG+="uaccess"
# V2 (345F:2132, MS2130S) — USB + hidraw
SUBSYSTEM=="usb",    ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2132", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2132", TAG+="uaccess"
# V3 (345F:2109, MS2109S) — USB + hidraw
SUBSYSTEM=="usb",    ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2109", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2109", TAG+="uaccess"
# Serial CH341 / CH9329 (1A86:7523)
SUBSYSTEM=="usb",    ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"
SUBSYSTEM=="ttyUSB", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"
# Serial CH32V208 (1A86:FE0C)
SUBSYSTEM=="usb",    ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", TAG+="uaccess"
SUBSYSTEM=="ttyACM", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", TAG+="uaccess"
EOF

# 3. Apply rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# 4. Mask BRLTTY (it grabs USB serial/HID devices)
if systemctl list-units --full --all 2>/dev/null | grep -q brltty; then
    sudo systemctl mask brltty-udev.service 2>/dev/null || true
    sudo systemctl mask brltty.service 2>/dev/null || true
    sudo systemctl stop brltty-udev.service 2>/dev/null || true
    sudo systemctl stop brltty.service 2>/dev/null || true
fi

echo "✅ Done. Log out and back in, then re-plug the device."

Fallback for systems without systemd-logind (Docker, OpenRC, old RHEL/CentOS): replace TAG+="uaccess" with MODE="0666" in the rules above. This grants access to all local users — fine for single-user desktops, reconsider on multi-user systems.

What each piece does

Piece Purpose
dialout group Opens /dev/ttyUSB* / /dev/ttyACM* (serial port for keyboard/mouse)
video group Opens /dev/video* (UVC capture device)
uucp group Serial port ownership on Arch Linux
udev uaccess tag systemd-logind grants access to the logged-in user automatically
BRLTTY mask Stops the Braille TTY daemon from stealing the USB serial/HID interface

Group changes need a logout/login (or reboot). The udev rules apply immediately.

The CH341/CH32V208 serial chips use a kernel built-in driver — no separate driver install needed on any modern distro (kernel 4.x+).

Full details: Linux Permission Access.

3. Display Server — Wayland vs X11

Openterface QT runs on both. Qt auto-detects via QT_QPA_PLATFORM:

  • X11: QT_QPA_PLATFORM=xcb (default on most X11 desktops)
  • Wayland: QT_QPA_PLATFORM=wayland (default on GNOME/Fedora, KDE Plasma 6)

The GStreamer video overlay uses GstVideoOverlay, which embeds differently on X11 (XID) vs Wayland (protocol-dependent).

Known Wayland issues:

  • Video may fall back to XWayland if the GStreamer sink lacks native Wayland support
  • Some compositors mis-handle the video overlay window

If video display is broken on Wayland, force X11:

QT_QPA_PLATFORM=xcb openterfaceQT

4. Build from Source

Prerequisites by Distro

Ubuntu / Debian 
sudo apt-get update -y
sudo apt-get install -y \
    build-essential cmake \
    qt6-base-dev qt6-multimedia-dev qt6-serialport-dev qt6-svg-dev qt6-tools-dev \
    libusb-1.0-0-dev libudev-dev \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    pkg-config libx11-dev libxrandr-dev libxrender-dev \
    libexpat1-dev libfreetype6-dev libfontconfig1-dev libbz2-dev \
    libturbojpeg0-dev libva-dev \
    libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \
    libswresample-dev libswscale-dev ffmpeg libssl-dev

Ubuntu 24.04+: use libturbojpeg-dev instead of libturbojpeg0-dev.

Fedora / RHEL 
sudo dnf install -y \
    gcc gcc-c++ cmake \
    qt6-qtbase-devel qt6-qtmultimedia-devel qt6-qtserialport-devel \
    qt6-qtsvg-devel qt6-qttools-devel \
    libusb1-devel libudev-devel \
    gstreamer1-devel gstreamer1-plugins-base-devel \
    pkg-config libX11-devel libXrandr-devel libXrender-devel \
    libexpat-devel freetype-devel fontconfig-devel bzip2-devel \
    turbojpeg-devel libva-devel ffmpeg-devel openssl-devel

Fedora uses /usr/lib64 for libraries and /usr/include/ffmpeg/ for headers.

openSUSE 
sudo zypper install -y \
    cmake gcc-c++ \
    libQt6Base-devel libQt6Multimedia-devel libQt6SerialPort-devel \
    libQt6Svg-devel libQt6Tools-devel \
    libusb-1_0-devel libudev-devel \
    gstreamer-devel gstreamer-plugins-base-devel \
    pkg-config libX11-devel libXrandr-devel libXrender-devel \
    libexpat-devel freetype2-devel fontconfig-devel libbz2-devel \
    libjpeg8-devel libva-devel ffmpeg-devel libopenssl-devel

Build Steps

git clone https://github.com/TechxArtisanStudio/Openterface_QT.git
cd Openterface_QT
mkdir build && cd build

Configure for your distro:

Ubuntu/Debian (x64):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt6

Fedora/RHEL (x64):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib64/cmake/Qt6 \
    -DOPENTERFACE_BUILD_STATIC=OFF \
    -DUSE_SHARED_FFMPEG=ON \
    -DFFMPEG_PREFIX=/usr

openSUSE (x64):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib64/cmake/Qt6 \
    -DOPENTERFACE_BUILD_STATIC=OFF \
    -DUSE_SHARED_FFMPEG=ON \
    -DFFMPEG_PREFIX=/usr/lib64

ARM64 (Raspberry Pi, etc.):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib/aarch64-linux-gnu/cmake/Qt6 \
    -DOPENTERFACE_BUILD_STATIC=OFF \
    -DUSE_SHARED_FFMPEG=ON \
    -DFFMPEG_PREFIX=/usr/lib/aarch64-linux-gnu

Compile and install:

make -j$(nproc)
sudo make install

What gets installed:

  • Binary: /usr/local/bin/openterfaceQT
  • Desktop entry: /usr/share/applications/com.openterface.openterfaceQT.desktop
  • Icon: /usr/share/icons/hicolor/256x256/apps/com.openterface.openterfaceQT.png

Update the desktop database so the menu entry appears:

sudo update-desktop-database /usr/share/applications/ 2>/dev/null || true
sudo gtk-update-icon-cache -f /usr/local/share/icons/hicolor 2>/dev/null || true

Raspberry Pi Notes

  • Pi 4 or 5 recommended; 4 GB+ RAM for smooth video decoding.
  • Pi 3 works but has performance issues.
  • Use 64-bit Raspberry Pi OS; 32-bit is not supported (Qt is too old).
  • Hardware video decode via V4L2-M2M (VAAPI is Intel-only and not available on Pi).

Check available hardware accelerations:

ffmpeg -hwaccels

CMake Options Reference

Option Default Description
OPENTERFACE_BUILD_STATIC ON Link libraries statically where possible
USE_SHARED_FFMPEG OFF Use shared FFmpeg (.so) — required on Fedora/openSUSE
FFMPEG_PREFIX /opt/ffmpeg Path to FFmpeg install (headers + libs)
CMAKE_PREFIX_PATH (auto) Path to Qt6 CMake config

Full build docs: BUILD.md.

5. Troubleshooting

Keyboard / Mouse not responding

  1. Confirm the serial node exists: 
    ls /dev/ttyUSB* /dev/ttyACM*
  2. If missing, check for BRLTTY stealing the device: 
    systemctl status brltty
    Mask it if active (see §2).
  3. If present but Permission denied, rerun the one-command setup in §2 and log out/in.
  4. Try sudo openterfaceQT to confirm it is a permission issue, not a hardware one.

"Device or resource busy" on serial port

Almost always BRLTTY. Mask it:

sudo systemctl mask brltty-udev.service brltty.service
sudo systemctl stop brltty-udev.service brltty.service

Video capture shows nothing

  1. Verify the UVC device: 
    ls /dev/video*
  2. Check your user is in the video group: 
    groups $USER | grep -q video && echo ok
  3. On Wayland, try forcing X11: QT_QPA_PLATFORM=xcb openterfaceQT.

"Qt platform plugin 'xcb' could not be loaded"

Set the Qt plugin paths explicitly:

export QT_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt6/plugins
export QT_QPA_PLATFORM_PLUGIN_PATH=$QT_PLUGIN_PATH/platforms
export QT_QPA_PLATFORM=xcb
openterfaceQT

Adjust the path for your distro:

  • Fedora: /usr/lib64/qt6/plugins
  • openSUSE: /usr/lib64/qt6/plugins

CMake: FFmpeg libraries not found

✗ Missing: /opt/ffmpeg/lib/libavdevice.a
CMake Error at cmake/FFmpeg.cmake:322

The build defaults to /opt/ffmpeg. Most distros install FFmpeg system-wide. Use shared FFmpeg and point at the real path:

# Fedora
cmake .. -DUSE_SHARED_FFMPEG=ON -DFFMPEG_PREFIX=/usr

# Ubuntu/Debian
cmake .. -DUSE_SHARED_FFMPEG=ON -DFFMPEG_PREFIX=/usr/lib/x86_64-linux-gnu

Fedora provides FFmpeg headers in /usr/include/ffmpeg/ — -DFFMPEG_PREFIX=/usr (not /usr/lib64) so both headers and libs are found.

Related

footer

Clone this wiki locally