Win32-FTDI-FTD2XX version 1.02 ============================== $Id: README,v 1.5 2008/11/17 15:00:38 395502 Exp $ ============================== Win32::FTDI::FTD2XX provides a Perl5 interface to FTDI's D2XX Direct USB Drivers (CDM 2.04.06 as of this writing). It comes in two major components, the FTD2XX.pm module and an encapsulation and abstraction library, called P5FTD2XX.DLL, which wraps the FTDI FTD2XX.DLL, providing a cleaner interface which works better with Win32::API. For instance, the simpler parameter passing mechanisms of Win32::API were never meant to handle things like (de)referencing and passing of pointers to pointers to buffers etc. The native FT_Open() driver function requires this to open the device handle, which then becomes the primary identifier for the connection to the rest of the API routines. Even when trying to pass the returned pointer around as an opaque datatype when returned through Win32::API, it fails to be recognized as a valid handle by the FT library, since the underlying pointer type's value/meaning gets mangled. The P5FTD2XX Windows DLL abstracts the more complicated API calls and datatypes (like wrapping 'FT_HANDLE' with 'PFT_HANDLE') and provides other extensions to allow Perl to more conveniently interact with the FTDI devices using the native CDM drivers instead of the Virtual Comm Port (VCP), which can be problematic on Windows when trying to use older interfaces like Win32::CommPort or Win32::Serial. The Win32::FTDI Perl object further abstracts and extends the API to make it most convenient for the Perl programming space, and looks after allocating & deallocating the PFT_HANDLEs and packed datatypes for parameter passing. In general, any export (see EXPORTS below) beginning with 'FT' is a direct Perl derivative of the original typedef's and #define's from the FTD2XX.H file. Any export prefixed with 'PFT' is an extension provided by the Win32::FTDI::FTD2Xxx.pm/P5FTD2XX DLL package. Many of the native FT API's have been completely preserved, such as '(P)FT_SetDataCharacteristics', others, like the multi-function 'FT_Open', have been divided into simpler dedicated interfaces as 'PFT_OpenBySerial' and 'PFT_OpenByIndex' (Note: The object interface methods do not require the 'PFT_' prefix, except where noted). Other convenience methods have been added, like 'waitForModem( bitmask )' and the 'crack...' methods which extract bit fields from FT status bytes for you if you don't care to use the values directly. Note: For performance gains at load time, each object method is autosplit/ autoloaded on demand, at which time each API Method also imports the actual API function from the DLL. The entire package was developed and tested using an FTDI UM232R USB to Serial Bridge device, with an Atmel ATMegaX8 AVR microcontroller backend. INSTALLATION To install this module type the following: perl Makefile.PL make make test make install DEPENDENCIES The FTDI/FTD2XX Drivers, at least CDM 2.04.06, must be installed in conjunction with this module for it to be functional (and, obviously, to get very far, you'll need an FTDI device plugged into your USB bus...) The perl object uses Win32::API (v0.55 on my ActiveState 5.8.8 build) to interface with the P5FTD2XX DLL, which will be copied to the windows system32 directory alongside the FTD2XX DLL. If you seem to get 'INVALID_API' returned from almost all methods, the P5FTD2XX DLL probably can't be found. Copy it manually from the {PerlRoot}/site/lib/Win32/FTDI directory to {SystemRoot}/System32 directory, or make sure your PATH statement includes {PerlRoot}/site/lib/Win32/FTDI. COPYRIGHT AND LICENCE Copyright (C) 2008 by Scott K. MacPherson, Akron, Ohio This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.