Skip to content

Automatically detect Dot Pad displays over USB#18444

Merged
seanbudd merged 12 commits into
nvaccess:masterfrom
bramd:dotpad-autodetect
Aug 4, 2025
Merged

Automatically detect Dot Pad displays over USB#18444
seanbudd merged 12 commits into
nvaccess:masterfrom
bramd:dotpad-autodetect

Conversation

@bramd

@bramd bramd commented Jul 11, 2025

Copy link
Copy Markdown
Contributor

Link to issue number:

None

Summary of the issue:

Dot Pad braille/tactile displays are not detected automatically, a user has to manually specify the correct USB serial port.

Description of user facing changes:

Dot Pad displays are automatically detected and due to the auto detection logic a "USB" port entry is added to connect to the first display connected over USB.

Description of developer facing changes:

None

Description of development approach:

Registered the Dot Pad with it's vendor/product ID.

Testing strategy:

  • Tested autodetection by plugging in a Dot Pad 320A after starting NVDA
  • Tested port selection by selecting "USB" from the ports list

Known issues with pull request:

  • The vendor/product ID of the Dot Pad is a generic ID of the FTDI serial converter being used. However, there are more devices that use a generic ID, such as some older Handy Tech braille displays, so this is in line with automatic detection of other devices. Reducing the risk of communicating with other devices that share the same ID is outside the scope of this pR

Code Review Checklist:

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

@coderabbitai summary

@bramd bramd force-pushed the dotpad-autodetect branch from e99a76d to f2c1316 Compare July 11, 2025 19:58
@bramd bramd marked this pull request as ready for review July 11, 2025 20:54
@bramd bramd requested review from a team as code owners July 11, 2025 20:54
@bramd bramd force-pushed the dotpad-autodetect branch from f2c1316 to bfaff9b Compare July 11, 2025 21:56
@bramd bramd closed this Jul 11, 2025
@bramd bramd reopened this Jul 11, 2025
Comment thread user_docs/en/changes.md Outdated
bramd and others added 3 commits July 13, 2025 13:50
Mention PR in changes

Co-authored-by: Leonard de Ruijter <3049216+LeonarddeR@users.noreply.github.com>
@michaelDCurran

Copy link
Copy Markdown
Member

We acknowledge that there are other older devices that auto detect against generic usb to serial converters. However, we would really like to move away from this as we feel strongly that this is dangerous. Sending serial commands to a device we can not be sure about could cause undefined behavior which could be damaging or dangerous for the user. So we do not believe that the argument that other devices do it is enough reason to accept this pr unfortunately.
However, we do welcome constructive and thoughtful conversation exploring our position and other possibilities. For example allowing it to auto detect, but change the default list of selected displays for auto detection to exclude this and those other drivers. Which still allows the user to turn them on at their own choosing.

@michaelDCurran michaelDCurran marked this pull request as draft July 16, 2025 03:34
@LeonarddeR

Copy link
Copy Markdown
Collaborator

@michaelDCurran wrote:

However, we would really like to move away from this as we feel strongly that this is dangerous.

  1. Has NV Access ever received reports from users that auto detection caused dangerous request to another device that was unrelated to Braille Display hardware?
  2. What is the behavior of other screen reader vendors here? I'm pretty sure that Dolphin SAM will be just as agressive with detection based on vid/pid. For JAWS, you need to explicitly opt in for a driver. For Narrator, I'm pretty sure installing braille display support will cause LibUSB to take over these devices, making them unusable for normal operation. That would break other screen readers too, though.

That said, "VID_0403&PID_6010" looks pretty generic, at least more generic than "VID_0403&PID_6001" which is used in multiple braille displays as well and has been automatically detected by us for ages.

The easiest solution is probably to add the driver to the config spec in the excludedDisplays list. However, I feel that it might be better to add an extra option in the braille display selection dialog that allows you to opt out of communication type/protocol combinations. For example, when I have bluetooth on and also have a braille display paired, I am yet in situations where I never use Bluetooth for automatic detection. It makes sense to disable Bluetooth explicitly in NVDA in these cases.
It might make sense to opt out of serial over usb by default, as I think that's the only area where generic usb pid and vids are used broadly. But it becomes problematic for deaf blind users who rely on such devices.

@bramd

bramd commented Jul 16, 2025

Copy link
Copy Markdown
Contributor Author
1. Has NV Access ever received reports from users that auto detection caused dangerous request to another device that was unrelated to Braille Display hardware?

I can't answer that, bit I don't find it unreasonable to accept that this might cause problems with other serial equipment and having a less aggressive default behavior would be preferable.

2. What is the behavior of other screen reader vendors here? I'm pretty sure that Dolphin SAM will be just as agressive with detection based on vid/pid. For JAWS, you need to explicitly opt in for a driver. For Narrator, I'm pretty sure installing braille display support will cause LibUSB to take over these devices, making them unusable for normal operation. That would break other screen readers too, though.

Yes, Narrator is weird here by just pushing libusb drivers. I'm not sure though if it does that for geherid VID/PIDs as well. I'm not sure how Dolphin SAM works these days, but in the past I thought you had to trigger a scan manually? JAWS requires you to select/install specific drivers, but should be able to do some autodetection after that. Also, for what it's worth, VoiceOver on Mac seems to aggressively connect to generic USB displays as well.

That said, "VID_0403&PID_6010" looks pretty generic, at least more generic than "VID_0403&PID_6001" which is used in multiple braille displays as well and has been automatically detected by us for ages.

