FTDI and OS X (Yosemite)

Revised 18 May 2016

This is a reposting of an earlier article under an open source project of mine. I’ve added it here as it is applicable to a more general audience than the yad2xx user.

It documents configuration issues between OS X (Yosemite) and a range of USB integration chips from FTDI. I’ve revised this article for El Capitan here.

There is a history between FTDI and Apple regarding device drivers for the OS X platform. Aspiring hackers be warned, it can be a bit of a minefield. This article is aimed at users of OS X Mavericks or later. Presently, I am using Yosemite, 10.10.5. You will find other material on the ‘net. At some point in time it will have been correct…

Connecting an FTDI based device to OS X can be a little tricky as both FTDI and Apple offer drivers. OS X version is also a factor, as are the USB devices vendor and product identifiers (VID/PID). The following device drivers are available:

1. Apple Serial Driver
2. FTDI Serial Driver (aka VCP Driver)
3. FTDI D2XX Driver

The first is available by default on Mavericks or later. The other two must be installed by the user and may cause conflicts.

USB VID/PID

Every USB device is allocated a unique vendor id/product id combo. When a device is attached OS X uses the VID/PID to determine which device driver to use. USB device vendors such as FTDI pay a licence fee and are allocated a unique number. For FTDI this unique vendor id (VID) is 0x0403. All devices manufactured by FTDI will come with this value set.

Product identifiers (PIDs), are allocated by the individual manufacturer. Because the PID is an unsigned 16-bit number there are a possible 65536 values available. FTDI sell multiple kinds of USB devices, the assigned PID varies according to the device. Common values are [1]:

Device	Default VID/PID
FT232BM/L/Q, FT245BM/L/Q	0x0403, 0x6001
FT232RL/Q, FT245RL/Q	0x0403, 0x6001
FT2232C/D/L	0x0403, 0x6010
FT2232HL/Q	0x0403, 0x6010
FT4232HL/Q	0x0403, 0x6011
FT232HL/Q	0x0403, 0x6014

On OS X you can view the VID/PID settings for every attached USB device in the System Report (Apple Menu -> About This Mac).

When a new USB device is attached OS X interrogates the device, a process known as USB device enumeration [2]. The information obtained is used to locate the correct device driver for the device.

Apple Serial Driver

For OS X releases 10.9+ (Mavericks and above), Apple provide their own device driver. It is configured to match against all default FTDI VID/PID combinations (see table above). Devices matched by this driver operate as serial ports and are located in the filesystem under /dev/cu.usbserial-xxxxx. Devices configured this way can be operated using the POSIX communications API [3].

Devices using the Apple driver cannot be operated using the D2XX driver. If you try to connect to one of these devices via D2XX it will report already being open. You can disable the Apple Driver using the following command:
sudo kextunload –b com.apple.driver.AppleUSBFTDI

Be warned, this disables the Apple driver for all FTDI devices using default VID/PID.

For reference, the Apple driver is located in:
/System/Library/Extensions/IOUSBFamily.kext/Contents/PlugIns/AppleUSBFTDI.kext

FTDI Serial Driver (VCP Driver)

FTDI supply their own serial driver for OS X. Its use is optional and you must manually install it. It installs into (v2.3+):
/Library/Extensions/FTDIUSBSerialDriver.kext

Like the Apple driver, its matches all default FTDI VID/PID devices. It also is configured to match many 3rd party devices based on an FTDI chip. The list of supported devices is too long to list here, see:
/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist

The FTDI serial driver will not cause conflicts with the Apple driver. In all instances where the device could match either driver the FTDI serial driver is used.

Because the FTDI serial driver is signed it cannot be modified. Editing the driver files, for example Info.plist, will prevent OS X from loading the driver (editing changes the package signature). This means that the FTDI serial driver can only be used with devices known to FTDI. It cannot be used with custom VID/PID devices.

Like the Apple driver, devices should be programmed using the POSIX communications API. You can disable the FTDI Serial driver using:
sudo kextunload –b com.FTDI.driver.FTDIUSBSerialDriver

FTDI D2XX Driver

The FTDI D2XX Driver is an optional installation. It allows the device to be used as a serial port. It also allows access to more advanced device modes such as bit bang, JTAG, I2C, SPI etc.

Devices may experience driver clashes. This is based on the device VID/PID combo and the installed drivers. The default FTDI VID/PID settings will match the Apple driver (always) and the FTDI Serial driver (if installed). Unlike the VCP driver, the Apple driver will win all clashes and the D2XX driver will fail (device open). If you want to use the D2XX driver for an FTDI device using the default VID/PID you must unload the Apple driver before the D2XX driver will work.

Custom VID/PID

It is possible to reprogram an FTDI devices VID/PID [1]. Changing to a VID/PID combo outside those configured for the Apple driver means the Apple driver will not match.

Changing to a value outside those configured for the FTDI Serial driver means that driver will not match. Devices that fail to match the Apple and FTDI Serial driver can only use the D2XX driver.

References

1. FTDI – Technical Note TN100 – USB Vendor ID / Product ID Guidelines
2. FTDI – Technical Note TN113 – Simplified Description of USB Device Enumeration
3. Apple Developer Notes – Working With a Serial Device