Scott K MacPherson > Win32-FTDI-FTD2XX-1.04 > Win32::FTDI::FTD2XX

Download:
Win32-FTDI-FTD2XX-1.04.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.04   Source  

NAME ^

Win32::FTDI::FTD2XX - PERL5 interface to FTDI's D2XX Direct USB Drivers

SYNOPSIS ^

  use Win32::FTDI::FTD2XX qw(:DEFAULT
        FT_BAUD_38400 FT_BITS_8 FT_STOP_BITS_1 FT_PARITY_NONE
        FT_FLOW_RTS_CTS PFT_MODEM_STATUS_CTS
        );

  my $FTD = Win32::FTDI::FTD2XX->new();
  unless( $FTD->PFT_STATUS() == FT_OK )
    {
    printf( STDERR "FTD2XX::new() failed: %s (%s)\n", 
            $FTD->PFT_STATUS_MSG(), $FTD->PFT_ERROR() );
    exit( 1 );
    } 
  printf( "FTD2XX::new() allocated PFT_HANDLE: %d\n", $FTD->PFT_HANDLE() );

  my $numDevices = $FTD->GetNumDevices();
  unless( $FTD->PFT_STATUS() == FT_OK )
    {
    printf( STDERR "FTD2XX::GetNumDevices() failed: %s (%s)\n",  
            $FTD->PFT_STATUS_MSG(), $FTD->PFT_ERROR() );
    exit( 1 );
    } 
  printf( "Found $numDevices FTDI devices connected!\n" );

DESCRIPTION ^

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.

EXPORTS ^

The FT_OK status constant is the only default export, as it is the basis for testing even the object's new() call. The other symbol exports may be chosen as desired on the 'use Win32::FTDI::FTD2XX' line as shown in the synopsis. See the FTD2XX.H header file and the FTD2XX Programmer's Guide for more information on their values. The PFT specific symbols are explained in the METHODS section.

The full list of available exports is: FT_OK FT_INVALID_HANDLE FT_DEVICE_NOT_FOUND FT_DEVICE_NOT_OPENED FT_IO_ERROR FT_INSUFFICIENT_RESOURCES FT_INVALID_PARAMETER FT_INVALID_BAUD_RATE FT_DEVICE_NOT_OPENED_FOR_ERASE FT_DEVICE_NOT_OPENED_FOR_WRITE FT_FAILED_TO_WRITE_DEVICE FT_EEPROM_READ_FAILED FT_EEPROM_WRITE_FAILED FT_EEPROM_ERASE_FAILED FT_EEPROM_NOT_PRESENT FT_EEPROM_NOT_PROGRAMMED FT_INVALID_ARGS FT_NOT_SUPPORTED FT_OTHER_ERROR FT_DEVICE_LIST_NOT_READY PFTE_INVALID_API PFTE_MAX_HANDLES PFTE_INVALID_HANDLE PFTE_WAIT_TIMEOUT FT_BAUD_300 FT_BAUD_600 FT_BAUD_1200 FT_BAUD_2400 FT_BAUD_4800 FT_BAUD_9600 FT_BAUD_14400 FT_BAUD_19200 FT_BAUD_38400 FT_BAUD_57600 FT_BAUD_115200 FT_BAUD_230400 FT_BAUD_460800 FT_BAUD_921600 FT_BITS_8 FT_BITS_7 FT_BITS_6 FT_BITS_5 FT_STOP_BITS_1 FT_STOP_BITS_1_5 FT_STOP_BITS_2 FT_PARITY_NONE FT_PARITY_ODD FT_PARITY_EVEN FT_PARITY_MARK FT_PARITY_SPACE FT_FLOW_NONE FT_FLOW_RTS_CTS FT_FLOW_DTR_DSR FT_FLOW_XON_XOFF FT_PURGE_RX FT_PURGE_TX FT_DEFAULT_RX_TIMEOUT FT_DEFAULT_TX_TIMEOUT FT_DEVICE_BM FT_DEVICE_AM FT_DEVICE_100AX FT_DEVICE_UNKNOWN FT_DEVICE_2232C FT_DEVICE_232R PFT_FLOW_XonChar PFT_FLOW_XoffChar PFT_MODEM_STATUS_CTS PFT_MODEM_STATUS_DSR PFT_MODEM_STATUS_RI PFT_MODEM_STATUS_DCD PFT_BITMODE_RESET PFT_BITMODE_ASYNCBB PFT_BITMODE_MPSSE PFT_BITMODE_SYNCBB PFT_BITMODE_MHBEM PFT_BITMODE_FOISM PFT_BITMODE_CBUSBB PFT_MAX_SERIAL PFT_MAX_DESCR PFT_MAX_HANDLES

