Improve error reporting. Specially when there is a lack of permissions.

Author: antoniovazquezblanco

src/usbbluetooth/__init__.py

@@ -6,5 +6,6 @@
 
 from .list_controllers import list_controllers
 from .controller import Controller
-from .wrong_driver_exception import WrongDriverException
-from .device_closed_exception import DeviceClosedException
+from .exception.device_closed_exception import DeviceClosedException
+from .exception.insufficient_permissions_exception import InsufficientPermissionsException
+from .exception.wrong_driver_exception import WrongDriverException

src/usbbluetooth/controller.py

@@ -6,8 +6,9 @@
 
 import usb
 from .hci_hdr_type import HciHdrType
-from .wrong_driver_exception import WrongDriverException
-from .device_closed_exception import DeviceClosedException
+from .exception.wrong_driver_exception import WrongDriverException
+from .exception.device_closed_exception import DeviceClosedException
+from .exception.insufficient_permissions_exception import InsufficientPermissionsException
 
 
 class Controller:
@@ -38,6 +39,14 @@ def open(self):
             # In windows, set_configuration is not implemented for devices not
             # running the correct driver, that should be WinUSB
             raise WrongDriverException()
+        except usb.core.USBError as e:
+            if e.errno == 13:
+                # This happens in Linux when the user has insufficient permissions
+                # to access the USB device
+                raise InsufficientPermissionsException()
+            else:
+                # This may be anything, report it to the user...
+                raise e
 
         # Find the Bluetooth interface of the usb device...
         self._interface_bt = usb.util.find_descriptor(
@@ -51,14 +60,16 @@ def open(self):
         try:
             if self._dev.is_kernel_driver_active(self._interface_bt.bInterfaceNumber):
                 # Detach the kernel driver
-                self._dev.detach_kernel_driver(self._interface_bt.bInterfaceNumber)
+                self._dev.detach_kernel_driver(
+                    self._interface_bt.bInterfaceNumber)
         except NotImplementedError:
             # In windows, is_kernel_driver_active and detach_kernel_driver are
             # not implemented
             pass
 
         # Claim the interface
-        usb.util.claim_interface(self._dev, self._interface_bt.bInterfaceNumber)
+        usb.util.claim_interface(
+            self._dev, self._interface_bt.bInterfaceNumber)
 
         # Get the relevant endpoints
         self._ep_events = usb.util.find_descriptor(

src/usbbluetooth/device_closed_exception.py renamed to src/usbbluetooth/exception/device_closed_exception.py

@@ -9,8 +9,6 @@ class DeviceClosedException(Exception):
     """Exception raised when interacting with a closed device."""
 
     def __init__(self):
-        super().__init__("The device you are trying to interact with has not "
-                         "been opened. Please, call the open() function "
-                         "before reading or writing to a device. "
-                         "Alternatively, use the `with` syntax to open and "
-                         "close the device.")
+        super().__init__("The device you are trying to interact with has not been opened. Please, call the open() "
+                         "function before reading or writing to a device. Alternatively, use the `with` syntax to open "
+                         "and close the device.")

src/usbbluetooth/exception/insufficient_permissions_exception.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+#
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: 2025 Antonio Vázquez Blanco <antoniovazquezblanco@gmail.com>
+#
+
+
+class InsufficientPermissionsException(Exception):
+    """Exception raised when trying to access a device with insufficient permissions."""
+
+    def __init__(self):
+        super().__init__("Current user has insufficient permissions to access this device. Please, visit "
+                         "https://usbbluetooth.github.io/quirks/ for more information. Depending on your operating "
+                         "system, you might need to set up udev rules or run this program with elevated privileges.")

src/usbbluetooth/wrong_driver_exception.py renamed to src/usbbluetooth/exception/wrong_driver_exception.py

@@ -9,8 +9,6 @@ class WrongDriverException(Exception):
     """Exception raised when trying to access a device with wrong driver."""
 
     def __init__(self):
-        super().__init__("The device you are trying to interact with is not "
-                         "accessible. This is most likely because it is being "
-                         "controlled by the wrong driver. In Windows, please "
-                         "use Zadig to change the driver of your device to "
-                         "WinUSB.")
+        super().__init__("The device you are trying to interact with is not accessible. This is most likely because it "
+                         "is being controlled by the wrong driver. In Windows, please use Zadig to change the driver "
+                         "of your device to WinUSB.")