ftd2chan(n) 0.1 ftd2chan "FTD2 Channel Driver"

NAME

ftd2chan - Tcl Channel Driver for FTD2XX Chips

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COMMANDS
    CONFIGURATION OPTIONS
        -mode baud,parity,data,stop
        -handshake type
        -timeout
        -ttycontrol
        -xchar
        -pollinterval
        -purge which
        -reset bool
        -latency msec
        -bitmode {mask mode}
        -queue
        -ttystatus
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require ftd2chan ?0.1?

ftd2chan id ?vid pid?

ftd2chan list

ftd2chan open SerialNumber serialno

ftd2chan open Description description

This manpage describes a Tcl channel driver that interfaces to the FTD2XX Direct Driver for FTDI USB to UART converter chips. This FTDI driver is contained in software distributed by FTDI as libftd2xx.so. See http://www.ftdichip.com for details on the driver. This package provides one new command, ftd2chan that is an ensemble command. The ftd2chan command creates a Tcl channel to access the FTDI chip driver. The channel driver also provides the usual options associated with serial ports as well as access to the various bit-banging modes of the FTDI chips. In particular the provided channel can be used to access the MPSSE capability of an FT 2232 chip.

COMMANDS

ftd2chan id ?vid pid?

The ftd2chan id subcommand queries or sets the value of the USB Vendor Id and Product Id. If the optional vid and pid arguments are supplied then the current value for the Vendor Id and Product Id are set into the D2XX drive to be the given values. The command returns a two element list consisting of the current value of the Vendor Id and Product Id. By default the FTDI driver reports a Vendor Id of 0x403 and a Product Id of 0x6017. These correspond to the standard identifiers for FTDI products. It is necessary to set the Vendor Id and Product Id to match the value reported by the product that you wish to open a channel on. The D2XX driver will only access devices for which match the Vendor and Product Id set into the driver by this command. This command is usually invoked first, in order to register the correct Vendor and Product Id. To recognize a Luminary Micro LM3S811 evaluation board:

% ftd2chan id 0x403 0xbcd9 1027 48345

ftd2chan list

The ftd2chan list subcommand returns a list of recognized devices that match the Vendor Id and Product Id set by the ftd2chan id subcommand. Each element of the returned list is a two element dictionary whose keys are SerialNumber and Description. The D2XX driver identifies devices by either a Serial Number or a Description and devices may be opened either by Serial Number or Description. Since the FTDI 2232 chip has two channels, generally the returned list is of length two. However, any channel that is already opened (and therefore can't be reopened) will not be returned in the list. Thus applications should be prepared for the fact that not all channels may be returned and should be prepared to identify positively the desired channel rather than depending upon a specific list index. A Luminary Micro LM3S811 evaluation board appears as:

% ftd2chan list {SerialNumber {LM000001 A} Description {LM3S811 Evaluation Board A}} {SerialNumber {LM000001 B} Description {LM3S811 Evaluation Board B}}

A Luminary Micro LM3S6965 evaluation board appears as:

% ftd2chan list {SerialNumber {04110100 A} Description {Stellaris Evaluation Board A}} {SerialNumber {04110100 B} Description {Stellaris Evaluation Board B}}

ftd2chan open SerialNumber serialno

ftd2chan open Description description

The ftd2chan open subcommand is used to create a channel to the D2XX chip driver. The chip driver can open devices by either serial number or description. This command returns a channel handle which may be used to access the newly created channel. Note that the channel is always created as both readable and writable. To open the B device by serial number on a Luminary Micro LM3S811 evaluation board:

foreach dev [ftd2chan list] { set serialNo [dict get $dev SerialNumber] if {[string match *B* $serialNo]} { set fchan [ftd2chan open SerialNumber $serialNo] break } }

CONFIGURATION OPTIONS

The options supported by the ftd2chan follow closely those supported for serial ports when the open command is used. Much of the text below comes from the open manual page. The fconfigure or chan configure commands can be used to configure the various options for ftd2 channels:

-mode baud,parity,data,stop

This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The baud rate is a simple integer that specifies the connection speed. Parity is one of the following letters: n, o, e, m, s; respectively signifying the parity options of "none", "odd", "even", "mark", or "space". Data is the number of data bits and should be the integer 7 or 8, while stop is the number of stop bits and should be the integer 1 or 2. By default when the channel is opened, the mode is set to 38400 baud, no parity, 8 data bits and 1 stop bit. However, you are strongly encouraged to not depend upon any defaults for the -mode option and explicitly set the required mode after opening the channel.

-handshake type

This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating system. If type is none, then any handshake is switched off. A type of rtscts activates hardware handshake using request to send and clear to send hardware handshake lines. Another form of hardware handshake, dtrdsr, uses the data terminal ready and data set ready hardware handshake lines. For software handshake, xonxoff, the handshake characters can be redefined with -xchar. The -handshake option cannot be queried.

-timeout

This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the reception of two bytes in milliseconds. The -timeout option does not affect write operations or nonblocking reads. This option cannot be queried.

-ttycontrol

This option is used to setup the handshake output lines permanently or to send a BREAK over the serial line. The signal names are case-independent. {RTS 1 DTR 0} sets the RTS output to high and the DTR output to low. The BREAK condition is enabled and disabled with {BREAK 1} and {BREAK 0} respectively. It's not a good idea to change the RTS (or DTR) signal with active hardware handshake rtscts (or dtrdsr). The result is unpredictable. The -ttycontrol option cannot be queried.

-xchar

This option is used to query or change the software handshake characters. The default is DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters.

-pollinterval

This option is used to set the maximum time between polling for fileevents. This affects the time interval between checking for events throughout the Tcl interpreter (the smallest value always wins). Use this option only if you want to poll the serial port more or less often than 10 msec (the default).

-purge which

The -purge is purges the receive and transmit buffers in the device. If which is "rx" then the receive buffer is purged. If which is "tx" then the transmitt buffer is purged. If which is "both" then both the receive and transmit buffers are purged.

-reset bool

The -reset sends a reset command to the device if bool is true.

-latency msec

The -latency queries and sets the timeout used to flush any remaining data from the chip receive buffer. The time given is in milliseconds and can range from 2 to 255.

-bitmode {mask mode}

The -bitmode option is used to enable various bit modes of operations of the FTD chips. The argument to the option is a two element list. The first element is the bit mode mask which determines which determines the direction of the I/O pins. A bit value of 0 marks the corresponding pin as an input and 1 sets it as an output. The second element is a string from the set: {Reset AsynchronousBitBang SynchronousBitBang MPSSE MCUHostBusEmulation FastOpto-IsolatedSerial CBUSBitBang}. See the FTDI documentation for the meanings of these operating modes.