Beruflich Dokumente
Kultur Dokumente
OS X
The purpose of this application note is to provide users of FTDI chips with a simple procedure for
installing FTDI drivers for FTDI devices used under MAC OS X.
Table of Contents
1 Introduction .................................................................... 3
2 Getting FTDI Device Drivers ............................................ 4
2.1 Getting VCP ............................................................................... 4
2.2 Getting D2XX ............................................................................ 4
3 Installing Drivers ............................................................ 5
3.1 Installing VCP Drivers on OS X 10.3 to OS X 10.8 ..................... 5
3.2 Installing VCP Drivers on OS X 10.9 onwards ........................... 9
3.3 Installing D2xx Drivers ........................................................... 15
4 Uninstalling FTDI Drivers on OS X ................................. 16
4.1 Uninstalling FTDI VCP Drivers on OS X 10.3 to OS X 10.8 ....... 16
4.2 Uninstalling FTDI VCP Drivers on OS X 10.9 onwards ............. 16
4.3 Uninstalling D2XX Drivers ....................................................... 17
5 VCP Troubleshooting ..................................................... 18
5.1 How do I know what my deviceID is? ..................................... 18
5.2 The device does not appear in the /dev directory ................... 18
5.3 The text NewPort Detected" is not displayed in System
Preferences-Network ...................................................................... 19
5.4 The device cannot be accessed even though the deviceID is
supported in FTDIUSBSerialDriver .................................................. 19
5.5 How do I open a Terminal window? ........................................ 19
6 D2XX Troubleshooting................................................... 20
6.1 I can't open a device even though the installation has been
successful........................................................................................ 20
6.2 After running an application two or three times, communication
stops ............................................................................................... 20
6.3 Problems upgrading to the latest D2XX driver ........................ 20
7 Disabling the Apple-provided VCP on OS X 10.9 and later
22
7.1 Disable by Renaming .............................................................. 22
7.2 Temporarily Unload ................................................................. 22
7.3 Block with D2xxHelper ............................................................ 22
7.3.1 Distributing D2xxHelper ........................................................................................ 22
1 Introduction
The purpose of this application note is to provide users of FTDI chips with a simple procedure for
installing FTDI drivers for their devices under MAC OS X.
VCP creates a virtual com port on the MAC and allows applications that use the POSIX programming
interface to communicate with the device. This is effectively the same us using a legacy com port.
The download is a Disk Image (dmg) file at: http://www.ftdichip.com/Drivers/VCP.htm
Download the version relevant to your OS version.
Clicking the weblink starts a download.
D2xx uses FTDIs programming interface to access advanced features of the chips.
The download is a Disk Image (dmg) file at http://www.ftdichip.com/Drivers/D2XX.htm
The current version at the time of writing (version 1.2.2) covers all versions of OS X from 10.4 onwards.
3 Installing Drivers
With Lion and Mountain Lion, you will need to bypass the new Gatekeeper security function to install the
pkg file. Simply press Cntrl-Click when you select FTDIUSBSerialDriver_10_4_10_5_10_6_10_7.pkg.
This will bring up a pop-up menu. Select Open from this menu:
Select Open and the VCP driver install process will begin ( see next page).
Select Install. At this point you may be asked for your password to authenticate the installation. This is
just the same as you would do to log into the machine to begin using it.
If the device is installed properly, you will see entries in the /dev directory:
/dev/cu.usbserial-xxxxxxxx
/dev/tty.usbserial-xxxxxxxx
where xxxxxxxx is either the device's serial number or, for unserialized devices, a location string
that depends on which USB port your device is connected to. Note that for FT2232D devices port
A is denoted by the serial number appended with "A" and port B is designated by the serial number
appended with "B".
/dev can be accessed through the Terminal application. The Terminal application can be launched
by selecting Go > Applications > Utilities > Terminal. Type the following lines in the Terminal
window to produce the file list:
cd /dev
ls-l
If you do wish to use FTDIs VCP, disable the Apple-provided FTDI VCP driver as per section 7.
To install the driver on the MAC, simply click on the FTDIUSBSerial.pkg shown in section 2.1.
Select Continue
Select Install.
At this point you may be asked for your password to authenticate the installation. This is just the same
as you would do to log into the machine to begin using it. Then select Install Software.
The final screen should show that the installation was successful. Select close and then reboot.
If the device is installed properly, you will see entries in the /dev directory:
/dev/cu.usbserial-xxxxxxxx
/dev/tty.usbserial-xxxxxxxx
where xxxxxxxx is either the device's serial number or, for unserialized devices, a location string
that depends on which USB port your device is connected to. Note that for FT2232D devices port
A is denoted by the serial number appended with "A" and port B is designated by the serial number
appended with "B".
/dev can be accessed through the Terminal application. The Terminal application can be launched
by selecting Go > Applications > Utilities > Terminal. Type the following lines in the Terminal
window to produce the file list:
cd /dev
ls-l
To avoid this scenario, if FTDIs VCP is installed, uninstall it by following the instructions in section 4. On
OS X 10.9 and later, block, unload or disable Apples driver by following the instructions in section 7.
Download the D2XX disk image as per section 2.2 of this document. Click the dmg item in the
Downloads area to mount the disk image, then drag the D2XX folder to your desktop.
Start a Terminal session (Go > Applications > Utilities > Terminal)
Samples written in C are provided to show how to use the library and verify the installation. These are
command-line applications that must be executed from the Terminal window. To compile and run the
samples, perform the following steps (these assume you have copied all of the distribution files to the
desktop and installed the library as per the Installation section above):
Open a Terminal window (Go > Applications > Utilities > Terminal).
To test running an application, connect an FTDI device with default VID (0x0403) and PID (e.g. 0x6001)
and type:
sudo EEPROM/read/read
Note: running as super-user (sudo) is necessary because OS X does not give ordinary users permission
to access USB directly.
If you have issues at this stage then consult the troubleshooting topics in section 6. If the
troubleshooting section doesn't help then contact support with your problem details.
Follow the procedures below if you wish to remove the FTDI-provided drivers from your MAC.
Start a Terminal session (Go > Applications > Utilities > Terminal) and enter the following
commands at the command prompt:
cd /System/Library/Extensions
rm -r FTDIUSBSerialDriver.kext
cd /Library/Receipts
rm -r ftdiusbserialdriver.pkg
rm -r ftdiusbserialdriverinstallerPostflight.pkg
rm -r ftdiusbserialdriverinstallerPreflight.pkg
To temporarily operate as the root user you can use sudo at the beginning of the command
e.g.
cd /System/Library/Extensions
sudo rm -r FTDIUSBSerialDriver.kext
cd /Library/Receipts
sudo rm -r ftdiusbserialdriver.pkg
sudo rm -r ftdiusbserialdriverinstallerPostflight.pkg
sudo rm -r ftdiusbserialdriverinstallerPreflight.pkg
Start a Terminal session (Go > Applications > Utilities > Terminal) and enter the following
commands at the command prompt:
cd /Library/Extensions
rm -r FTDIUSBSerialDriver.kext
then reboot
To temporarily operate as the root user you can use sudo at the beginning of the command
e.g.
cd /Library/Extensions
sudo rm -r FTDIUSBSerialDriver.kext
then reboot
Start a Terminal session (Go > Applications > Utilities > Terminal)
5 VCP Troubleshooting
Select USB under Hardware in the panel to the left and then select the appropriate device from the
USB Device Tree.
In the screen shot below (from OS 10.4), the device has a deviceID given by:
Vendor ID: 0x0403
Product ID: 0x6001
If the device does not work after installing the driver, it is likely to be because the PID is not
supported by the driver. If this is the case, contact the vendor of your product to determine if they
provide an edited driver to support their product. If they do not provide an edited driver you can make
the edits yourself by following the instructions in TN_105 Adding Support for New Devices to MAC Driver
from the FTDI website
http://www.ftdichip.com/Documents/TechnicalNotes/TN_105%20Adding%20Support%20for%20New%2
0FTDI%20Devices%20to%20Mac%20Driver.pdf
Please note that editing the kext to add a VID/PID, or alias a baud rate now requires re-signing with a
kext-signing certificate.
If the VID is not 0x0403, it is likely that the device is not an FTDI device and we cannot support it.
Disable the EEPROM so that the device reverts to its default deviceID, then replug.
To get support for your deviceID built into FTDIUSBSerialDriver, contact the vendor of your product to
determine if they provide an edited driver to support their product. If they do not provide an edited driver
On OS X 10.11 or later, another possibility is that VCP has been blocked by installation of D2xxHelper,
bundled with an application. VCP and such an application are mutually exclusive. To force using VCP,
disable D2xxHelper:
cd /Library/Extensions
sudo mv D2xxHelper.kext D2xxHelper.disabled
Then reboot. To force using D2xx again, rename D2xxHelper.disabled back to D2xxHelper.kext and
reboot.
An ownership or permissions problem is preventing the system from making the device accessible.
Check that the driver is owned by root and wheel. The most common symptom is the group for
FTDIUSBSerialDriver is not wheel.
To change the group, login as root and perform the following script in a Terminal window (Go >
Applications > Utilities > Terminal):
cd /system/library/extensions
chgrp -R wheel FTDIUSBSerialDriver.kext
On OS X 10.11 or later, another possibility is that VCP has been blocked by installation of D2xxHelper,
bundled with an application. VCP and such an application are mutually exclusive. To force using VCP,
disable D2xxHelper:
cd /Library/Extensions
sudo mv D2xxHelper.kext D2xxHelper.disabled
Then reboot. To force using D2xx again, rename D2xxHelper.disabled back to D2xxHelper.kext and
reboot.
6 D2XX Troubleshooting
6.1 I can't open a device even though the installation has been
successful
This is possibly due to another driver claiming the device for use as a virtual COM port. To check, type:
kextstat | grep FTDI
If the output contains lines referring to either (or both) of AppleUSBFTDI or FTDIUSBSerialDriver, the
solution is one of the following:
Reprogram the FTDI chip with non-FTDI (vendor/product) identifiers. This prevents OS X from
matching the device with any other driver. See
http://www.ftdichip.com/Support/Documents/TechnicalNotes/TN_100_USB_VID-
PID_Guidelines.pdf for guidance on this.
On OS X 10.9 and later: install D2xxHelper which blocks AppleUSBFTDI and
FTDIUSBSerialDriver from matching standard FTDI chips. See section 7.3.
On OS X 10.10 and earlier: disable or temporarily unload the serial driver(s). For
FTDIUSBSerialDriver, see section 4; for AppleUSBFTDI, see section 7.
Another possibility is an incorrect VID/PID. Try changing your application to use the FT_SetVIDPID API
call to quickly determine if this is the case.
It is always recommended that you close a file handle obtained by FT_Open/FT_OpenEx before
exiting an application. Side effects of not closing the handle with the multithreaded setting (as
illustrated above) can be future communication with the device fails (always test this prior to
enabling this setting).
The Sample applications demonstrate a method of trapping an abnormal exit (control C operation) and
closing each handle in turn.
If you cannot find a work around then try setting the USB Reset After Open bit in the ftd2xx.cfg file but
only as a last resort.
To determine which D2XX library your application is using perform the following steps (examples in
brackets assume you have copied all of the files to the desktop and successfully compiled the samples as
described in the Samples section):
Open a Terminal window (Go > Applications > Utilities > Terminal).
simple:
/usr/local/lib/libftd2xx.1.2.2.dylib (compatibility version 1.2.2, current version 1.2.2)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 88.1.6)
To alter the library so that the simple sample points to use the install_name_tool (e.g
install_name_tool -change /usr/local/lib/libftd2xx.1.2.2.dylib /usr/local/lib/libftd2xx.dylib simple).
Please note you may need to change user mode to perform this function depending on the file
permissions set on the executable.
Run the otool (illustrated in step 3 above) to confirm that the library pointed to by the application
has changed and is correct.
Start a terminal session (Go > Applications > Utilities > Terminal) and copy/paste the following text to
the command prompt:
cd /System/Library/Extensions/IOUSBFamily.kext/Contents/Plugins
sudo mv AppleUSBFTDI.kext AppleUSBFTDI.disabled
sudo touch /System/Library/Extensions
then reboot.
It is possible to unload Apples VCP for the current session, i.e. until the next reboot:
sudo kextunload b com.apple.driver.AppleUSBFTDI
(If a warning message indicates that the kext cant be unloaded, then reboot and retry the above
command.)
To reload:
sudo kextload b com.apple.driver.AppleUSBFTDI
The kextunload and kextload commands can be run in any directory.
Note: this is the only non-temporary method which works on 10.11 El Capitan.
FTDI provides a signed kernel extension (D2xxHelper.kext) which contains no code but acts to prevent
OS X from matching an FTDI chip (with standard vendor and product identifiers) with a VCP driver, either
Apples or FTDIs. This leaves the device unclaimed, and available for D2XX programs only.
1. Disconnect all FTDI devices.
2. Download and run the D2xxHelper installer from http://www.ftdichip.com/Drivers/D2XX.htm
3. Reboot.
4. Reconnect the FTDI devices.
To include D2xxHelper.kext with your own D2XX application installer, download the package from the link
above, then extract it with:
pkgutil --expand D2xxHelper.pkg tmpdir
tar xf tmpdir/dst.pkg/Payload
Copyright Future Technology Devices International Limited 22
Document Reference No.: FT_000201
FTDI Drivers Installation guide for MAC OS X
Application Note AN_134 Version 1.4
Clearance No.: FTDI# 123
This creates Library/Extensions/D2xxHelper.kext in the current directory.
8 Contact Information
Future Technology Devices International Limited Future Technology Devices International Limited (USA)
Unit 1, 2 Seaward Place, Centurion Business Park 7130 SW Fir Loop
Glasgow G41 1HH Tigard, OR 97223-8160
United Kingdom USA
Tel: +44 (0) 141 429 2777 Tel: +1 (503) 547 0988
Fax: +44 (0) 141 429 2758 Fax: +1 (503) 547 0987
Future Technology Devices International Limited Future Technology Devices International Limited
(Taiwan) (China)
2F, No. 516, Sec. 1, NeiHu Road Room 1103, No. 666 West Huaihai Road,
Taipei 114 Shanghai, 200052
Taiwan , R.O.C. China
Tel: +886 (0) 2 8797 1330 Tel: +86 21 62351596
Fax: +886 (0) 2 8751 9737 Fax: +86 21 62351595
Web Site
www.ftdichip.com
System and equipment manufacturers and designers are responsible to ensure that their systems, and any Future Technology Devices
International Ltd (FTDI) devices incorporated in their systems, meet all applicable safety, regulatory and system-level performance
requirements. All application-related information in this document (including application descriptions, suggested FTDI devices and other
materials) is provided for reference only. While FTDI has taken care to assure it is accurate, this information is subject to customer
confirmation, and FTDI disclaims all liability for system designs and for any applications assistance provided by FTDI. Use of FTDI
devices in life support and/or safety applications is entirely at the users risk, and the user agrees to defend, indemnify and hold
harmless FTDI from any and all damages, claims, suits or expense resulting from such use. This document is subject to change without
notice. No freedom to use patents or other intellectual property rights is implied by the publication of this document. Neither the whole
nor any part of the information contained in, or the product described in this document, may be adapted or reproduced in any material
or electronic form without the prior written consent of the copyright holder. Future Technology Devices International Ltd, Un it 1, 2
Seaward Place, Centurion Business Park, Glasgow G41 1HH, United Kingdom. Scotland Registered Company Number: SC136640
Appendix A Abbreviations
Terms Description
PID Product ID, a unique product identification issued by the holder of the
VID Vendor ID, a unique vendor identification number issued by the USB
USB USB Universal Serial Bus
OS Operating System