Device Drivers
Serial contains built-in support for a wide array of devices. However, up until macOS 10.15 the presence of a kernel driver on your system could prevent Serial from accessing the device directly using its own, built-in drivers. This distinction was normally transparent, but it meant any bugs or missing features in the underlying driver affected Serial along with any other application using the affected port.
See the troubleshooting tips below if you suspect an issue you’re having may be caused by the driver.
macOS 10.15 and 11.0+
Serial will automatically prefer its own built-in driver for all supported devices except for Communication Device Class (CDC) devices. When you open a serial port on a supported device, the device will be disconnected from the operating system and the corresponding entry under /dev, if it exists, will be removed. When the port is closed, the device will be returned to the operating system and again be available for other applications to use.
While using the built-in driver, in the event Serial is force-quit the device may not be released back to macOS properly. In the event this happens, re-launch Serial, and look for any devices marked with an exclamation point in the device list. Double-click the device and follow the prompt to restore its operation. Serial will launch a helper tool that requires administrator privileges which will release the device and reattach it to the system driver. You may also unplug and replug the device to restore it.
If you’d prefer Serial use the system driver instead, under the “Terminal” menu, choose “Settings…”, then click the “Driver” tab. Choose “Automatic”, “Prefer Built-in Driver” or “Prefer System Driver”. If “Automatic” is chosen, Serial will choose the system driver in certain cases if the driver available meets the same standard as our built-in driver.
macOS 10.11 — 10.14
On older versions of macOS, the presence of a kernel driver may prevent Serial from accessing the device directly. Many of these drivers do not fully implement all of the features of the underlying device, or worse, can cause system instability and data loss.
One of the most common symptom you’ll experience is the device may open, but no data can be sent or received. Other problems include features that do not work (i.e. break support, flow control, or custom baud rates). Some drivers may even crash your computer if the USB device is removed while it is being used.
The solution is to temporarily disable or remove these drivers to allow Serial’s built-in support for these devices to work.
Generally, drivers provided by FTDI or Silicon Labs are of high quality and fully support all features of the underlying device. Do check the vendor’s website for updates, as using an outdated version of a vendor driver can lead to problems with new versions of macOS. The drivers Apple began including in recent versions of macOS are improving but are still incomplete. There is no risk of crashing or data loss with Apple’s drivers.
Determine Bundle identifier
Serial displays the driver’s “bundle identifier” - the unique string used to identify programs on the Mac - under the “Device Info” panel. Once you have this you can disable and/or remove the driver using the instructions below.
Disable Driver (Temporary)
To disable a driver, enter the command below. This change will take effect until you reboot your machine.
Use Caution:
- Unloading (or removing) the vendor-supplied driver will prevent other applications from accessing the serial port.
- Save all work before proceeding as some drivers may not unload cleanly and could crash the system
sudo kextunload -b [bundleid]
Re-Enable Driver
To re-enable a driver, enter the command below:
sudo kextload -b [bundleid]
Remove Driver (Permanent)
Use the following command within Terminal.app to see where a driver is on disk:
kextfind -b [bundleid]
Installed drivers are located under /System/Library/Extensions or /Library/Extensions. You may see the same driver installed in both locations, as older versions of some drivers installed themselves under /System/Library/Extensions which is off-limits since OSX 10.11.
BE VERY CAREFUL WHILE WORKING IN THESE DIRECTORIES, AND DO NOT REMOVE ANYTHING THAT MENTIONS APPLE IN THE NAME OR BUNDLE IDENTIFIER. YOU CAN RENDER YOUR SYSTEM INOPERABLE BY REMOVING THE WRONG DRIVER.
Next, make sure the device in question is unplugged from your USB port before continuing.
Within Terminal.app, move the driver from where it currently is somewhere else on your machine- your desktop, for example:
sudo mv [path-to-driver] ~/Desktop/
Finally, reboot your machine. This is important to make sure your system is stable after the change.