bdDetect module
Support for braille display detection. This allows devices to be automatically detected and used when they become available, as well as providing utilities to query for possible devices for a particular driver. To support detection for a driver, devices need to be associated using the C{add*} functions. Drivers distributed with NVDA do this at the bottom of this module. For drivers in add-ons, this must be done in a global plugin.
- class bdDetect.DeviceType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
StrEnum
- HID = 'hid'
HID devices
- SERIAL = 'serial'
Serial devices (COM ports)
- CUSTOM = 'custom'
Devices with a manufacturer specific driver
- BLUETOOTH = 'bluetooth'
Bluetooth devices
- class bdDetect.DeviceMatch(type: DeviceType, id: str, port: str, deviceInfo: Dict[str, str])
Bases:
NamedTuple
Represents a detected device.
Create new instance of DeviceMatch(type, id, port, deviceInfo)
- type: DeviceType
The type of the device.
- id: str
The identifier of the device.
- port: str
The port that can be used by a driver to communicate with a device.
- deviceInfo: Dict[str, str]
All known information about a device.
- _asdict()
Return a new dict which maps field names to their values.
- _field_defaults = {}
- _fields = ('type', 'id', 'port', 'deviceInfo')
- classmethod _make(iterable)
Make a new DeviceMatch object from a sequence or iterable
- _replace(**kwds)
Return a new DeviceMatch object replacing specified fields with new values
- bdDetect.fallBackDevices: set[tuple[str, DeviceType, str]] = {}
Used to store fallback devices. When registered as a fallback device, it will be yielded last among the connected USB devices.
- bdDetect.scanForDevices = <extensionPoints.Chain object>
A Chain that can be iterated to scan for devices. Registered handlers should yield a tuple containing a driver name as str and DeviceMatch Handlers are called with these keyword arguments: @param usb: Whether the handler is expected to yield USB devices. @type usb: bool @param bluetooth: Whether the handler is expected to yield USB devices. @type bluetooth: bool @param limitToDevices: Drivers to which detection should be limited.
C{None} if no driver filtering should occur.
@type limitToDevices: Optional[List[str]]
- bdDetect._isDebug()
- bdDetect.getDriversForConnectedUsbDevices(limitToDevices: List[str] | None = None) Iterator[Tuple[str, DeviceMatch]]
Get any matching drivers for connected USB devices. Looks for (and yields) custom drivers first, then considers if the device is may be compatible with the Standard HID Braille spec. @param limitToDevices: Drivers to which detection should be limited.
C{None} if no driver filtering should occur.
@return: Generator of pairs of drivers and device information.
- bdDetect._getStandardHidDriverName() str
Return the name of the standard HID Braille device driver
- bdDetect._isHIDBrailleMatch(match: DeviceMatch) bool
- bdDetect.getDriversForPossibleBluetoothDevices(limitToDevices: List[str] | None = None) Iterator[Tuple[str, DeviceMatch]]
Get any matching drivers for possible Bluetooth devices. Looks for (and yields) custom drivers first, then considers if the device is may be compatible with the Standard HID Braille spec. @param limitToDevices: Drivers to which detection should be limited.
C{None} if no driver filtering should occur.
@return: Generator of pairs of drivers and port information.
- class bdDetect._DeviceInfoFetcher(*args, **kwargs)
Bases:
AutoPropertyObject
Utility class that caches fetched info for available devices for the duration of one core pump cycle.
- cachePropertiesByDefault = True
Specifies whether properties are cached by default; can be overridden for individual properties by setting _cache_propertyName. @type: bool
- property btDevsCache: List[Tuple[str, DeviceMatch]] | None
Type info for auto property: _get_btDevsCache
- _get_btDevsCache() List[Tuple[str, DeviceMatch]] | None
- _set_btDevsCache(cache: List[Tuple[str, DeviceMatch]] | None)
- comPorts: list[dict[str, str]]
Type info for auto property: _get_comPorts
- _get_comPorts() list[dict[str, str]]
- usbDevices: List[Dict]
Type info for auto property: _get_usbDevices
- _get_usbDevices() List[Dict]
- usbComPorts: list[dict[str, str]]
Type info for auto property: _get_usbComPorts
- _get_usbComPorts() list[dict[str, str]]
- hidDevices: List[Dict]
Type info for auto property: _get_hidDevices
- _get_hidDevices() List[Dict]
- _abc_impl = <_abc._abc_data object>
- class bdDetect._Detector
Bases:
object
Detector class used to automatically detect braille displays. This should only be used by the L{braille} module.
Constructor. After construction, a scan should be queued with L{queueBgScan}.
- _queueBgScan(usb: bool = False, bluetooth: bool = False, limitToDevices: List[str] | None = None)
Queues a scan for devices. If a scan is already in progress, a new scan will be queued after the current scan. To explicitely cancel a scan in progress, use L{rescan}. @param usb: Whether USB devices should be detected for this and subsequent scans. @param bluetooth: Whether Bluetooth devices should be detected for this and subsequent scans. @param limitToDevices: Drivers to which detection should be limited for this and subsequent scans.
C{None} if default driver filtering according to config should occur.
- _stopBgScan()
Stops the current scan as soon as possible and prevents a queued scan to start.
- static _bgScanUsb(usb: bool = True, limitToDevices: List[str] | None = None)
Handler for L{scanForDevices} that yields USB devices. See the L{scanForDevices} documentation for information about the parameters.
- static _bgScanBluetooth(bluetooth: bool = True, limitToDevices: List[str] | None = None)
Handler for L{scanForDevices} that yields Bluetooth devices and keeps an internal cache of devices. See the L{scanForDevices} documentation for information about the parameters.
- _bgScan(usb: bool, bluetooth: bool, limitToDevices: List[str] | None)
Performs the actual background scan. this function should be run on a background thread. @param usb: Whether USB devices should be detected for this particular scan. @param bluetooth: Whether Bluetooth devices should be detected for this particular scan. @param limitToDevices: Drivers to which detection should be limited for this scan.
C{None} if no driver filtering should occur.
- rescan(usb: bool = True, bluetooth: bool = True, limitToDevices: List[str] | None = None)
Stop a current scan when in progress, and start scanning from scratch. @param usb: Whether USB devices should be detected for this and subsequent scans. @type usb: bool @param bluetooth: Whether Bluetooth devices should be detected for this and subsequent scans. @type bluetooth: bool @param limitToDevices: Drivers to which detection should be limited for this and subsequent scans.
C{None} if default driver filtering according to config should occur.
- handleWindowMessage(msg=None, wParam=None)
- pollBluetoothDevices()
Poll bluetooth devices that might be in range. This does not cancel the current scan.
- terminate()
- bdDetect.getConnectedUsbDevicesForDriver(driver: str) Iterator[DeviceMatch]
Get any connected USB devices associated with a particular driver. @param driver: The name of the driver. @return: Device information for each device. @raise LookupError: If there is no detection data for this driver.
- bdDetect.getPossibleBluetoothDevicesForDriver(driver: str) Iterator[DeviceMatch]
Get any possible Bluetooth devices associated with a particular driver. @param driver: The name of the driver. @return: Port information for each port. @raise LookupError: If there is no detection data for this driver.
- bdDetect.driverHasPossibleDevices(driver: str) bool
Determine whether there are any possible devices associated with a given driver. @param driver: The name of the driver. @return: C{True} if there are possible devices, C{False} otherwise. @raise LookupError: If there is no detection data for this driver.
- bdDetect.driverSupportsAutoDetection(driver: str) bool
Returns whether the provided driver supports automatic detection of displays. @param driver: The name of the driver. @return: C{True} if de driver supports auto detection, C{False} otherwise.
- bdDetect.driverIsEnabledForAutoDetection(driver: str) bool
Returns whether the provided driver is enabled for automatic detection of displays. @param driver: The name of the driver. @return: C{True} if de driver is enabled for auto detection, C{False} otherwise.
- bdDetect.getSupportedBrailleDisplayDrivers(onlyEnabled: bool = False) Generator[Type[BrailleDisplayDriver], Any, Any]
- bdDetect.getBrailleDisplayDriversEnabledForDetection() Generator[str, Any, Any]
- bdDetect.initialize()
Initializes bdDetect, such as detection data. Calls to addUsbDevices, and addBluetoothDevices. Specify the requirements for a detected device to be considered a match for a specific driver.
- bdDetect.terminate()
- class bdDetect.DriverRegistrar(driver: str)
Bases:
object
An object to facilitate registration of drivers in the bdDetect system. It is instanciated for a specific driver and passed to L{braille.BrailleDisplayDriver.registerAutomaticDetection}.
- _driver: str
- _getDriverDict() defaultdict[DeviceType, set[str] | Callable[[DeviceMatch], bool]]
- addUsbDevices(type: DeviceType, ids: set[str], useAsFallBack: bool = False)
Associate USB devices with the driver on this instance. :param type: The type of the driver. :param ids: A set of USB IDs in the form C{“VID_xxxx&PID_XXXX”}.
Note that alphabetical characters in hexadecimal numbers should be uppercase.
- Parameters:
useAsFallBack –
A boolean flag to determine how USB devices are associated with the driver.
If False (default), the devices are added directly to the primary driver list for the specified type, meaning they are immediately available for use with the driver. If True, the devices are added to a fallback list and are used only if the primary driver cannot use the initial devices, serving as a backup option in case of compatibility issues. This provides flexibility and robustness in managing driver-device connections.
- Raises:
ValueError – When one of the provided IDs is malformed.
- addBluetoothDevices(matchFunc: Callable[[DeviceMatch], bool])
Associate Bluetooth HID or COM ports with the driver on this instance. @param matchFunc: A function which determines whether a given Bluetooth device matches.
It takes a L{DeviceMatch} as its only argument and returns a C{bool} indicating whether it matched.
- addDeviceScanner(scanFunc: Callable[[...], Iterable[Tuple[str, DeviceMatch]]], moveToStart: bool = False)
Register a callable to scan devices. This adds a handler to L{scanForDevices}. @param scanFunc: Callable that should yield a tuple containing a driver name as str and DeviceMatch.
The callable is called with these keyword arguments: @param usb: Whether the handler is expected to yield USB devices. @type usb: bool @param bluetooth: Whether the handler is expected to yield USB devices. @type bluetooth: bool @param limitToDevices: Drivers to which detection should be limited.
C{None} if no driver filtering should occur.
@type limitToDevices: Optional[List[str]]
- @param moveToStart: If C{True}, the registered callable will be moved to the start
of the list of registered handlers. Note that subsequent callback registrations may also request to be moved to the start. You should never rely on the registered callable being the first in order.