Troubleshooting

No devices appear

Work through these in order — the cause is almost always one of the first two.

1. Confirm the permission setup actually applied

getfacl -p /dev/hidraw0 | grep '^user:'

You should see an entry naming your username. If you only see user::rw- with no name, the ACL was not applied. Reinstall the rule:

sudo ./scripts/install-udev-rules.sh

2. Log out and back in

Group membership is established at login. If the installer just added you to the openlogi group, your current session does not have it yet.

To verify without logging out:

id -nG | tr ' ' '\n' | grep openlogi

If that prints nothing but getent group openlogi shows you as a member, you need a new session.

3. Check the device is visible to the kernel

ls -l /dev/hidraw*
sudo dmesg | grep -i logitech

A Logitech device with no hidraw node at all is a kernel or connection problem, not an OpenLogi one.

4. Confirm the device speaks HID++

Not every Logitech product does — some budget peripherals are plain HID with no vendor protocol. The probe reports this directly:

./target/release/logi-probe

Error messages

These come from OpenLogi's HID++ layer, and logi-probe prints them verbatim. What each one means:

permission denied opening /dev/hidrawN

The udev rule is missing, or your session started before it was installed. Install it, then log out and back in:

sudo ./scripts/install-udev-rules.sh

If the rule is installed and this persists, work through No devices appear from step 1.

No Logitech device answered.

The receiver or Bluetooth endpoint opened fine, but no device replied. The mouse or keyboard is switched off, out of range, asleep, or not paired to that receiver. Move or click it to wake it and run the probe again. To pair it, see Pairing a device.

timed out waiting for a reply from device N

A request reached the receiver but the device at index N did not answer in time — usually because it went to sleep or lost its connection mid-query. Wake the device and retry. If it happens every time on one device, file an issue with the probe output.

feature 0x2201 is not supported by this device

Not a fault: the device does not implement that HID++ feature (here, adjustable DPI), so OpenLogi cannot offer the matching setting. See Supported devices for what each feature unlocks.

Buttons do not respond after remapping

Check uinput is available

ls -l /dev/uinput

If the file does not exist, the module is not loaded:

sudo modprobe uinput

The installer writes /etc/modules-load.d/openlogi.conf so this persists across reboots. If that file is missing, create it:

echo uinput | sudo tee /etc/modules-load.d/openlogi.conf

If the file exists but the group is wrong, re-run the rule installer.

Check the control is actually divertable

Not every button can be diverted — the firmware decides. The probe lists which controls on your device support it:

./target/release/logi-probe watch 30

Press the buttons during the watch window. Anything that prints a notification is divertable; anything silent is not remappable on that device.

A button is dead and OpenLogi is closed

A diverted button sends no normal report, so if the application exits without restoring it, that button does nothing.

OpenLogi restores every diverted control on shutdown, including on SIGINT and SIGTERM. If it was killed with SIGKILL — which cannot be caught — the diversion survives. To clear it:

• Power-cycle the device (switch it off and on), or
• Start OpenLogi again and close it normally

Conflicts with Solaar

There should not be any. HID++ 2.0 requests carry a software id that the device echoes back, and OpenLogi uses a different one from Solaar and fwupd, so replies are matched to the program that asked.

If you do see erratic behaviour with both running, that is worth reporting — include which device, which connection type, and whether it also occurs with Solaar closed.

Settings do not survive a reboot

This is expected for host-side actions, and is the distinction described in Architecture.

• DPI is written to the device's flash and persists with OpenLogi closed.
• Button mappings to desktop actions, commands and URLs require OpenLogi to be running, because no firmware implements those concepts.

The application marks which is which.

Pairing a device with a receiver

OpenLogi configures devices that are already connected; it does not pair them. To pair a mouse or keyboard with a Bolt or Unifying receiver, use Solaar, which runs fine alongside OpenLogi. For Bluetooth, pair it through your desktop's Bluetooth settings or bluetoothctl. Once it is connected, OpenLogi picks it up.

Filing a useful bug report

Include the output of:

./target/release/logi-probe

That reports the device, its connection path, and its full capability list — which is the first thing anyone diagnosing the problem needs.

Issues: github.com/mohin7/openlogi/issues