OSX: Getting Pesky FTDI Debugging Devices to Work

Many useful FTDI-based debugging devices exist for those of us working in the embedded world. These devices are extremely useful and provide JTAG and SWD capabilities, as well as acting as I2C, SPI, or Serial protocol converters. With an FTDI debug tool, you can use your host machine to debug and interface with a variety of parts.

However, one fact that complicates things greatly is that most parts use their own USB product and vendor ID codes, which means that you have to manually modify the FTDI driver kext in order for your device to be detected. There are many guides on the internet for enabling custom FTDI device support, but most of them now seem out of date. This guide is valid as of OSX 10.12, which requires additional steps to disable OSX's "System Integrity Protection."

Testing a Connection

In order to judge whether an FTDI device is properly detected or not, I attempt to open a serial connection. Without the correct drivers, no usbserial devices show up. Your device will likely have a different name.

For example, here's how I connect to a TUMPA debugger on my host machine.

picocom -b 115200 /dev/tty.usbserial-TIM01416B

If you are unable to connect, you likely need to perform the steps below.

miniterm.py

If you are unsure of what serial program to use, run the following commands to enable miniterm.py:

$ sudo easy_install pip
$ sudo pip install pyserial

After installing pyserial, you can run miniterm.py, which will show you a list of connected serial devices:

$ miniterm.py
--- Available ports:
--- /dev/cu.Bluetooth-Incoming-Port n/a
--- /dev/cu.MuadDib-WirelessiAP n/a

Note above that I have no USB serial device connected, indicating a problem.

Try Your Device

Before doing anything, try plugging your device into the computer and make sure the AppleUSBFTDI driver doesn't already support your device.

If you don't see the FTDI serial device, there's still another step to try with the native OSX drivers. Try these steps, then attempt to connect:

sudo kextunload -p -b com.apple.driver.AppleUSBFTDI
sudo kextutil -b com.apple.driver.AppleUSBFTDI -p AppleUSBEFTDI-6010-1

If you see the FTDI serial device, stop reading!

Download the FTDI Drivers

If your device didn't work with the native FTDI driver, you will want to try the "official" FTDI drivers. Download them for your machine here.

Once installed, check your device again and see if it connects.

If you see the FTDI serial device, stop reading!

Find your PID/VID

At this point, it is likely that your FTDI device has a PID/VID combination that isn't listed in the FTDI kext. My TUMPA falls into this boat.

Connect your device, and issue the following command in the shell:

$ system_profiler SPUSBDataType

This command will print information for all USB devices connected to your computer. Look for your FTDI device entry:

TIAO USB Multi-Protocol Adapter:
    Product ID: 0x8a98
    Vendor ID: 0x0403  (Future Technology Devices International Limited)
    Version: 7.00
    Serial Number: TIM01416
    Speed: Up to 480 Mb/sec
    Manufacturer: TIAO
    Location ID: 0x14100000 / 5
    Current Available (mA): 500
    Current Required (mA): 450
    Extra Operating Current (mA): 0

Note down the Product ID and Vendor ID, and convert those numbers to decimal.

Modifying the FTDI kext

First, make a copy of the FTDI Info.plist so you have a backup:

$ sudo cp /System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist /System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist.orig

Open the FTDI kext Info.plist file in your favorite text editor, located at /System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist

You will need to add a new device entry with the PID/VID for your product supplied. Copy one of the device entries, supply a new name corresponding to your device, and modify the VID/PID to match your product.

Here's an example for my TUMPA:

<key>TIAO USB Multi-protocol Adapter</key>
<dict>
    <key>CFBundleIdentifier</key>
    <string>com.FTDI.driver.FTDIUSBSerialDriver</string>
    <key>IOClass</key>
    <string>FTDIUSBSerialDriver</string>
    <key>IOProviderClass</key>
    <string>IOUSBInterface</string>
    <key>bConfigurationValue</key>
    <integer>1</integer>
    <key>bInterfaceNumber</key>
    <integer>0</integer>
    <key>idProduct</key>
    <integer>35480</integer>
    <key>idVendor</key>
    <integer>1027</integer>
</dict>
<key>TIAO USB Multi-protocol Adapter</key>
<dict>
    <key>CFBundleIdentifier</key>
    <string>com.FTDI.driver.FTDIUSBSerialDriver</string>
    <key>IOClass</key>
    <string>FTDIUSBSerialDriver</string>
    <key>IOProviderClass</key>
    <string>IOUSBInterface</string>
    <key>bConfigurationValue</key>
    <integer>1</integer>
    <key>bInterfaceNumber</key>
    <integer>1</integer>
    <key>idProduct</key>
    <integer>35480</integer>
    <key>idVendor</key>
    <integer>1027</integer>
</dict>

I have two entries here because my device has two FTDI interfaces. Whether you have one or two interfaces depends on your part - do some digging :)

Disabling SIP

Modern OSX enables "System Integrity Protection" by default, which will prevent our modified FTDI driver from loading since the signature no longer matches the driver contents. You will need to disable SIP to use the modified driver on your system.

  • Boot to Recovery OS by restarting your machine and holding down the Command and R keys at startup.
  • Launch Terminal from the Utilities menu.
  • Enter the following command to disable SIP:
    $ csrutil disable
  • Reboot your computer

If you want to enable SIP again, simply follow the steps and issue the following command:

$ csrutil enable

Loading/Unloading the Driver

After rebooting your system, you should be good to go. However, if you have already disabled SIP and are making modifications to the driver, you can manually load/unload in the shell:

$ sudo kextunload /System/Library/Extensions/FTDIUSBSerialDriver.kext/
$ sudo kextload /System/Library/Extensions/FTDIUSBSerialDriver.kext/

Further Reading