RomanNum3ral
/
Solaar
mirror of https://github.com/pwr-Solaar/Solaar.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve RHEL installation guide and add automated install example (#3162) 

* Improve RHEL installation guide and add automated install example

* docs: fix RHEL guide formatting and pre-commit style
This commit is contained in:
Grant Scott Turner 2026-03-10 07:43:25 -04:00 committed by GitHub
parent 4525704793
commit 940aae1be1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 124 additions and 194 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
RHEL.md
View File

@ -1,245 +1,175 @@
# Solaar on RHEL 10 # Solaar installation guide for RHEL, Rocky, AlmaLinux, and CentOS Stream
## Purpose This guide covers manual installation and an automated install example for
RHEL-family systems using `dnf`.
This documents the steps required to get **Solaar** running on **RHEL 10** when the package is not available from the normal repositories. ## Supported distributions
## Environment - Red Hat Enterprise Linux (RHEL)
- Rocky Linux
- AlmaLinux
- Oracle Linux
- CentOS Stream
* OS: RHEL 10 The commands assume a minimal CLI system with `sudo` access.
* Desktop: KDE Plasma on Wayland
* Device class: Logitech Unifying Receiver
* Example mouse: Logitech M720 Triathlon
## Observed issue ## 1) Install dependencies
The following packages were not available from the configured repositories:
```bash ```bash
sudo dnf install solaar xbindkeys xdotool evtest sudo dnf makecache --refresh
sudo dnf install -y \
git \
gtk3 \
python3 \
python3-devel \
python3-dbus \
python3-gobject \
python3-pip \
python3-psutil \
python3-pyudev \
python3-setuptools \
python3-xlib \
python3-yaml
``` ```
DNF returned package-not-found errors for those package names. Optional troubleshooting helpers:
## What worked
### 1. Confirm the Logitech receiver is detected
```bash ```bash
lsusb | grep -i logitech sudo dnf install -y \
evemu \
libinput \
usbutils
``` ```
Expected output looked similar to this: ## 2) Clone Solaar
```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 ```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 git clone https://github.com/pwr-Solaar/Solaar.git
cd Solaar cd Solaar
``` ```
### 4. Install Solaar to the user environment ## 3) Install Solaar
Install it into the user site-packages instead of system-wide. Install for the current user:
```bash ```bash
python3 -m pip install --user . python3 -m pip install --user .
``` ```
If upgrading later from the fork or local checkout: Or install system-wide:
```bash ```bash
python3 -m pip install --user --upgrade . sudo python3 -m pip install .
``` ```
### 5. Run Solaar directly from the user-local install path ## 4) Install udev rules
Install the recommended `uinput` rule:
```bash ```bash
~/.local/bin/solaar sudo make install_udev_uinput
``` ```
For CLI inspection: Verify rule installation:
```bash ```bash
~/.local/bin/solaar show ls -l /etc/udev/rules.d/42-logitech-unify-permissions.rules
~/.local/bin/solaar config "M720 Triathlon Multi-Device Mouse"
``` ```
### 6. Confirm the receiver and device are visible Rollback udev rule installation:
A working example:
```bash ```bash
~/.local/bin/solaar show sudo make uninstall_udev
``` ```
This displayed the Unifying Receiver and the M720 Triathlon, including battery state and configurable features. ## 5) Run Solaar
## Automated installer script
A guided installer script is included in this repository and automates the RHEL workflow in this document while prompting before each major action.
Run it from the Solaar checkout:
```bash
./tools/install-rhel.sh
```
The script can:
* check for Logitech receiver visibility with `lsusb`
* install required packages with `dnf`
* create the checkout directory and clone/update Solaar
* install Solaar with `python3 -m pip install --user`
* optionally add a Bash alias for `solaar`
* optionally run `solaar show`, `solaar config`, `libinput debug-events`, and `keyd monitor`
* write a timestamped evidence log in `~/.local/state/solaar/`
## 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 ```bash
solaar solaar
``` ```
## Summary or:
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 ```bash
lsusb | grep -i logitech python3 -m solaar
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 ## 6) Automated install options
* Package availability in RHEL 10 repositories may differ from Fedora or Debian-based systems. Use the guided installer in this repository:
* Wayland limits certain Solaar rule features.
* `solaar show` may crash on some host-info metadata due to an upstream parsing issue. ```bash
* Direct user-local execution from `~/.local/bin/solaar` may be required if no system package exists. ./tools/install-rhel.sh
* Replace example paths and event device numbers with the values on your own system. ```
Minimal non-interactive example script:
```bash
cat > install-rhel-solaar.sh <<'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
if [[ "${EUID}" -eq 0 ]]; then
echo "Run as a regular user with sudo access, not as root."
exit 1
fi
sudo dnf makecache --refresh
sudo dnf install -y \
git \
gtk3 \
python3 \
python3-devel \
python3-dbus \
python3-gobject \
python3-pip \
python3-psutil \
python3-pyudev \
python3-setuptools \
python3-xlib \
python3-yaml
if [[ ! -d Solaar/.git ]]; then
git clone https://github.com/pwr-Solaar/Solaar.git
fi
cd Solaar
python3 -m pip install --user .
sudo make install_udev_uinput
~/.local/bin/solaar --version
SCRIPT
chmod +x install-rhel-solaar.sh
./install-rhel-solaar.sh
```
## 7) Verification
```bash
command -v solaar
solaar --version
python3 -m pip show solaar
```
If installed with `--user`, ensure `~/.local/bin` is on your `PATH`:
```bash
echo "$PATH" | tr ':' '\n' | grep -Fx "$HOME/.local/bin" >/dev/null || \
echo 'Add ~/.local/bin to PATH'
```
## 8) Troubleshooting
Receiver not detected:
```bash
lsusb | grep -Ei 'logitech|046d'
sudo udevadm trigger
```
Check access to hidraw devices:
```bash
ls -l /dev/hidraw*
getfacl /dev/hidraw* 2>/dev/null | sed -n '1,80p'
```