SEE ALSO ^

You'll probably want a copy of the FTDI D2XX Programmer's Guide to reference the corresponding API descriptions ...

http://www.ftdichip.com

OBJECT METHODS ^

The following methods have been provided for interaction with the P5FTD2XX and FTD2XX libraries. All methods set an internal status of type PFT_STATUS, which will include the values given in the standard FT_STATUS set (i.e. $FT_OK etc), as well as PFT specific values, (i.e. PFTE_INVALID_HANDLE). In some cases, if the method doesn't return some other specific value(s), it will generally return TRUE or FALSE (or undef) to indicate failure. Note: TRUE and FALSE are loosely bound to 1 and 0 respectively. On failure, the PFT_STATUS() accessor method can be used to query the PFT/FT_STATUS error value. PFT_ERROR_MSG() provides a quick string based translation of the error.

Standard parameter conventions apply: {required}, [optional], ...

In most cases, all numeric parameters are automatically packed and unpacked between their scalar and binary equivalents for passing into and out of the APIs. Only specific cases require the application to pack or unpack some datatypes, and will be covered in those methods.

New
  Parameters: [PFT_DEBUG => {FALSE|TRUE}]
  Returns: Object Reference (use PFT_STATUS method to check for errors)
  Purpose: Extension Method - Instanciates the FTDI perl object, loads the P5FTD2XX DLL
  and (as a dependency) the FTD2XX DLL. It will immediately import the PFT_New() and 
  PFT_Free() API's as a bare minimum, allocating a PFT_HANDLE type, which is this object
  instance's identifier to the P5FTD2XX library for its lifespan. PFT_HANDLE is synonymous
  with FT_HANDLE, and provides one per object instance. You may allocate a maximum of 
  PFT_MAX_HANDLES objects. 

  The object includes an auto DESTROY method that will close any open FTDI device handle
  and deallocate the PFT_HANDLE in the P5FTD2XX interface, when it gets garbage collected
  by Perl.

  For a description of optional PFT_DEBUG parameter, see the PFT_DEBUG Accessor Method.
GetNumDevices
  Parameters: None
  Return Success: $numDevices 
  Return Failure: undef
  Purpose: Abstraction Method - Returns the number of connected FTDI devices. 
  See FT_ListDevices().
Rescan
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_Rescan()

  Note: As with other bus controls, there is a wait period of 3-5 seconds after
  a USB bus scan where any API call that requires direct connection to the device, 
  like GetSerialByIndex() etc, will fail with FT_INVALID_HANDLE until it has 
  completely stabilized. The application should account for this wait period, or
  setup a polling loop to detect the change in return status.
Reload
  Parameters: {$devVID, $devPID}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_Reload()
ResetPort
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_ResetPort()
ResetDevice
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_ResetDevice()
CyclePort
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_CyclePort()
  
  Note: As with other bus controls, there is a wait period of 5-8 seconds after
  a CyclePort where any API call that requires direct connection to the device, 
  like GetSerialByIndex() etc, will fail with FT_INVALID_HANDLE until it has 
  completely stabilized. The application should account for this wait period, or
  setup a polling loop to detect the change in return status.
GetDriverVersion
  Parameters: None
  Return Success: $driverVersion
  Return Failure: undef
  Purpose: API Method - See FT_GetDriverVersion()
