Unstable auto detect for Humanware Brailliant and APH Mantis Q40 braille displays

[LeonarddeR]

Steps to reproduce:

1. Pair a Mantis Q40 over Bluetooth
2. Start NVDA with braille auto detection enabled.

Actual behavior:

NVDA sometimes fails detecting the display, because it tries the HID prottocol driver first. This driver reports as available but is not supported by the display. Interesting enough, as soon as you select the HID driver manually, NVDA connects to the display but the displays stays empty. When you open the display dialog again, nothing is selected and the HID driver disappeared.
Note that sometimes, NVDA manages to connect to the display with the Brailliant driver, but behavior is pretty instable on my system.

Expected behavior:

Direct connection using the Brailliant driver when using auto detect.

System configuration

NVDA installed/portable/running from source:

Installed

NVDA version:

2021.3

Windows version:

Windows 11 22000.348

Other questions

Does the issue still occur after restarting your computer?

Yes

Have you tried any other versions of NVDA? If so, please report their behaviors.

Same behavior as current Alpha.

If NVDA add-ons are disabled, is your problem still occurring?

Yes

Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

Yes

[LeonarddeR]

note, issues with the Brailliant were reported by @dkager. They have the same firmware under the hood.

[dkager]

Thanks for reporting this. I can confirm the problem also occurs when you select Bluetooth as the port, rathern than Auto. USB works as usual. Might the Chameleon 20 also be affected?

[LeonarddeR]

Might the Chameleon 20 also be affected?

Likely, isn't that just a rebranded Brailliant?

[feerrenrut]

@LeonarddeR and @dkager could you please test and confirm this is fixed in the RC for 2021.3.1 https://www.nvaccess.org/post/nvda-2021-3-1rc1/

[LeonarddeR]

Yes, this works fine for me.

[dkager]

Not for me unfortunately (Brailliant BI 40X). Here is the log of me trying a couple of times, with various errors:

INFO - braille.BrailleHandler.setDisplayByName (20:14:33.330) - braille._BgThread (6540):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - brailleDisplayDrivers.hid.BrailleDisplayDriver.__init__ (20:14:33.330) - braille._BgThread (6540):
Found display with 40 cells connected via hid (\\?\hid#{00001124-0000-1000-8000-00805f9b34fb}_vid&00021d6b_pid&0246&col02#8&f2c30de&0&0001#{4d1e55b2-f16f-11cf-88cb-001111000030})
INFO - braille.BrailleHandler.setDisplayByName (20:14:33.346) - braille._BgThread (6540):
Loaded braille display driver hid, current display has 40 cells.
ERROR - unhandled exception (20:14:39.662) - braille._BgThread (6540):
Traceback (most recent call last):
  File "_ctypes/callbacks.c", line 232, in 'calling callback function'
  File "hwIo\base.pyc", line 144, in _ioDone
OSError: [WinError 1167] The device is not connected.
ERROR - braille.executor (20:14:52.897) - braille._BgThread (6540):
Error displaying cells. Disabling display
Traceback (most recent call last):
  File "braille.pyc", line 2233, in executor
  File "brailleDisplayDrivers\hid.pyc", line 196, in display
  File "hwIo\base.pyc", line 111, in write
OSError: [WinError 1167] The device is not connected.
ERROR - braille.BrailleHandler.handleDisplayUnavailable (20:14:52.897) - braille._BgThread (6540):
Braille display unavailable. Disabling
Traceback (most recent call last):
  File "braille.pyc", line 2233, in executor
  File "brailleDisplayDrivers\hid.pyc", line 196, in display
  File "hwIo\base.pyc", line 111, in write
OSError: [WinError 1167] The device is not connected.
INFO - braille.BrailleHandler.setDisplayByName (20:14:52.913) - braille._BgThread (6540):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - braille.BrailleHandler.setDisplayByName (20:14:54.350) - braille._BgThread (6540):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - brailleDisplayDrivers.hid.BrailleDisplayDriver.__init__ (20:14:54.350) - braille._BgThread (6540):
Found display with 40 cells connected via hid (\\?\hid#{00001124-0000-1000-8000-00805f9b34fb}_vid&00021d6b_pid&0246&col02#8&f2c30de&0&0001#{4d1e55b2-f16f-11cf-88cb-001111000030})
INFO - braille.BrailleHandler.setDisplayByName (20:14:54.350) - braille._BgThread (6540):
Loaded braille display driver hid, current display has 40 cells.
INFO - brailleDisplayDrivers.brailliantB.BrailleDisplayDriver.__init__ (20:15:05.021) - MainThread (2152):
Found display with 40 cells connected via hid (\\?\hid#{00001124-0000-1000-8000-00805f9b34fb}_vid&00021d6b_pid&0246&col01#8&f2c30de&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030})
INFO - braille.BrailleHandler.setDisplayByName (20:15:05.021) - MainThread (2152):
Loaded braille display driver brailliantB, current display has 40 cells.
ERROR - braille.executor (20:15:10.641) - braille._BgThread (6540):
Error displaying cells. Disabling display
Traceback (most recent call last):
  File "braille.pyc", line 2233, in executor
  File "brailleDisplayDrivers\brailliantB.pyc", line 240, in display
  File "hwIo\hid.pyc", line 301, in setOutputReport
OSError: [WinError 121] The semaphore timeout period has expired.
ERROR - braille.BrailleHandler.handleDisplayUnavailable (20:15:10.641) - braille._BgThread (6540):
Braille display unavailable. Disabling
Traceback (most recent call last):
  File "braille.pyc", line 2233, in executor
  File "brailleDisplayDrivers\brailliantB.pyc", line 240, in display
  File "hwIo\hid.pyc", line 301, in setOutputReport
OSError: [WinError 121] The semaphore timeout period has expired.
INFO - braille.BrailleHandler.setDisplayByName (20:15:15.511) - MainThread (2152):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - braille.BrailleHandler.setDisplayByName (20:15:15.647) - braille._BgThread (6540):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - braille.BrailleHandler.setDisplayByName (20:15:17.110) - braille._BgThread (6540):
Loaded braille display driver noBraille, current display has 0 cells.
INFO - brailleDisplayDrivers.hid.BrailleDisplayDriver.__init__ (20:15:17.110) - braille._BgThread (6540):
Found display with 40 cells connected via hid (\\?\hid#{00001124-0000-1000-8000-00805f9b34fb}_vid&00021d6b_pid&0246&col02#8&f2c30de&0&0001#{4d1e55b2-f16f-11cf-88cb-001111000030})
INFO - braille.BrailleHandler.setDisplayByName (20:15:17.118) - braille._BgThread (6540):
Loaded braille display driver hid, current display has 40 cells.
ERROR - stderr (20:15:17.119) - braille._BgThread (6540):
Exception in thread braille._BgThread:
Traceback (most recent call last):
  File "threading.pyc", line 926, in _bootstrap_inner
  File "threading.pyc", line 870, in run
  File "braille.pyc", line 2257, in func
OSError: exception: privileged instruction
INFO - braille.BrailleHandler.setDisplayByName (20:15:41.976) - MainThread (2152):
Loaded braille display driver noBraille, current display has 0 cells.

[feerrenrut]

@dkager I'm looking into this today, could you attach Debug level logs with the hwIO category enabled (via advanced settings panel).

Please do this with 2021.3.1rc1 and 2021.2. Having both logs will let me compare where things deviate from the expected path, and to confirm that this set of actions works correctly on 2021.2.

We are eager to get this release out in the next few days, hopefully we can address this before then.

[LeonarddeR]

@dkager I assume this is global autodetect, not only auto detect for the hid driver?

[LeonarddeR]

Ugh, I think I know the issue here.

BdDetect is calling getDriversForConnectedUsbDevices and getDriversForPossibleBluetoothDevices. if getDriversForPossibleBluetoothDevices yields a match that only matches the HID driver before yielding the match associated with the Brailliant driver, NVDA will still try the HID driver first. The logic I changed only has to do with device matches that match both the vendor and hid driver. In that case, the vendor driver is now prefered.
Though I can no longer reproduce the issue with 2021.3.1RC1, this is most likely due to a side effect that getDriversForPossibleBluetoothDevices yields matches in a different order. I guess it can even change when I reboot, pair again or disable/enable bluetooth.

This is worrying and really a bug in the display firmware's, they really ought not provide a HID device that's malfunctioning like this.

I see several fixes to this:

1. Completely exclude HID braille from auto detect for now.
2. Expand the HID driver in such a way that it can better ensure that it is actually connected to a functioning device.

I guess 2 is preferred, though this might require a lot of testing. I can have a look as I have a device. The steps to reproduce a working situation would be as follows:

1. Connect the device to the system
2. Explicitly select the HID driver from the braille display selection dialog
3. Ensure that NVDA reports a failure loading the display.

If this happens, auto detect will be smart enough to try the next device in the list, which is likely to be the Brailliant driver. It will at most introduce a delay in auto detection.

[LeonarddeR]

@dkager I'm looking into this today, could you attach Debug level logs with the hwIO category enabled (via advanced settings panel).

I'm afraid this is not going to help much. I looked at the hwIo logs for my APH Mantis Q40, but when the HID driver is used, NVDA just writes braille to the display and the display simply seems to ignore it. Key presses on the display don't enter NVDA at all.

[feerrenrut]

Thanks for the updates @LeonarddeR. @dkager no need for the logs at this stage.

Can we fix the order that the matches are yielded? Perhaps by filtering in the itertools.chan and doing the process again once all non HID matches are considered.

[LeonarddeR]

The problem with that, is that the vendor bluetooth implementation is also HID based.

[feerrenrut]

Will it have the HIDUsagePage for that match as well, eg match.deviceInfo.get('HIDUsagePage') == HID_USAGE_PAGE_BRAILLE

[feerrenrut]

@dkager Could you please test a try-build for me?

[dkager]

What @LeonarddeR wrote makes sense. I got the Brailliant to work once yesterday by explicitly choosing it and setting the port to Bluetooth. Then when switching back to either the Auto port or global autodetect, you either get an error or sometimes an empty braille display. Although that might be the firmware having issues.

[dkager]

@feerrenrut The try-build definitely improves connectivity. I have had a few cases where there was either no connection through Bluetooth or NVDA crashed as soon as I pressed OK to change the braille display. Most times Bluetooth worked. I haven't been able to reliably reproduce the error. I could look at it further, but that will probably have to wait until the weekend.

[feerrenrut]

@dkager If you get a crash with this build, could you please collect the crash dump and the NVDA log for us?
Information on logs and crash dumps on the wiki

[feerrenrut]

If testing over the weekend, please do so with the build of RC to test merged changes: https://ci.appveyor.com/api/buildjobs/pl56jgcjg2ym6xap/artifacts/output%2Fnvda_snapshot_rc-24378%2Ccaf14822.exe

I'll be releasing an RC2 early next week based on this.

[dkager]

I have as yet not been able to reproduce the problem with debug logging, but admittedly haven't restarted NVDA much. I will post logs as soon as I get errors, but overall it seems that as soon as the correct driver is loaded, the rest of the session goes very smoothly. Putting the Brailliant into sleep mode and reactivating it later also works well, proving that autodetection within the same driver and port works.