Allow excluding display drivers from automatic detection

[LeonarddeR]

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.

[AppVeyorBot]

• PASS: Translation comments check.
• FAIL: Unit tests. See test results for more information.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/xfkurf1tp9b0m36d/artifacts/output/nvda_snapshot_pr15200-28774,0655eef6.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.8,
  INSTALL_END 0.8,
  BUILD_START 0.0,
  BUILD_END 24.2,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 19.9,
  FINISH_END 0.1

See test results for failed build of commit 0655eef6e9

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/bap2vr3g3rbs3ii7/artifacts/output/nvda_snapshot_pr15200-28775,b8f389c9.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.9,
  INSTALL_END 1.0,
  BUILD_START 0.0,
  BUILD_END 26.2,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 20.5,
  FINISH_END 0.1

See test results for failed build of commit b8f389c94c

[LeonarddeR]

It looks like #15208 also changed model names in the comments in bdDetect.py. I don't think that was a desirable change, therefore I left the dots in tact when fixing merge conflicts, effectively reverting that change.

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/n1jebllh26ripa5t/artifacts/output/nvda_snapshot_pr15200-28792,7007bf6d.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 1.2,
  INSTALL_END 0.9,
  BUILD_START 0.0,
  BUILD_END 25.0,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 22.5,
  FINISH_END 0.1

See test results for failed build of commit 7007bf6dcb

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/sf76jl68c4jrib8l/artifacts/output/nvda_snapshot_pr15200-28812,088dfaef.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.9,
  INSTALL_END 0.9,
  BUILD_START 0.0,
  BUILD_END 25.5,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 19.8,
  FINISH_END 0.1

See test results for failed build of commit 088dfaef14

[seanbudd]

@michaelDCurran - this and the issue #15196 still need a product decision

[seanbudd]

Thanks @LeonarddeR for taking on this large project

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: Unit tests.
• PASS: Lint check.
• FAIL: System tests (tags: installer NVDA). See test results for more information.
• Build (for testing PR): https://ci.appveyor.com/api/buildjobs/2dm17vcbe1lq0qtx/artifacts/output/nvda_snapshot_pr15200-29032,45bceb0d.exe
• CI timing (mins):
  INIT 0.0,
  INSTALL_START 0.9,
  INSTALL_END 0.9,
  BUILD_START 0.0,
  BUILD_END 26.6,
  TESTSETUP_START 0.0,
  TESTSETUP_END 0.3,
  TEST_START 0.0,
  TEST_END 20.6,
  FINISH_END 0.1

See test results for failed build of commit 45bceb0d43

[Qchristensen]

User guide looks good, thanks!

[bramd]

The config migration seems to fail. When trying to update from a previous alpha build, I get:

Traceback (most recent call last):
  File "config\__init__.pyc", line 571, in _initBaseConf
  File "config\__init__.pyc", line 605, in _loadConfig
  File "config\__init__.pyc", line 601, in _loadConfig
  File "config\profileUpgrader.pyc", line 24, in upgrade
  File "config\profileUpgrader.pyc", line 41, in _doConfigUpgrade
  File "config\profileUpgradeSteps.pyc", line 368, in upgradeConfigFrom_10_to_11
  File "configobj\__init__.pyc", line 508, in __getitem__
KeyError: 'excludedDisplays'