crackDriverVersion
  Parameters: [$driverVersion]
  Return Success: $driverVersionDotNotation
  Return Failure: undef
  Purpose: Convenience method - translates the numeric DWORD from the driver to
  the equivalent dot notation (ie. "00020405" -> "2.04.05"). 
  If $driverVersion is supplied, it should be of the form returned by GetDriverVersion.
  If $driverVersion is undefined, GetDriverVersion will be called first to get the value.
GetLibraryVersion
  Parameters: None
  Return Success: $libraryVersion
  Return Failure: undef
  Purpose: API Method - See FT_GetLibraryVersion()
crackLibraryVersion
  Parameters: [$libraryVersion]
  Return Success: $libraryVersionDotNotation
  Return Failure: undef
  Purpose: Convenience method - translates the numeric DWORD from the library to
  the equivalent dot notation (ie. "00030115" -> "3.01.15"). 
  If $libraryVersion is supplied, it should be of the form returned by GetLibraryVersion.
  If $libraryVersion is undefined, GetLibraryVersion will be called first to get the value.
GetSerialByIndex
  Parameters: {$devIndex}
  Return Success: $devSerial
  Return Failure: undef
  Purpose: Abstraction Method - Returns the serial string of the connected FTDI device
  at the given index. See FT_ListDevices().
GetDescrByIndex
  Parameters: {$devIndex}
  Return Success: $devDescription
  Return Failure: undef
  Purpose: Abstraction Method - Returns the description string of the connected FTDI device
  at the given index. See FT_ListDevices().
GetDeviceInfo
  Parameters: {$devIndex}
  Return Success: $devInfo
  Return Failure: undef
  Purpose: Abstraction Method - See FT_GetDeviceInfo(). Returns all the description strings
  via a hash reference of the form:
    $devInfo->{TypeID};  # raw numeric device type ID
    $devInfo->{TypeNm};  # translated TypeID name string
    $devInfo->{VID};     # device's VID
    $devInfo->{PID};     # device's PID
    $devInfo->{Serial};  # serial number string
    $devInfo->{Descr};   # description string
OpenBySerial
  Parameters: {$devSerial}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: Abstraction Method - Opens a connection to the device based on serial number.
  See FT_Open(). Note: The object's Close() method should be called to free any previously
  opened FT_HANDLE.
OpenByIndex
  Parameters: {$devIndex}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: Abstraction Method - Opens a connection to the device based on index number.
  See FT_Open(). Note: The object's Close() method should be called to free any previously
  opened FT_HANDLE.
Close
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_Close().
SetBaudRate
  Parameters: {$baudRate}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetBaudRate().
SetDivisor
  Parameters: {$divisor}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetDivisor().
SetDataCharacteristics
  Parameters: {$dataBits, $stopBits, $parityBits}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetDataCharacteristics().
SetFlowControl
  Parameters: {$flowCtrl} [, $XonChar, $XoffChar]
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetFlowControl(). 
  Note: The ANSI standard Xon/Xoff characters have been defined in 
  PFT_FLOW_XonChar (0x11), and PFT_FLOW_XoffChar (0x13).
SetTimeouts
  Parameters: {$readTimeout, $writeTimeout}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetTimeouts(). 
GetTimeouts
  Parameters: None
  Return Success: $readTimeout, $writeTimeout
  Return Failure: undef
  Purpose: Extension Method - query the current timeout values, as previously set
  in SetTimeouts().
SetReadTimeout
  Parameters: {$readTimeout}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: Extension Method - Sets the read timeout without disturbing the current
  write timeout value.
GetReadTimeout
  Parameters: None
  Return Success: $readTimeout
  Return Failure: undef
  Purpose: Extension Method - Gets the current read timeout value.
SetWriteTimeout
  Parameters: {$writeTimeout}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: Extension Method - Sets the write timeout without disturbing the current
  read timeout value.