Both of those are generic product identifiers from FTDI and are also documented in various places as such. The 6010 is a dual serial module, exposing two serial interfaces. Why this is used in this device is unknown to me, but it seems less common in braille displays then the single serial interface module. The 6001 is one of the FTDI single serial modules.

The easiest solution is probably to add the driver to the config spec in the excludedDisplays list. However, I feel that it might be better to add an extra option in the braille display selection dialog that allows you to opt out of communication type/protocol combinations. For example, when I have bluetooth on and also have a braille display paired, I am yet in situations where I never use Bluetooth for automatic detection. It makes sense to disable Bluetooth explicitly in NVDA in these cases. It might make sense to opt out of serial over usb by default, as I think that's the only area where generic usb pid and vids are used broadly. But it becomes problematic for deaf blind users who rely on such devices.

Yes, and it also gives a weird user experience for users upgrading NVDA and/or starting with a new config, on another machine for example. Excluding USB serial by default will cause some USB displays to be detected and others not. People who relied on the autodetect behavior would be confused if that suddenly stopped working on a new installation.

I'm open to take the easy way here and exclude DotPad by default, but that creates a weird situation where other USB serial displays are autodetected and this specific one is not. However, on the other hand I think that proposing and working out a whole solution for this generic ID problem including a great UX for all our users, including deafblind ones, is broadening the scope of this PR a lot. Also, I feel that the discussion should be held in an issue or Github discussion where it will be found by more affected users. Users without a DotPad display will not check this PR, but might be interested and affected by this.

@bramd

bramd commented Jul 16, 2025

Copy link
Copy Markdown
Contributor Author

We acknowledge that there are other older devices that auto detect against generic usb to serial converters. However, we would really like to move away from this as we feel strongly that this is dangerous. Sending serial commands to a device we can not be sure about could cause undefined behavior which could be damaging or dangerous for the user. So we do not believe that the argument that other devices do it is enough reason to accept this pr unfortunately.

I see your point, but this means we either broaden the scope of this PR a lot or we add this to disabled displays and have unexpected other behavior for this specific displays over other braille displays. I also wonder why this was not a problem with the initial bdDetect system, where generic IDs were already present.

However, we do welcome constructive and thoughtful conversation exploring our position and other possibilities. For example allowing it to auto detect, but change the default list of selected displays for auto detection to exclude this and those other drivers. Which still allows the user to turn them on at their own choosing.

Regardless if we do this in the current PR or not, here are a few of my thoughts on how we can do this:

  1. Disable generic IDs in the default configspec
  2. Add an option to NVDA's first launch dialog: "Enable automatic detection of Braille Displays (you can always change this later)" with the options:
  • Disabled
  • Safe, excludes certain USB devices (default)
  • Full, might cause problems with other USB serial devices
  1. Add a button "Revert to safe defaults" in the braille displays to detect dialog
  2. Show a popup if a generic device is connected to USB:
  • "It seems you connected a {deviceName} braille display. However, this device is not configured for automatic detection by NVDA since it can cause problems with other devices if we try to detect it automatically. Would you like to use this device as a Braille Display? Please note that you can always change this by checking/unchecking this display in NVDA's Select Braille Display dialog."
  • Options: "Yes, this time only", "Yes and detect it automatically in the future", "No, not this time", "No and don't ask again"
  • We need to track this state somehow and probably expose it to the user

I would like to hear your thoughts about implementing one or more of these options.

@michaelDCurran

michaelDCurran commented Jul 16, 2025 via email

Copy link
Copy Markdown
Member

@bramd

bramd commented Jul 17, 2025

Copy link
Copy Markdown
Contributor Author

@michaelDCurran I would suggest that

  1. I modify this PR to disable DotPad autodetection by default and leave the rest as is. So this feature does not strand on coming up with the UX and possibly upgrade path for existing users.
  2. I open a new issue with a summary of this discussion so far and try to discuss autodetection of generic devices with a broader user group before deciding/moving forward on that one

@michaelDCurran

michaelDCurran commented Jul 17, 2025 via email

Copy link
Copy Markdown
Member

@bramd bramd requested a review from LeonarddeR July 26, 2025 11:18
@seanbudd seanbudd added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Jul 29, 2025
Comment thread user_docs/en/changes.md Outdated
@seanbudd seanbudd requested a review from Copilot July 31, 2025 05:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds automatic detection support for Dot Pad braille/tactile displays connected over USB. Previously, users had to manually select the correct USB serial port for these devices.

  • Enables automatic detection for Dot Pad displays using USB vendor/product IDs
  • Adds the Dot Pad to the excluded displays list by default due to generic USB identifiers
  • Updates configuration upgrade logic to handle the new excluded display setting

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
user_docs/en/userGuide.md Updated documentation to reflect automatic detection capability and configuration options
user_docs/en/changes.md Added changelog entry for the new automatic detection feature
tests/unit/test_config.py Added comprehensive unit tests for the configuration upgrade function
source/config/profileUpgradeSteps.py Implemented configuration upgrade logic to add dotPad to excluded displays
source/config/configSpec.py Updated schema version and default excluded displays list
source/brailleDisplayDrivers/dotPad/driver.py Added automatic detection support and USB device registration

Comment thread source/brailleDisplayDrivers/dotPad/driver.py
Comment thread source/brailleDisplayDrivers/dotPad/driver.py Outdated
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@seanbudd seanbudd enabled auto-merge (squash) August 4, 2025 03:33

@Qchristensen Qchristensen left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, users will appreciate this - we had an inquiry just the other day :)

@seanbudd seanbudd merged commit 50e50cf into nvaccess:master Aug 4, 2025
21 checks passed
@SaschaCowley SaschaCowley added this to the 2025.3 milestone Aug 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants