macOS: rework list_ports to support unicode product descriptors. #364
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit makes some changes to try to improve the behavior of serial.tools.list_ports on macOS and to reduce the amount of magic numbers in this code. These changes include a better adherence to iokit function type declarations as taken from the iokit header files, as well as switching all iokit calls to use UTF-8 encoding rather than mac_roman. The main functional change of this commit is that the devicename is now retrieved through IORegistryEntryName, which avoids some weird USB descriptor mangling that happens somewhere deep within the BSD serial device subsystem in XNU. In particular, on serial devices, all USB product descriptor characters that are not in the basic alphanumeric set are replaced with underscores, which is silly as USB descriptors are unicode strings. This mangling ONLY happens to the product descriptor string, so the vendor and serial number strings do not need to be handled differently than before.
|
Thank you |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
A number of Arm-based microcontrollers, such as the kinetis-based Teensy 3 family, provide a native USB interface that allows the user to control a number of attributes, such as the product descriptor string. However, macOS exhibits some weird behavior where it mangles specifically the product descriptor string (and as far as I can tell, only the product descriptor string) on USB serial devices (this also does not seem to happen with other types of USB device). The mangling, which replaces all non-alphanumeric characters with underscores, appears to happen somewhere deep in the kernel's BSD serial subsystem. In order to work around this, the device's product name can be queried with a different IOKit call, specifically
IORegistryEntryGetName, which appears to be aliased directly to the (unmangled) USB product descriptor string for all USB devices.Note: I'm not sure what versions of macOS pyserial aims to support, but I have tested this (briefly) on both 10.11 and 10.13.
This PR also attempts to make a few correctness fixes to the way pyserial interfaces with IOKit. These have been squashed into the same commit for the sake of brevity.