Add Solaar installation guide for RHEL 10

Document steps to install and run Solaar on RHEL 10, including troubleshooting and configuration for Logitech devices.

docs/RHEL.md

@@ -1 +1,225 @@
-RHEL Spork
+# Solaar on RHEL 10
+
+## Purpose
+
+This documents the steps required to get **Solaar** running on **RHEL 10** when the package is not available from the normal repositories.
+
+## Environment
+
+* OS: RHEL 10
+* Desktop: KDE Plasma on Wayland
+* Device class: Logitech Unifying Receiver
+* Example mouse: Logitech M720 Triathlon
+
+## Observed issue
+
+The following packages were not available from the configured repositories:
+
+```bash
+sudo dnf install solaar xbindkeys xdotool evtest
+```
+
+DNF returned package-not-found errors for those package names.
+
+## What worked
+
+### 1. Confirm the Logitech receiver is detected
+
+```bash
+lsusb | grep -i logitech
+```
+
+Expected output looked similar to this:
+
+```text
+Bus 001 Device 00X: ID 046d:c52b Logitech, Inc. Unifying Receiver
+```
+
+### 2. Install required base packages from RHEL and EPEL where available
+
+Install Python packaging support and device/input tooling first.
+
+```bash
+sudo dnf install python3 python3-pip git libinput evemu
+```
+
+Also install build and runtime pieces commonly needed for user-space input and HID tools.
+
+```bash
+sudo dnf install python3-devel gcc pkgconf-pkg-config gtk3 python3-gobject
+```
+
+Note: exact dependency resolution may vary depending on enabled repositories and what is already installed.
+
+### 3. Clone the Solaar repository
+
+```bash
+mkdir -p ~/dev-repos
+cd ~/dev-repos
+git clone https://github.com/pwr-Solaar/Solaar.git
+cd Solaar
+```
+
+### 4. Install Solaar to the user environment
+
+Install it into the user site-packages instead of system-wide.
+
+```bash
+python3 -m pip install --user .
+```
+
+If upgrading later from the fork or local checkout:
+
+```bash
+python3 -m pip install --user --upgrade .
+```
+
+### 5. Run Solaar directly from the user-local install path
+
+```bash
+~/.local/bin/solaar
+```
+
+For CLI inspection:
+
+```bash
+~/.local/bin/solaar show
+~/.local/bin/solaar config "M720 Triathlon Multi-Device Mouse"
+```
+
+### 6. Confirm the receiver and device are visible
+
+A working example:
+
+```bash
+~/.local/bin/solaar show
+```
+
+This displayed the Unifying Receiver and the M720 Triathlon, including battery state and configurable features.
+
+## Wayland note
+
+On KDE Wayland, Solaar prints a warning similar to:
+
+```text
+rules cannot access modifier keys in Wayland, accessing process only works on GNOME with Solaar Gnome extension installed
+```
+
+This does **not** prevent basic Solaar usage. It only means some rule-processing features are limited under Wayland, especially outside GNOME.
+
+## Device-specific issue seen with the M720
+
+`solaar show` triggered a traceback when trying to read host-name metadata from the M720 Triathlon:
+
+```text
+UnicodeDecodeError: 'utf-8' codec can't decode bytes in position 12-13: unexpected end of data
+```
+
+This appears related to Solaar parsing stored host information from the mouse, not to receiver detection itself.
+
+### Practical workaround
+
+Use targeted commands that still work, such as:
+
+```bash
+~/.local/bin/solaar config "M720 Triathlon Multi-Device Mouse"
+```
+
+This successfully showed configurable settings like:
+
+* scroll wheel direction
+* scroll wheel resolution
+* pointer speed
+* reprogrammable keys
+* persistent remappable keys
+* diversion settings
+
+## Verifying input behavior outside Solaar
+
+To inspect raw input events from the mouse, identify the correct `/dev/input/eventX` node for the mouse on your system and then run:
+
+```bash
+sudo libinput debug-events --device /dev/input/eventX
+```
+
+This confirmed the mouse was producing:
+
+* pointer motion
+* left and middle button events
+* scroll wheel events
+* horizontal wheel events
+* keyboard-style events for some remapped functions
+
+## keyd note
+
+A locally installed `keyd` binary may exist under `/usr/local/bin/keyd` if built from source or installed manually.
+
+If it is not available in the shell `PATH`, direct invocation may be required for monitoring:
+
+```bash
+sudo /usr/local/bin/keyd monitor
+```
+
+This can help verify that virtual keyboard and pointer events are being created and that remapped device actions are flowing through the input stack.
+
+## Recommended quality-of-life alias
+
+Add a shell alias so Solaar can be launched normally:
+
+```bash
+vi ~/.bashrc
+```
+
+Append:
+
+```bash
+alias solaar="$HOME/.local/bin/solaar"
+```
+
+Reload shell config:
+
+```bash
+source ~/.bashrc
+```
+
+Then launch with:
+
+```bash
+solaar
+```
+
+## Summary
+
+The working path on RHEL 10 was:
+
+1. Confirm the Logitech Unifying Receiver is visible with `lsusb`.
+2. Install Python and required development/runtime packages.
+3. Clone the Solaar repository.
+4. Install Solaar with `python3 -m pip install --user .`.
+5. Run Solaar from `~/.local/bin/solaar`.
+6. Use `solaar config "M720 Triathlon Multi-Device Mouse"` for stable device configuration.
+7. Use `libinput debug-events` and optionally `keyd monitor` to validate the input stack.
+
+## Commands used
+
+```bash
+lsusb | grep -i logitech
+mkdir -p ~/dev-repos
+cd ~/dev-repos
+git clone https://github.com/pwr-Solaar/Solaar.git
+cd Solaar
+python3 -m pip install --user .
+~/.local/bin/solaar
+~/.local/bin/solaar show
+~/.local/bin/solaar config "M720 Triathlon Multi-Device Mouse"
+sudo libinput debug-events --device /dev/input/eventX
+sudo /usr/local/bin/keyd monitor
+```
+
+## Caveats
+
+* Package availability in RHEL 10 repositories may differ from Fedora or Debian-based systems.
+* Wayland limits certain Solaar rule features.
+* `solaar show` may crash on some host-info metadata due to an upstream parsing issue.
+* Direct user-local execution from `~/.local/bin/solaar` may be required if no system package exists.
+* Replace example paths and event device numbers with the values on your own system.