From 0d0131d2b21f27c6c48fec571ad1dfa89a7c3e90 Mon Sep 17 00:00:00 2001 From: XTRM-Unraid Date: Sun, 1 Feb 2026 09:44:20 +0200 Subject: [PATCH] Add KVM switch documentation for Mac/Nobara setup - DDC/CI monitor switching (Dell U3821DW) - HID++ Logitech peripheral switching (MX Keys S, MX Master 3S) - Scripts for bidirectional switching - Troubleshooting guide and reference Co-Authored-By: Claude Opus 4.5 --- docs/wip/KVM-SWITCH-MAC-NOBARA.md | 177 ++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/wip/KVM-SWITCH-MAC-NOBARA.md diff --git a/docs/wip/KVM-SWITCH-MAC-NOBARA.md b/docs/wip/KVM-SWITCH-MAC-NOBARA.md new file mode 100644 index 0000000..7df93c3 --- /dev/null +++ b/docs/wip/KVM-SWITCH-MAC-NOBARA.md @@ -0,0 +1,177 @@ +# One-Key KVM: Mac ↔ Nobara + +**Status:** WIP - Scripts created, needs testing +**Hardware:** Dell U3821DW, MX Keys S, MX Master 3S +**Updated:** 2026-02-01 + +## Overview + +Software KVM solution to switch the Dell U3821DW ultrawide monitor and Logitech MX peripherals between Mac (MacBook Pro M3) and Nobara Linux using DDC/CI and HID++ commands. + +## Hardware Mapping + +### Monitor Inputs +| Input | Code | Port | Computer | +|-------|------|------|----------| +| USB-C | 27 | USB-C | Mac | +| HDMI 2 | 18 | HDMI 2 | Nobara | + +### Peripheral Channels +| Channel | Code | Connection | Computer | +|---------|------|------------|----------| +| 1 | 0x00 | Bluetooth | Mac | +| 2 | 0x01 | Logi Bolt USB | Nobara | + +### Devices +- **Monitor:** Dell U3821DW (38" Ultrawide, DDC/CI enabled) +- **Keyboard:** Logitech MX Keys S (Easy-Switch capable) +- **Mouse:** Logitech MX Master 3S (Easy-Switch capable) +- **Receiver:** Logi Bolt USB (PID: 046d:c548) + +## Prerequisites + +### Mac +```bash +# Install m1ddc (DDC control for Apple Silicon) +brew install m1ddc + +# Install hidapitester (HID control) +curl -sL https://github.com/todbot/hidapitester/releases/latest/download/hidapitester-macos-arm64.zip -o /tmp/hidapitester.zip +unzip -o /tmp/hidapitester.zip -d ~/bin/ +chmod +x ~/bin/hidapitester +``` + +### Nobara (Linux) +```bash +# Install ddcutil +sudo dnf install ddcutil + +# Add user to i2c group (requires reboot) +sudo usermod -aG i2c $USER + +# Install hidapitester +curl -sL https://github.com/todbot/hidapitester/releases/latest/download/hidapitester-linux-amd64.zip -o /tmp/hidapitester.zip +unzip -o /tmp/hidapitester.zip -d ~/bin/ +chmod +x ~/bin/hidapitester + +# Udev rule for non-root HID access +echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c548", MODE="0666"' | \ + sudo tee /etc/udev/rules.d/99-logitech-bolt.rules +sudo udevadm control --reload-rules && sudo udevadm trigger +``` + +## Scripts + +### Switch to Nobara (Run on Mac) +**Location:** `~/scripts/to_nobara.sh` + +```bash +#\!/bin/bash +# KVM Switch: Mac → Nobara +set -e + +echo "Switching to Nobara..." + +# Switch Monitor to HDMI 2 +m1ddc set input 18 + +# Switch Mouse to Bolt (Channel 2) +~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \ + --open --length 7 --send-output "0x10,0x01,0x09,0x1b,0x01,0x00,0x00" + +# Switch Keyboard to Bolt (Channel 2) +~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \ + --open --length 7 --send-output "0x10,0x02,0x09,0x1b,0x01,0x00,0x00" + +echo "Done\!" +``` + +### Switch to Mac (Run on Nobara) +**Location:** `~/scripts/to_mac.sh` + +```bash +#\!/bin/bash +# KVM Switch: Nobara → Mac +set -e + +echo "Switching to Mac..." + +# Switch Monitor to USB-C +ddcutil setvcp 60 27 + +# Switch Mouse to Bluetooth (Channel 1) +~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \ + --open --length 7 --send-output "0x10,0x01,0x09,0x1b,0x00,0x00,0x00" + +# Switch Keyboard to Bluetooth (Channel 1) +~/bin/hidapitester --vid 046d --pid c548 --usage 0x0001 --usagePage 0xff00 \ + --open --length 7 --send-output "0x10,0x02,0x09,0x1b,0x00,0x00,0x00" + +echo "Done\!" +``` + +## Keyboard Shortcuts + +### Mac (Logi Options+) +1. Logi Options+ → MX Keys S → Smart Actions +2. Create "KVM Switch" action +3. Trigger: F12 +4. Action: System → Open File → `~/scripts/to_nobara.sh` + +### Nobara (GNOME) +1. Settings → Keyboard → Custom Shortcuts +2. Command: `/home/USER/scripts/to_mac.sh` +3. Shortcut: F12 + +## Troubleshooting + +### Monitor doesn't switch +- **DDC/CI disabled:** Monitor Menu → Others → DDC/CI → On +- **USB-C hub blocking DDC:** Connect monitor directly to Mac USB-C port +- **Linux permissions:** Ensure user in `i2c` group, reboot after adding + +### Peripherals don't switch +- **Wrong device index:** The 0x01/0x02 values depend on Bolt pairing order + ```bash + # Find correct indices on machine with Bolt receiver + hidapitester --vid 046d --pid c548 --list-detail + ``` +- **Different Bolt PID:** Some receivers have different product IDs + ```bash + hidapitester --list | grep 046d + ``` + +### HID++ Command Reference +| Byte | Purpose | Values | +|------|---------|--------| +| 0x10 | Report ID (short) | Fixed | +| 0x01/0x02 | Device index | Mouse=0x01, Keyboard=0x02 (may vary) | +| 0x09 | Feature index | Change Host feature | +| 0x1b | Function | Set host | +| 0x00/0x01 | Channel | 0x00=Ch1, 0x01=Ch2, 0x02=Ch3 | + +## DDC Input Codes (Dell U3821DW) + +| Input | Code | Hex | +|-------|------|-----| +| DisplayPort 1 | 15 | 0x0F | +| DisplayPort 2 | 16 | 0x10 | +| HDMI 1 | 17 | 0x11 | +| HDMI 2 | 18 | 0x12 | +| USB-C | 27 | 0x1B | + +## Files Location + +Scripts are stored on Mac at `~/scripts/`: +- `to_nobara.sh` - Switch to Nobara (run on Mac) +- `to_mac.sh` - Switch to Mac (copy to Nobara) +- `debug_kvm.sh` - Diagnostic script +- `setup_nobara.sh` - Nobara setup script + +## TODO + +- [ ] Test monitor switching with DDC/CI enabled +- [ ] Verify Bolt receiver PID on Nobara +- [ ] Confirm device indices for keyboard/mouse +- [ ] Set up keyboard shortcuts on both machines +- [ ] Test bidirectional switching