-
Notifications
You must be signed in to change notification settings - Fork 35
Linux permission access
Copy and paste the entire block below into your Linux terminal. It will grant all device permissions needed for Openterface Mini-KVM (works for V1/V2/V3 hardware, serial CH341/CH32V208, plus HID and video capture devices).
# ── Openterface Linux Permission Setup ──
# Run once after plugging in the device. Log out & back in after.
# 1. Add yourself to required groups (serial, video, Arch-compat)
sudo usermod -a -G dialout,video,uucp $USER
# 2. Write udev rules for ALL Openterface devices
sudo tee /etc/udev/rules.d/51-openterface.rules > /dev/null <<'EOF'
# Openterface 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"
# Openterface 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"
# Openterface 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) — USB + ttyUSB
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"
SUBSYSTEM=="ttyUSB", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TAG+="uaccess"
# Serial CH32V208 (1A86:FE0C) — USB + ttyACM
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", TAG+="uaccess"
SUBSYSTEM=="ttyACM", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", TAG+="uaccess"
EOF
# 3. Apply rules immediately
sudo udevadm control --reload-rules
sudo udevadm trigger
# 4. Mask BRLTTY if present (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
echo "✓ BRLTTY services masked and stopped"
fi
# 5. Reminder
echo ""
echo "✅ udev rules installed and applied."
echo "➡️ Now log out and back in (or reboot) for group changes to take effect."
echo "➡️ Then re-plug the Openterface device and launch the app."| Step | Effect |
|---|---|
usermod -a -G dialout,video,uucp |
Grants serial port, video capture, and Arch-compatible group access |
| udev rules for all 5 device VID/PID pairs | Covers V1, V2, V3, CH341, CH32V208 across usb + hidraw + ttyUSB + ttyACM subsystems |
udevadm reload + trigger |
Applies rules immediately without reboot |
| BRLTTY mask + stop | Prevents the Braille TTY daemon from stealing USB device access |
Note: Group changes (
dialout,video,uucp) only take effect after logging out and back in. A full system restart is also safe. The udev rules apply immediately and do not require a restart.
If the command above did not grant device access (e.g., on systems without systemd-logind, older distributions, or containerized environments), use the alternative MODE="0666" approach instead. This sets world read-write permissions on the device nodes, which works on every Linux system.
⚠️ Security note:MODE="0666"grants all local users (not just the logged-in user) full access to these devices. This is safe for single-user desktop machines but should be reconsidered on multi-user servers.
# ── Openterface Linux Permission Setup (0666 fallback) ──
# 1. Add yourself to required groups (serial, video, Arch-compat)
sudo usermod -a -G dialout,video,uucp $USER
# 2. Write udev rules with MODE="0666" for universal access
sudo tee /etc/udev/rules.d/51-openterface.rules > /dev/null <<'EOF'
# Openterface V1 (534D:2109)
SUBSYSTEM=="usb", ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="534d", ATTRS{idProduct}=="2109", MODE="0666"
# Openterface V2 (345F:2132, MS2130S)
SUBSYSTEM=="usb", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2132", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2132", MODE="0666"
# Openterface V3 (345F:2109, MS2109S)
SUBSYSTEM=="usb", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2109", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="345f", ATTRS{idProduct}=="2109", MODE="0666"
# Serial CH341 / CH9329 (1A86:7523)
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE="0666"
SUBSYSTEM=="ttyUSB", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE="0666"
# Serial CH32V208 (1A86:FE0C)
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", MODE="0666"
SUBSYSTEM=="ttyACM", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="fe0c", MODE="0666"
EOF
# 3. Apply rules immediately
sudo udevadm control --reload-rules
sudo udevadm trigger
# 4. Mask BRLTTY if present
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
echo "✓ BRLTTY services masked and stopped"
fi
# 5. Reminder
echo ""
echo "✅ udev rules (MODE=0666) installed and applied."
echo "➡️ Now log out and back in (or reboot) for group changes to take effect."
echo "➡️ Then re-plug the Openterface device and launch the app."| Symptom | Likely cause | Use fallback? |
|---|---|---|
| Device still shows "Permission denied" after the first setup | System uses non-systemd init (OpenRC, runit, etc.) | ✅ Yes |
| Running in a Docker container or chroot | No systemd-logind daemon | ✅ Yes |
| On older enterprise distros (RHEL/CentOS 6 era) |
uaccess tag not supported |
✅ Yes |
| Single-user desktop running Ubuntu 20.04+, Fedora, Arch |
uaccess works fine |
❌ No need |
Tip: After running either setup, re-plug the device and check that
/dev/hidraw*and/dev/ttyUSB*or/dev/ttyACM*nodes exist with the correct permissions before launching the app.
Unlike Windows, Linux enforces strict access control on every hardware device node under /dev. A user-space application like Openterface QT cannot simply talk to USB devices — the kernel requires explicit permission at multiple layers. Without proper permissions, the application will either fail silently, report "access denied" errors, or be unable to discover the device entirely.
Openterface QT communicates with three categories of hardware, each requiring its own permission pathway:
| Hardware Category | Device Node | Why It Is Needed |
|---|---|---|
| HID Capture Card | /dev/hidraw* |
Reads video capture input signal status, detects resolution/refresh rate via HID reports, and sends HDMI switching commands to the device. The Openterface Mini-KVM presents itself as a custom HID device to the host PC — without hidraw access, the application cannot identify which chip is connected (MS2109/MS2109S/MS2130S), read register values, or perform firmware updates. |
| Serial Port (Keyboard/Mouse Emulator) |
/dev/ttyUSB*, /dev/ttyACM*
|
The Openterface device emulates a USB keyboard and mouse to send keystrokes/mouse actions to the target machine being controlled. The serial port is the channel through which HID keyboard scan codes and mouse movement data are sent to the KVM hardware. Without serial port access, keyboard and mouse control over the remote machine is completely non-functional. |
| Video Capture (Camera) | /dev/video* |
The Openterface Mini-KVM also functions as a UVC (USB Video Class) webcam — it captures the HDMI signal from the target machine and presents it as a video stream to the host PC. Linux exposes UVC cameras as /dev/video* nodes, and only users in the video group (or those granted access via udev TAG+="uaccess") can read from them. Without video device permission, the live screen preview shows nothing. |
Additionally, one software conflict must be managed:
| Conflict Source | Why It Interferes |
|---|---|
| BRLTTY (Braille TTY daemon) | BRLTTY is a screen-reader service that aggressively claims USB serial and HID devices to drive Braille displays. When active, it detaches the device from the kernel driver and re-opens it exclusively, preventing Openterface QT from accessing the serial port or HID interface. The service is installed by default on many Linux distributions as part of desktop accessibility packages. |
Openterface QT uses three complementary mechanisms to ensure the application has access to all required devices.
What it does: Creates persistent rules that tell the Linux device manager (udev) to automatically grant access to specific USB devices when they are plugged in.
How it works: When a USB device matching a defined VID/PID combination is connected, udev applies the TAG+="uaccess" tag, which instructs systemd-logind to grant read/write access to the currently logged-in local user. This is the modern, recommended approach — it does not require the user to be root or to manually manage group memberships.
Scope of rules: Rules are written for both the usb subsystem (raw USB access via libusb) and the device-specific subsystems (hidraw for HID, ttyUSB/ttyACM for serial).
Where rules are installed:
- At runtime: generated by the application's Environment Setup dialog →
/etc/udev/rules.d/51-openterface.rules - At install time: written by the DEB postinst script and the install-linux.sh script
Critical gap: The install-time scripts only contain rules for the original V1 device and the older CH341 serial chip. Rules for V2 (345F:2132), V3 (345F:2109), and the newer CH32V208 serial chip (1A86:FE0C) are missing from the DEB postinst, install-linux.sh, and there is no RPM spec udev installation at all.
What it does: Adds the current user to system groups that own device nodes.
| Group | Devices Covered | Why Needed |
|---|---|---|
dialout |
/dev/ttyUSB*, /dev/ttyACM*
|
These serial device nodes are owned by the dialout group. Without membership, the user cannot open the serial port to send keyboard/mouse commands. |
video |
/dev/video* |
Video capture device nodes are owned by the video group. Without membership, the user cannot open the UVC camera to view the target screen. |
uucp |
/dev/ttyUSB* (Arch Linux) |
Some Arch Linux-based distributions use uucp instead of dialout for serial device ownership. |
Note: Group membership takes effect only after the user logs out and logs back in (or restarts the system).
When the application starts (or when the user opens the Environment Setup dialog), it performs live checks to verify that all devices are accessible:
| Check | Method | What It Verifies |
|---|---|---|
| Serial Permission | Attempts to open each known serial device (1A86:7523, 1A86:FE0C) via libusb | Confirms the user can access the serial port for keyboard/mouse emulation |
| HID Permission | Attempts to open each known Openterface capture card (534D:2109, 345F:2109, 345F:2132) via libusb | Confirms the user can access the HID interface for chip detection, register reads, and firmware updates |
| HID Device File Permission | Checks read/write permissions on /dev/hidraw* devices and verifies udev rule files exist |
Confirms the kernel device node is accessible at the filesystem level |
| Video Permission | Checks read/write permissions on /dev/video* devices and verifies udev rule files exist |
Confirms the camera capture device is accessible |
| BRLTTY Detection | Queries systemd for active brltty services and checks for running brltty processes | Detects if BRLTTY is active and likely blocking device access |
| CH341 Driver | Checks /proc/modules for loaded ch341 kernel module |
Verifies the serial chip driver is loaded in the kernel |
If any check fails, the Environment Setup dialog displays the specific failure and provides copy-paste shell commands to fix it.
Important clarification: The CH341 (CH9329) and CH32V208 serial chips used in Openterface devices do not require installing a separate driver on modern Linux systems.
The Linux kernel has included a built-in ch341 serial driver (drivers/usb/serial/ch341.c) since kernel version 3.x. When an Openterface device is plugged in:
- The kernel's USB subsystem recognizes the VID:PID (1A86:7523 for CH341, 1A86:FE0C for CH32V208)
- The built-in
ch341module automatically binds to the device - A
/dev/ttyACM*or/dev/ttyUSB*device node is created - The device is immediately usable — provided the user has the correct group membership (
dialout/uucp) and udev permissions
The application's Environment Setup dialog offers to extract and build an out-of-tree CH341 driver source as a legacy fallback for older kernels. However, for any reasonably modern Linux distribution (kernel 4.x+), this is unnecessary.
The only situation where the built-in driver may not work: Some very old or minimal kernel configurations may not have CONFIG_USB_SERIAL_CH341 enabled. In those cases, the bundled out-of-tree driver source can be compiled and loaded manually.
| Hardware Version | Vendor ID | Product ID | Chip Type | Video Chip ID |
|---|---|---|---|---|
| V1 (Original) | 0x534D | 0x2109 | MS2109 | VideoChipType::MS2109 |
| V2 | 0x345F | 0x2132 | MS2130S | VideoChipType::MS2130S |
| V3 | 0x345F | 0x2109 | MS2109S | VideoChipType::MS2109S |
footer