OS X D2XX Library Version 1.4.24
© Future Technology Devices International Ltd. 2016

DISCLAIMER

This software is supplied on an as-is basis and no warranty as to their suitability for any particular purpose is either made or implied. Future Technology Devices International Ltd. will not accept any claim for damages howsoever arising as a result of use or failure of this software. Your statutory rights are not affected. This software or any variant of it is not intended for use in any medical appliance, device or system in which the failure of the product might reasonably be expected to result in personal injury. This document provides preliminary information that may be subject to change without notice.

Libusb

This package uses an unmodified version of libusb (libusb.info) which is distributed under the terms of the GNU Lesser General Public License (see libusb/COPYING or www.gnu.org/licenses).  Source code for libusb is included in this distribution.

Packages

This package contains only 64-bit static and dynamic libftd2xx libraries for OS X 10.8 (Mountain Lion) or later.  Libraries for earlier OS X versions are available at ftdichip.com/Drivers.

Installation

Installing the library is a relatively simple operation which involves copying a file and making a symbolic link.
Use the following steps to install (these assume you have copied the distribution’s D2XX folder to the desktop):

1. Open a Terminal window (Finder->Go->Utilities->Terminal).
2. If the /usr/local/lib directory does not exist, create it:
  sudo mkdir /usr/local/lib
3. if the /usr/local/include directory does not exist, create it:
  sudo mkdir /usr/local/include
4. Copy the dylib file to /usr/local/lib:
  sudo cp Desktop/release/build/libftd2xx.1.4.24.dylib /usr/local/lib/libftd2xx.1.4.24.dylib
5. Make a symbolic link:
  sudo ln -sf /usr/local/lib/libftd2xx.1.4.24.dylib /usr/local/lib/libftd2xx.dylib
6. Copy the D2XX include file:
  sudo cp Desktop/release/ftd2xx.h /usr/local/include/ftd2xx.h
7. Copy the WinTypes include file:
  sudo cp Desktop/release/WinTypes.h /usr/local/include/WinTypes.h
8. You have now successfully installed the D2XX library.

Samples

The samples provided are simple C written command line based 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):

1. Open a Terminal window (Finder->Go->Utilities->Terminal).
2. Change to the root samples directory - cd Desktop/release/Samples
3. Build the samples by typing “make” then return. If you have issues at this stage revisit the installation section to ensure the library is correctly installed. Read the error messages and try to determine the source of the problem. If you still have issues then contact support detailing your issue with as much information as possible.
4. To run an application have a suitable FTDI device with default VID and PID and change to the Simple directory (cd Simple) then type “./simple” then return(make sure the dot and the forward slash precede the simple command).
5. If you have issues at this stage then consult the troubleshooting section later in this document. If the troubleshooting section doesn’t help then contact support with your problem details.

Upgrading Issues

Upgrading the D2XX library can cause problems such as a reported bug fix does not appear to be fixed.
This is most likely related to the application executable pointing to a previous version of the library.

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 above in the Samples section):

1. Open a Terminal window (Finder->Go->Utilities->Terminal).
2. Change directory to the application executable folder (cd Desktop/release/Samples/Simple)
3. Use otool to determine the library path (otool -L simple)
4. The following test is an example of what is displayed
simple:
        /usr/local/lib/libftd2xx.1.4.24.dylib (compatibility version 0.1.0, current version 1.4.24)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 88.1.6)
5. As illustrated the simple application is pointing to the libftd2xx.1.4.24.dylib.
6. To alter the library that the simple sample points to use the install_name_tool (e.g install_name_tool -change /usr/local/lib/libftd2xx.1.4.24.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.
7. Run the otool (illustrated in step 3) to confirm that the library pointed to by the application has changed and is correct.

Vendor and Product Identifiers (VIDs and PIDs)

D2XX can only access devices with particular VIDs and PIDs.  The library has a built-in table of supported VID+PID combinations which by default contains FTDI’s own standard values, for example 0x0403 0x6001 for the FT232R.

You can extend the table with your own custom VID+PID combinations using FT_SetVIDPID.  You must call this before attempting to list or open devices otherwise FT_Open, FT_ListDevices etc. will not recognise your device.  There is an example of this in the Samples folder.

From version 1.4 onwards, there is no restriction on the number of times that you may call FT_SetVIDPID, and there is no need to save or restore existing VID+PIDs.  Previous versions called upon an external LibTable library to check additional VID+PIDs but this method is no longer supported.

Configuration Settings (Advanced users only)

Configuration settings are considered advanced features and are only needed in certain rare situations. Only alter these settings if it has been suggested by support or you know exactly what you are doing. 

The D2XX configuration file MUST be called ftd2xx.cfg. This is a simple text file containing various settings and allows for expansion in the future. The file is read on an FT_Open/Ex only. 3 sections are available for settings – global, VID/PID and unique. An example of the ftd2xx.cfg file is included in the package and each section should be self explanatory. The [Globals] section applies to all devices, the [VID_0403&PID_6001] applies to devices of only VID and PID 0x0403 and 0x6001 and the unique settings apply to only those devices of a particular serial number – in this case [FT000001].
The configuration file must reside in /usr/local/lib or the /usr/lib folder.

Multithreaded write

It has been noted during beta testing that some multi threaded applications can lock up during write communication with the devices. This is due to a conflict in the application run loop and the write run loop. To prevent lockup with a multithreaded application use the 31st (ConfigFlags=0x40000000) bit in the configuration file. This will enable an alternative FT_Write that has its own thread and will not conflict with the current thread run loop operation.

Troubleshooting

Q. Cannot open a port even though installation has been successful.
A1. This is possibly due to OS X claiming the device as a virtual COM port (VCP).  The solution depends on the version of OS X: either disable the VCP or install D2xxHelper which prevents the device being claimed, leaving it available for D2XX.  For more details, please read the our OS X Driver Installation Guide.
A2. 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.

Q. After running an application two or three times – communication will stop.
A. Always close the device on application shutdown. Trapping application exit is demonstrated in some of the sample programs and for simple C applications this is one method to circumvent this issue. 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 very last resort!).