File Coverage

blib/lib/Win32/FTDI/FTD2XX.pm

Criterion	Covered	Total	%
statement	10	12	83.3
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	14	16	87.5

#!perl
################################################################################
#
# Description: Perl5 FTDI CDM Driver Interface Module
#
# Author     : Scott K. MacPherson, (c) Copyright 2008, All Rights Reserved
#
#
# $Id: FTD2XX.pm,v 1.4 2008/11/17 15:03:33 395502 Exp $
#
################################################################################

package Win32::FTDI::FTD2XX;

use 5.008008;
use strict;
require Exporter;
use AutoLoader qw(AUTOLOAD);

use Win32::API;       # DLL calling interface

our $VERSION = do { my @r = (q$Revision: 1.4 $ =~ /\d+/g); sprintf( "%d."."%02d" x $#r, @r ) };

use vars qw( $VERSION @ISA @EXPORT @EXPORT_OK );

our @ISA = qw( Exporter );

# default export list
our @EXPORT = qw(
  FT_OK
);

# available for export to caller
our @EXPORT_OK = qw(
  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
);

#######################################
# Definitions from FTD2XX.H and P5FTD2XX.H

# Specific parameter datatypes
Win32::API::Type->typedef( 'PFT_HANDLE', 'DWORD' );
Win32::API::Type->typedef( 'PPFT_HANDLE', 'LPDWORD' );
Win32::API::Type->typedef( 'PFT_STATUS', 'DWORD' );

# Enumerated device status types
use constant FT_OK => 0;
use constant FT_INVALID_HANDLE => 1;
use constant FT_DEVICE_NOT_FOUND => 2;
use constant FT_DEVICE_NOT_OPENED => 3;
use constant FT_IO_ERROR => 4;
use constant FT_INSUFFICIENT_RESOURCES => 5;
use constant FT_INVALID_PARAMETER => 6;
use constant FT_INVALID_BAUD_RATE => 7;
use constant FT_DEVICE_NOT_OPENED_FOR_ERASE => 8;
use constant FT_DEVICE_NOT_OPENED_FOR_WRITE => 9;
use constant FT_FAILED_TO_WRITE_DEVICE => 10;
use constant FT_EEPROM_READ_FAILED => 11;
use constant FT_EEPROM_WRITE_FAILED => 12;
use constant FT_EEPROM_ERASE_FAILED => 13;
use constant FT_EEPROM_NOT_PRESENT => 14;
use constant FT_EEPROM_NOT_PROGRAMMED => 15;
use constant FT_INVALID_ARGS => 16;
use constant FT_NOT_SUPPORTED => 17;
use constant FT_OTHER_ERROR => 18;
use constant FT_DEVICE_LIST_NOT_READY => 19;
#PFT specific error additions
use constant PFTE_INVALID_API => 100;
use constant PFTE_MAX_HANDLES => 101;
use constant PFTE_INVALID_HANDLE => 102;
use constant PFTE_WAIT_TIMEOUT => 103;

# STATUS Translation - accessed only via PFT_STATUS_MSG()
my %PFTMsg = (
  @{[FT_OK]} => "OK",
  @{[FT_INVALID_HANDLE]} => "FT_INVALID_HANDLE",
  @{[FT_DEVICE_NOT_FOUND]} => "DEVICE_NOT_FOUND",
  @{[FT_DEVICE_NOT_OPENED]} => "DEVICE_NOT_OPENED",
  @{[FT_IO_ERROR]} => "IO_ERROR",
  @{[FT_INSUFFICIENT_RESOURCES]} => "INSUFFICIENT_RESOURCES",
  @{[FT_INVALID_PARAMETER]} => "INVALID_PARAMETER",
  @{[FT_INVALID_BAUD_RATE]} => "INVALID_BAUD_RATE",
  @{[FT_DEVICE_NOT_OPENED_FOR_ERASE]} => "DEVICE_NOT_OPENED_FOR_ERASE",
  @{[FT_DEVICE_NOT_OPENED_FOR_WRITE]} => "DEVICE_NOT_OPENED_FOR_WRITE",
  @{[FT_FAILED_TO_WRITE_DEVICE]} => "FAILED_TO_WRITE_DEVICE",
  @{[FT_EEPROM_READ_FAILED]} => "EEPROM_READ_FAILED",
  @{[FT_EEPROM_WRITE_FAILED]} => "EEPROM_WRITE_FAILED",
  @{[FT_EEPROM_ERASE_FAILED]} => "EEPROM_ERASE_FAILED",
  @{[FT_EEPROM_NOT_PRESENT]} => "EEPROM_NOT_PRESENT",
  @{[FT_EEPROM_NOT_PROGRAMMED]} => "EEPROM_NOT_PROGRAMMED",
  @{[FT_INVALID_ARGS]} => "INVALID_ARGS",
  @{[FT_NOT_SUPPORTED]} => "NOT_SUPPORTED",
  @{[FT_OTHER_ERROR]} => "OTHER_ERROR",
  @{[FT_DEVICE_LIST_NOT_READY]} => "DEVICE_LIST_NOT_READY",
  @{[PFTE_INVALID_API]} => "INVALID_API",
  @{[PFTE_MAX_HANDLES]} => "MAX_HANDLES_REACHED",
  @{[PFTE_INVALID_HANDLE]} => "PFT_INVALID_HANDLE",
  @{[PFTE_WAIT_TIMEOUT]} => "WAIT_TIMEOUT",
  );

# Baud Rates
use constant FT_BAUD_300 => 300;
use constant FT_BAUD_600 => 600;
use constant FT_BAUD_1200 => 1200;
use constant FT_BAUD_2400 => 2400;
use constant FT_BAUD_4800 => 4800;
use constant FT_BAUD_9600 => 9600;
use constant FT_BAUD_14400 => 14400;
use constant FT_BAUD_19200 => 19200;
use constant FT_BAUD_38400 => 38400;
use constant FT_BAUD_57600 => 57600;
use constant FT_BAUD_115200 => 115200;
use constant FT_BAUD_230400 => 230400;
use constant FT_BAUD_460800 => 460800;
use constant FT_BAUD_921600 => 921600;

# Word Lengths
use constant FT_BITS_8 => 0x08;
use constant FT_BITS_7 => 0x07;
use constant FT_BITS_6 => 0x06;
use constant FT_BITS_5 => 0x05;

# Stop Bits
use constant FT_STOP_BITS_1 => 0x00;
use constant FT_STOP_BITS_1_5 => 0x01;
use constant FT_STOP_BITS_2 => 0x02;

# Parity
use constant FT_PARITY_NONE => 0x00;
use constant FT_PARITY_ODD => 0x01;
use constant FT_PARITY_EVEN => 0x02;
use constant FT_PARITY_MARK => 0x03;
use constant FT_PARITY_SPACE => 0x04;

# Flow Control
use constant FT_FLOW_NONE => 0x0000;
use constant FT_FLOW_RTS_CTS => 0x0100;
use constant FT_FLOW_DTR_DSR => 0x0200;
use constant FT_FLOW_XON_XOFF => 0x0400;
use constant PFT_FLOW_XonChar => 0x11;   # CTRL-Q (ANSI standard)
use constant PFT_FLOW_XoffChar => 0x13;  # CTRL-S (ANSI standard)

# Purge rx and tx buffers
use constant FT_PURGE_RX => 1;
use constant FT_PURGE_TX => 2;

# GetModemStatus() flags
use constant PFT_MODEM_STATUS_CTS => 0x00000010;
use constant PFT_MODEM_STATUS_DSR => 0x00000020;
use constant PFT_MODEM_STATUS_RI => 0x00000040;
use constant PFT_MODEM_STATUS_DCD => 0x00000080;

# Get/Set BitMode masks
use constant PFT_BITMODE_RESET => 0x00;
use constant PFT_BITMODE_ASYNCBB => 0x01;
use constant PFT_BITMODE_MPSSE  => 0x02;
use constant PFT_BITMODE_SYNCBB => 0x04;
use constant PFT_BITMODE_MHBEM => 0x08;
use constant PFT_BITMODE_FOISM => 0x10;
use constant PFT_BITMODE_CBUSBB => 0x20;

# Events (NOT IMPLEMENTED IN PERL CODE YET)
#typedef VOID (*PFT_EVENT_HANDLER)(DWORD,DWORD);
#
#my $FT_EVENT_RXCHAR = 1;
#my $FT_EVENT_MODEM_STATUS = 2;

# Timeouts
use constant FT_DEFAULT_RX_TIMEOUT => 300;
use constant FT_DEFAULT_TX_TIMEOUT => 300;

# Enumerated Device types
use constant FT_DEVICE_BM => 0;
use constant FT_DEVICE_AM => 1;
use constant FT_DEVICE_100AX => 2;
use constant FT_DEVICE_UNKNOWN => 3;
use constant FT_DEVICE_2232C => 4;
use constant FT_DEVICE_232R => 5;

# FT Device Translation - accessed only via GetDeviceInfo()
our %FT_DEVICE_TYPE = (
  @{[FT_DEVICE_BM]} => 'FT_DEVICE_BM',
  @{[FT_DEVICE_AM]} => 'FT_DEVICE_AM',
  @{[FT_DEVICE_100AX]} => 'FT_DEVICE_100AX',
  @{[FT_DEVICE_UNKNOWN]} => 'FT_DEVICE_UNKNOWN',
  @{[FT_DEVICE_2232C]} => 'FT_DEVICE_2232C',
  @{[FT_DEVICE_232R]} => 'FT_DEVICE_232R',
  );

# Misc limits
use constant PFT_MAX_SERIAL => 32;     # max serial number string buffer
use constant PFT_MAX_DESCR => 64;      # max description string buffer
use constant PFT_MAX_HANDLES => 50;    # max allocated PFT_HANDLES
use constant PFT_WAIT_POLLTM => 0.25;  # default 250ms wait method poll cycle time

################################################################################
# DLL functions to import (Win32::API parameter/pack syntax)
# Note: As of this writing, the Win32::API prototype interface from v0.55
# seemed to have issues handling these correctly, and would abort often.
# However, reverting to the legacy positional/pack parameter interface
# works fine.
################################################################################
my $P5FTD2XX_DLL = "p5ftd2xx";

# Note: all functions return L/DWORD type
my %PFT_Imports = (
  'PFT_Version' => 'P',
  'PFT_New' => 'P',
  'PFT_Free' => 'L',
  'PFT_ValidHandle' => 'L',
  'PFT_Status' => 'L',
  'PFT_GetSerialByIndex' => 'LLP',
  'PFT_GetDescrByIndex' => 'LLP',
  'PFT_OpenByIndex' => 'LL',
  'PFT_OpenBySerial' => 'LP',
  'PFT_Rescan' => 'L',
  'PFT_Reload' => 'LII',
  'PFT_ResetPort' => 'L',
  'PFT_CyclePort' => 'L',
  'PFT_GetDriverVersion' => 'LP',
  'PFT_GetLibraryVersion' => 'LP',
  'PFT_GetNumDevices' => 'LP',
  'PFT_GetDeviceInfo' => 'LPPPP',
  'PFT_Close' => 'L',
  'PFT_SetBaudRate' => 'LL',
  'PFT_SetDivisor' => 'LI',
  'PFT_SetDataCharacteristics' => 'LIII',
  'PFT_SetFlowControl' => 'LIII',
  'PFT_SetTimeouts' => 'LLL',
  'PFT_SetDtr' => 'L',
  'PFT_ClrDtr' => 'L',
  'PFT_SetRts' => 'L',
  'PFT_ClrRts' => 'L',
  'PFT_SetBreakOn' => 'L',
  'PFT_SetBreakOff' => 'L',
  'PFT_GetStatus' => 'LPPP',
  'PFT_GetQueueStatus' => 'LP',
  'PFT_GetModemStatus' => 'LP',
  'PFT_SetChars' => 'LIIII',
  'PFT_SetResetPipeRetryCount' => 'LL',
  'PFT_SetDeadmanTimeout' => 'LL',
  'PFT_StopInTask' => 'L',
  'PFT_RestartInTask' => 'L',
  'PFT_Purge' => 'LL',
  'PFT_ResetDevice' => 'L',
  'PFT_Read' => 'LPLP',
  'PFT_Write' => 'LPLP',
  'PFT_GetLatencyTimer' => 'LP',
  'PFT_SetLatencyTimer' => 'LI',
  'PFT_GetBitMode' => 'LP',
  'PFT_SetBitMode' => 'LII',
  'PFT_SetUSBParameters' => 'LLL',
  );
#
# End of FTD2XX/P5FTD2XX defs
#
################################################################################
# Object Constructor/Destructors
#
sub new
  {
  my $class = shift;
  my $self = {
  # public/user definable settings
  PFT_DEBUG => 0,         # toggles debug output
  @_,
  # private object data
  _PFT_HANDLE => 0,        # handle of opened FTDI device
  _PFT_STATUS => FT_OK,   # status of last PFT call
  _PFT_ERROR => "",        # error message string
  # _{function}            # imported function references
  };
  bless( $self, $class );

  # import the bare minimum from the DLL to get started
  return( $self ) unless( _importDll( $self, "PFT_New" ) );
  return( $self ) unless( _importDll( $self, "PFT_Free" ) );

  my $PFT_HANDLE = pack( 'L', 0 );  # create storage for the handle
  if( $self->{_PFT_STATUS} = $self->{_PFT_New}->Call( $PFT_HANDLE ) )
    {
    return( $self );
    }
  $self->{_PFT_HANDLE} = unpack( 'L', $PFT_HANDLE );
  return( $self );

  } # new();

########################################
#
sub DESTROY
  {
  my $self = shift;
  if( $self->{_PFT_Free} && $self->{_PFT_HANDLE} )
    {
    printf( STDERR "Win32::FTDI::DESTROY() Freeing PFT_HANDLE: %d\n",
            $self->{_PFT_HANDLE} ) if( $self->{PFT_DEBUG} );
    $self->{_PFT_Free}->Call( $self->{_PFT_HANDLE} );
    }
  return( 1 );
  }

################################################################################
# Accessor Methods
#
sub VERSION
  {
  my $self = shift;
  return( $VERSION );  # return our (module) version
  }

########################################
#
sub PFT_HANDLE
  {
  my $self = shift;
  return( $self->{_PFT_HANDLE} );  # return PFT handle number in use
  }

########################################
#
sub PFT_STATUS
  {
  my $self = shift;
  return( $self->{_PFT_STATUS} );
  }

########################################
#
sub PFT_STATUS_MSG
  {
  my $self = shift;
  my $PFT_Errno = shift;

  # if specific status translation is not requested, return current
  return( $PFTMsg{$self->{_PFT_STATUS}} ) unless( defined($PFT_Errno) );
  return( $PFTMsg{$PFT_Errno} );
  }

########################################
#
sub PFT_ERROR
  {
  my $self = shift;
  return( $self->{_PFT_ERROR} );
  }

########################################
#
sub PFT_DEBUG
  {
  my $self = shift;
  my $new = shift;

  if( $new )
    {
    my $old = $self->{PFT_DEBUG};
    $self->{PFT_DEBUG} = $new;
    return( $old );  # return previous debug state
    }
  return( $self->{PFT_DEBUG} );
  }

################################################################################
# Private Object Methods
#
sub _importDll
  {
  my $self = shift;
  my $function = shift;

  # check to make sure we have an import definition for the requested function
  unless( exists( $PFT_Imports{$function} ) )
    {
    $self->{_PFT_STATUS} = PFTE_INVALID_API;
    $self->{_PFT_ERROR} = "No '$function' API in DLL import list";
    return( 0 );
    }

  # check to make sure we haven't imported this before
  if( $self->{"_$function"} )
    {
    $self->{_PFT_STATUS} = PFTE_INVALID_API;
    $self->{_PFT_ERROR} = "API previously imported";
    return( 0 ); # fail
    }

  # import the function
  print( "Win32::FTDI::_importDll( $function($PFT_Imports{$function}))\n" ) if( $self->{PFT_DEBUG} );
  my $f = Win32::API->new( $P5FTD2XX_DLL, $function, $PFT_Imports{$function}, 'L', '_cdecl' );
  unless( $f )
    {
    $self->{_PFT_STATUS} = PFTE_INVALID_API;
    $self->{_PFT_ERROR} = "$!";
    return( 0 ); # fail
    }

  # store the reference for use
  $self->{"_$function"} = $f;
  return( 1 );   # success

  } # _importDll()

################################################################################
1;
__END__