Add troubleshooting guidance for Linux permission issues with SpaceMouse

Author: JakubAndrysek

README.md

@@ -73,6 +73,8 @@ The library uses `hidapi` as low-level interface to the device and `easyhid` as
             </pre>
             </details>
 
+        - **Note:** If you encounter "Failed to open device" errors, see the [Troubleshooting - Linux](./troubleshooting.md#linux) section for device-specific permission setup.
+
     - ### Windows
         - Install the latest release of hidapi.dll and hidapi.lib from
           the [hidapi releases](https://github.com/libusb/hidapi/releases) page.

troubleshooting.md

@@ -96,6 +96,72 @@ Read descriptor from the device (replace `<VID/PID>` with the VID/PID of your de
     Closing device
     ```
 
+<hr>
+
+## Linux
+
+### Failed to open device / Permission denied
+
+If you encounter an error like `Failed to open device` or `Permission denied` when trying to use your SpaceMouse on Linux, this is typically a permissions issue. Normal users don't have permission to access HID devices by default.
+
+**Error example:**
+```bash
+Traceback (most recent call last):
+  File "/home/user/.local/lib/python3.8/site-packages/pyspacemouse/pyspacemouse.py", line 183, in open
+    self.device.open()
+  File "/home/user/.local/lib/python3.8/site-packages/easyhid/easyhid.py", line 134, in open
+    raise HIDException("Failed to open device")
+easyhid.easyhid.HIDException: Failed to open device
+```
+
+**Solution:**
+
+1. **Find your device's Vendor ID and Product ID:**
+   ```bash
+   lsusb
+   ```
+   Look for your SpaceMouse device. Example output:
+   ```
+   Bus 001 Device 013: ID 256f:c652 3Dconnexion Universal Receiver
+   ```
+   Here, `256f` is the Vendor ID and `c652` is the Product ID.
+
+2. **Create udev rules to grant permissions:**
+   ```bash
+   cd /etc/udev/rules.d
+   sudo touch 99-spacemouse.rules
+   sudo nano 99-spacemouse.rules
+   ```
+
+3. **Add the following rules** (replace `046d` and `c62b` with your Vendor ID and Product ID):
+   ```bash
+   SUBSYSTEM=="input", GROUP="input", MODE="0660"
+   KERNEL=="hidraw*", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c62b", MODE="0666"
+   ```
+
+   Common SpaceMouse IDs:
+   - SpaceMouse Compact: `256f:c635`
+   - SpaceMouse Wireless: `256f:c62e`
+   - 3Dconnexion Universal Receiver: `256f:c652`
+   - SpaceNavigator: `046d:c626`
+
+4. **Reload udev rules:**
+   ```bash
+   sudo udevadm control --reload-rules
+   sudo udevadm trigger
+   ```
+
+5. **Add your user to the input group:**
+   ```bash
+   sudo usermod -a -G input $USER
+   ```
+
+6. **Disconnect and reconnect your SpaceMouse**, then log out and log back in to Ubuntu (or restart your computer).
+
+After these steps, your SpaceMouse should work correctly without permission errors.
+
+<hr>
+
 ## Windows
 
 !!! info "Error message - OSError: cannot load library 'hidapi.dll'"