Link to issue number:

closes #15196

Summary of the issue:

1. It is currently not possible to disable display drivers for automatic detection, other than the HID braille standard
2. There is no obvious way for add-on bundled braille display drivers to register themselves in automatic detection.

Description of user facing changes

1. In the braille display selection dialog, when automatic is selected, there is now an additional checklistbox that allows you to disable drivers. The disabled drivers are saved in config.
2. The advanced option for to disable HID braille has been removed. Users should use the new checklistbox instead. There is a config profile upgrade step to remember the user's decision about explicitly disabling HID.
3. It is now possible to select the HID braille driver manually when it is disabled for automatic detection. The old option in advanced setting disabled HID completely, i.e. the driver wasn't available for manual selection either.

Description of development approach

1. Added a registerAutomaticDetection classmethod to BrailleDisplayDriver. This method is called by bdDetect.initialize. The classmethod receives a bdDetect.DriverRegistrar that contains the following methods:
   • addUsbDevices: to register USB devices
   • addBluetoothDevices: To register bluetooth devices
   • addDeviceScanner: convenience method to register a handler to the scanForDevices extension point
2. Added a supportsAutomaticDetection boolean attribute on braille display drivers. This should be set to True for bdDetect to recognize the driver.
3. Removed the option from the config to enable/disable HID, instead rely on a new excludeDisplays lisst in the config that is populated by the new option in the braille display selection dialog. Note that exclusions are saved, not inclusions. This ensures that new drivers will be opt-out.
4. bdDetect.Detector._queueBgScan has a backwards compatible change for its limitToDevices parameter. When None, it falls back to the list of enabled drivers. When no drivers are disabled, it checks all drivers.
5. Logic from bdDetect.initialize() has been moved to the respective display drivers, calling the replacement methods on the driverRegistrar and omitting the name of the driver in the method call.

Testing strategy:

Performed the following tests:

• Ensured that my APH mantis 40 is detected using both USB and Bluetooth
• Ensured that mantis wouldn't be detected when explicitly disabled
• Ensured that a config profile switch would detect a new display if an earlier detected display is disabled in a new profile, ensuring the disabled entry would be respected
• Ensured that HID braille is properly disabled as part of the config profile upgrade step

Known issues with pull request:

None known

Change log entries:

New features

• When using automatic detection of braille displays, it is now possible to opt-out drivers from detection from the Braille display Selection dialog. (Allow add-on braille display drivers to opt in for auto detection #15196)
  Changes
• The advanced setting to enable support for HID braille has been removed in favor of the new option to disable specific drivers for braille display auto detection in the braille display selection dialog. (Allow add-on braille display drivers to opt in for auto detection #15196)
  For Developers
• Added official support to register custom braille display drivers in the automatic braille display detection process. Consult the braille.BrailleDisplayDriver class documentation for more details. Most notably, the supportsAutomaticDetection attribute must be set to True and the registerAutomaticDetection classmethod must be implemented. (Allow add-on braille display drivers to opt in for auto detection #15196)
  Deprecations
• bdDetect.addUsbDevices and bdDetect.addBluetoothDevices have been deprecated. Braille display drivers should implement the registerAutomaticDetection classmethod instead. That method receives a DriverRegistrar object on which the addUsbDevices and addBluetoothDevices methods can be used.
• The default implementation of the check method on BrailleDisplayDriver uses bdDetect.driverHasPossibleDevices for devices that are marked as thread safe. Starting from NVDA 2024.1, in order for the base method to use bdDetect.driverHasPossibleDevices, the supportsAutomaticDetection attribute must be set to True as well.

Code Review Checklist:

• Pull Request description:
  • description is up to date
  • change log entries
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• API is compatible with existing add-ons.
• Documentation:
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• Security precautions taken.