GetWriteTimeout
  Parameters: None
  Return Success: $writeTimeout
  Return Failure: undef
  Purpose: Extension Method - Gets the current write timeout value.
SetDtr
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetDtr().
ClrDtr
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_ClrDtr().
SetRts
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetRts().
ClrRts
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_ClrRts().
SetBreakOn
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetBreakOn().
SetBreakOff
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetBreakOff().
GetStatus
  Parameters: None
  Return Success: $amountInRxQueue, $amountInTxQueue, $eventStatus
  Return Failure: undef
  Purpose: API Method - See FT_GetStatus().
GetQueueStatus
  Parameters: None
  Return Success: $amountInRxQueue
  Return Failure: undef
  Purpose: API Method - See FT_GetQueueStatus().
GetModemStatus
  Parameters: None
  Return Success: $modemStatus
  Return Failure: undef
  Purpose: API Method - See FT_GetModemStatus().
crackModemStatus
  Parameters: {$modemStatusBitmask}
  Return Success: $statusCTS, $statusDSR, $statusRI, $statusDCD
  Return Failure: undef
  Purpose: Convenience Method - Based on the provided bitmask, sets each value in the returning
  array to TRUE if bit is set, FALSE otherwise. See FT_GetModemStatus().
waitForModem
  Parameters: {$modemStatusBitmask} [, $timeout] [, $pollTm]
  Return Success: TRUE
  Return Failure: FALSE (Check PFT_STATUS - FT API failure or PFTE_WAIT_TIMEOUT set)
  Purpose: Extension Method - since the event API's are unimplemented, this method may be used
  to suspend program execution until one or more of the modem status bits is set (see
  GetModemStatus). 

  The modemStatusBitmask is formed using the PFT_MODEM_STATUS_xxx bit definitions. i.e.:
    $FTD->waitForModem( PFT_MODEM_STATUS_CTS, 3 );
  would wait max 3 seconds for the device's CTS signal to assert itself.

  The optional $timeout provides a limiting timeframe to wait, in seconds. Fractional seconds,
  i.e. 0.5 (500ms) are allowed. The timeout is infinite if undefined. 

  The optional $pollTm is the time in seconds between polls of the device. The default is 0.25
  (250ms). 

  Note: the timeout is NOT implemented in real time clock fassion, so it should not be used for
  critical timing sequences, but is accurate enough for most uses. When setting $timeout and/or
  $pollTm, $timeout should be an even multiple of $pollTm, or if not, the overlap in timing should
  be accounted for if neccessary. 
SetChars
  Parameters: {$eventCh, $eventChEn, $errorCh, $errorChEn}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetChars().
  Note: The $eventCh and $errorCh parameters should be specified in numeric form, 
  i.e.:  SetChars( 0x12, 1, 0x14, 1 );
SetResetPipeRetryCount
  Parameters: {$count}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetResetPipeRetryCount().
StopInTask
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_StopInTask().
RestartInTask
  Parameters: None
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_RestartInTask().
Purge
  Parameters: {$mask}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_Purge().
Read
  Parameters: {$bytesToRead}
  Return Success: $bytesReturned, $readBuffer
  Return Failure: undef
  Purpose: API Method - See FT_Read().
  Note: The method treats the returned buffer content as an opaque scalar value. Any translation
  of strings or unpacking of binary content must be done by the application.
Write
  Parameters: {$writeBuffer} [, $bytesToWrite]
  Return Success: $bytesWritten
  Return Failure: undef
  Purpose: API Method - See FT_Write().
  Note: The method treats the write buffer content as an opaque scalar value. Any translation
  of strings or packing of binary content must be done by the application.
  If $bytesToWrite is not specified, the method will use the return of 'length($writeBuffer)'.
  If $bytesToWrite is specified, it allows sending a full or partial buffer; however, the result
  of sending more bytes than are in the buffer is undefined.
GetLatencyTimer
  Parameters: None
  Return Success: $timer
  Return Failure: undef
  Purpose: API Method - See FT_GetLatencyTimer().
SetLatencyTimer
  Parameters: {$timer}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetLatencyTimer().
GetBitMode
  Parameters: None
  Return Success: $mode
  Return Failure: undef
  Purpose: API Method - See FT_GetBitMode().
SetBitMode
  Parameters: {$mode}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetBitMode().
  Note: The following EXPORTS for BitModes are available for convenience:
    PFT_BITMODE_RESET
    PFT_BITMODE_ASYNCBB
    PFT_BITMODE_MPSSE
    PFT_BITMODE_SYNCBB
    PFT_BITMODE_MHBEM
    PFT_BITMODE_FOISM
    PFT_BITMODE_CBUSBB
SetUSBParameters
  Parameters: {$inTransferSize, $outTransferSize}
  Return Success: TRUE
  Return Failure: FALSE
  Purpose: API Method - See FT_SetUSBParameters().
P5VERSION
  Parameters: None
  Return Success: $PFT_DLL_VERSION
  Return Failure: undef
  Purpose: Accesor Method - returns the version of the P5FTD2XX DLL in use.
VERSION
  Parameters: None
  Return Success: $FTD2XX_MODULE_VERSION
  Return Failure: undef
  Purpose: Accesor Method - returns the version of the FTD2XX.pm in use.
PFT_HANDLE
  Parameters: None
  Return Success: $PFT_HANDLE
  Return Failure: undef
  Purpose: Accesor Method - returns the numeric PFT_HANDLE allocated by the 
  P5FTD2XX library which identifies the object's unique connection and state
  information store.
PFT_STATUS
  Parameters: None
  Return Success: $PFT_STATUS
  Return Failure: undef
  Purpose: Accesor Method - returns the enumerated status/error values of the last
  method call (see FT and PFTE extensions in EXPORTS). In addition to the FT status
  types, the PFT specific error types are: 
  PFTE_INVALID_API - Requested API not in P5FTD2XX.DLL - usually a bug on my part, or the
    P5FTD2XX.DLL can't be found in the system PATH (default: "%SystemRoot%\System32")
  PFTE_INVALID_HANDLE - The PFT_HANDLE passed is not valid (also usually a bug on my part)
  PFTE_MAX_HANDLES - You've allocated max objects/PFT_HANDLES from the P5FTD2XX interface
  PFTE_WAIT_TIMEOUT - error type for 'waitForModem' method on timeout only
PFT_STATUS_MSG
  Parameters: [$PFT_STATUS]
  Return Success: $PFT_STATUS_MSG
  Return Failure: undef
  Purpose: Accesor Method - translates the enumerated FT_STATUS/PFT_STATUS values into
  text equivalent for ease of generating error output. If a specific $PFT_STATUS is not 
  provided, the method assumes the current state.
PFT_ERROR
  Parameters: None
  Return Success: $PFT_ERROR
  Return Failure: undef
  Purpose: Accesor Method - some methods may have extended error information regarding the
  failure reported in the (P)FT_STATUS types, and are returned here. 
PFT_DEBUG
  Parameters: {TRUE|FALSE}
  Return Success: $previousState
  Return Failure: undef
  Purpose: Accesor Method - some methods may have extended runtime debug information that
  can be sent to STDERR when this variable is set to TRUE.

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.

BUGS and THINGS TO DO ^

Please report bugs to me at my email address below.

See the BUGS file in the distribution for known issues and their status.

Things to Do

1) The FT_EVENT features have not been ported, and may or may not be, depending on demand (see the 'waitForModem' method instead for now).

2) Complete the DeviceInfoList/Detail Classic APIs.

3) Complete the EEPROM API interface.

4) Win the lottery, buy an island and retire ...

AND... if anyone is really just peeing their pants for a particular function that I haven't provided or ported yet, let me know and I'll see what I can do with the time I have.

AUTHOR ^

Scott K. MacPherson <skmacphe@cpan.org>

COPYRIGHT AND LICENSE ^

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.

syntax highlighting: