USB2.DLL
Version 1.7.8

An easy programming interface for the Cypress Cy7c68013(A) USB2.0 controller.

Available Languages:

• English (File: Usb2Dll_help_en.html)

• German (File: Usb2Dll_help.html)

• What is USB2.DLL?
• About USB High-Speed Interface Module V2.0 and V2.5 from Braintechnology
• Installation
• Some general things about this DLL
• Examples
• Header and Includes for different programming languages
• Latency times and speed
• Functions of the DLL
  • General functions
    • UsbInit
    • UsbGetError
    • UsbGetErrorStringByNr
    • UsbSetLicense
    • UsbCheckSpeed
    • UsbOpen
    • UsbClose
    • UsbGetVersion
    • UsbSetTimeout
    • UsbWaituSec <new>
    • UsbGetStatus <new>
    • UsbRetrieveAllErrors <new>
    • UsbDevicePresent <new>
    • UsbDeviceInitialized <new>
  • IO functions
    • UsbSetIOState
    • UsbSetIODir
    • UsbGetIOState
  • Port functions
    • UsbSetPortState
    • UsbSetPortDir
    • UsbGetPortState
• i²c-Bus functions
  • UsbI2CSetTimeout <new>
  • UsbI2CSetSpeed
  • UsbI2CWriteByte
  • UsbI2CWriteBytes
  • UsbI2CReadByte
  • UsbI2CReadBytes
  • UsbI2CWriteAndReadBytes
• i²c-EEProm functions
  • UsbEEpSetTimeout <new>
  • UsbEEpWriteByte
  • UsbEEpWriteBytes
  • UsbEEpReadByte
  • UsbEEpReadBytes
  • UsbEEpSetAddr
• SPI functions <new>
  • UsbSpiInit
  • UsbSpiTransfer
  • UsbSpiTransferByte
• Parallelport-functions
  • UsbParInit
  • mode 0-3
  • mode 4-7
  • mode 8-9
  • UsbParInitUsingArray
  • UsbParSetTimeout <new>
  • UsbParSetWaveforms <new>
  • UsbParOut
  • UsbParIn
  • UsbGetRdyState
• Troubleshooting
• Future extensions
• Version history
• Contact

The USB2.DLL is developed using the usb2.0 interface from Braintechnology. The interface is ideal to realize your own developments in the USB2.0 sector.

Pinout of the module:
 

Version 2.0		Version 2.5

Connections:

The DLL must be in the search path for DLLs. That is either the system-directory of the computer, or the directory of your application.

A registration using regsvr32 is not necessary, since this is no activex-dll.

Nearly every function has a call parameter named DevNum. It must contain the number of the USB interface you want to access. The first attached interface has the number 0, the second number 1, ...

If only one interface is attached, you have to pass the value 0.

The DLL has a debug console that can be activated by creating the registry key:
HKEY_LOCAL_MACHINE\Software\usb2dll

and creating a DWORD with the name "Debug" and the value "1".

When any dll function will be called a debug window gets opened showing error messages and other informations suitable for debugging purposes.

The Debug mode can be deactivated by deleting the key or setting the value "Debug" to 0.

There are 3 simple examples included, which clarify the access to the interface:

pardemo:

This program demonstrates the programming of the parallel bus. You have to press the button Initialize Parallel Interface before pressing any other button. A click on button Write! writes the count of bytes you specified in the edit-field to the parallel bus. A click on button  Read! does the equivalent for read access.

Note: This Demo uses parallel mode 4.

i²cdemo:

Using this example you can read and write values to the internal EEProm. The speed of the i²c-Bus can be selected (100/400KHz).

To write a value you have to fill the edit-fields ADDRESS and VALUE and click on the button Write.

For reading a value from the EEProm enter the ADDRESS and click on Read. The Read value will be shown in the value-field.

iodemo:

With the help of this example the states and directions of all IO-lines may be set or read.
Every I/O-Line is visualized with 3 elements:

• A "number", which can be changed to 0 or 1 by clicking on it. It sets the logic state of the IO-line. Changes affect themselves only, if the line is set as an output.
• An arrow, which indicates the current direction of the respective IO-line. If the arrow points left, the IO line is an Input, if it points right, it is an Output.
• A "LED", which indicates the current state (HI/Low) of the IO line.

Future versions will contain examples for Visual C++ and Visual Basic.

The folder "Includes" contains includes and samples for different programming languages like Visual Basic, Delphi and Visual C++

If you want to use the DLL in another programming language and no include exists you may perhaps need a description of the used data types in call- and return parameters:

Data type	length in Bytes	signed/unsigned	Description
boolean	1	-	A boolean contains the value 1 (=true) oder 0 (=false)
byte	1	unsigned	An unsigned value from 0 to 255
word	2	unsigned	An unsigned value from 0 to 65535
dword	4	unsigned	An unsigned value from 0 to (2^32)-1
pchar	4	-	Pointer to a zero terminated string (as it is used in C)
pointer	4	-	An untyped Pointer

If the keyword "Var" is used in front of a parameter, a pointer to a value is expected. It is equivalent to the "*" operator in C, or the keyword "byRef" in Visual Basic.

Initializes the USB interface specified by DevNum. The Initialization procedure programs the current firmware to the controller and its call is necessary to be able to communicate with the controller.

If no license is set before calling UsbInit the function tries to find a file named "license.dat" in the current working directory and the DLL's folder. If this file it found, the license will be set automatically.

The interface is not opened exclusively, i.e. several programs can access the Interface at the same time. Therefore no "closing" of the DLL is necessary.

If an error occurs during communication with the interface, this function delivers the error number. If the returned value is 0, no error occurred. After calling this function, the reported error will be cleared.

The error number can also be automatically translated to a human readable string by calling the function UsbGetErrorStringByNr.

When passing the Error number retrieved by UsbGetError in ErrNr, a pointer to the error message will be returned in PString. For compatibility reasons a pointer to a PChar will be used. A PChar is a pointer to a zero terminated Array of Char, as it is used in C or several windows-api functions.

PString is a "pointer to a pointer to a string array", so an address of a pchar will be received using this function.

function UsbSetLicense(Filename : PChar) : boolean;

If this function is not executed before calling any other function of the dll, a messagebox will be shown about every 5 minutes to indicate that you are using a demo version. If you have registered and got a license-file from us, you have to pass the Filename (and Path) of the license-file to remove the popup window.

If no path is specified the file will be opened from the current working directory (CWD).

function UsbCheckSpeed(DevNum : Byte; var Speed : Byte) : boolean;

Returns a value in variable Speed. If Speed is 0, the usb controller is connected to a usb1.1, if Speed is 1 to a USB2 host controller.

function UsbOpen(DevNum : Byte) : boolean;

If this function is not used, the device will be opened and closed every time you call a function of the dll. This results in a small loss of time, but multiple applications can access the device at the same time.

If you call this function, the device will be opened exclusive and speed up data transfers, but you have to call the function UsbClose when your application exists.

This function has to be called (if it is used) after calling the function UsbInit.

function UsbClose(DevNum : Byte) : boolean;

Closes the device, when it has been opened using UsbOpen. If UsbOpen is not used, UsbClose does not need to be called.

procedure UsbGetVersion(VersionStr : PChar);

Returns the Versionnumber of usb2dll as String in VersionStr. VersionStr has to point to a memory area of at least 8 Byte length.

function UsbSetTimeout(DevNum : Byte; timeout : Word) : boolean;

Will set the timeout for i2c and parallel bus transfers. The parameter timeout specifies the timeout in count of milliseconds (for example 5 is equivalent to 5ms).

The default value is 10 milliseconds.

Waits for the specified count of micro seconds (=1/1000ms or 1/1000000 s).

If the retrieving of error codes is turned of by UsbRetrieveAllErrors this function can be called to manually retrieve the status from the firmware.

Some functions (currently UsbI2cWriteByte(s) and UsbParOut) retrieve an error code from the firmware, although it might not be needed. This additional retrievment of the error code slows down the execution of the command, as an additional usb transfer is needed.
With the parameter RetrieveAll = false this additional error retrievement can be turned off.

The default is that error codes are read from the firmware.

function UsbDevicePresent(DevNum : Byte) : Boolean;

This function returns true (1) if the specified Device is present. It it returns false the driver is not installed correctly or the device is not connected.

function UsbDeviceInitialized(DevNum : Byte) : Boolean;

UsbDeviceInitialized returns true (1) if UsbInit has been called for the specified DevNum before. If it has not been called the function will return false (0).

A single IO line can be set to High (State=1) or Low (State=0). LineNum must contain the number of the IO line you want to set.

The assignment is as follows:

PortC and PortE are only available for the -100 and -128 version of the FX2 controller.

The IO-Line must be programmed as output by using UsbSetIODir or UsbSetPortDir, to make the changes affect.

Sets the direction of a single IO line to output (Dir=1) or input (Dir=0). After initialization of the interface all io lines are set as input (tristate).

The assignments of LineNum to IO-lines corresponds to UsbSetIOState.

Returns in parameter State the condition of an IO-line. If it is High, then State=1, is it Low, then State=0.

The assignments of LineNum to IO-lines corresponds to UsbSetIOState.

Sets one of the ports to the states passed by the parameter State. PortNum is the number of the io-port you want to modify. 

The assignments are as follows:

If a bit of State is 1, the appropriate port pin is switched to high-state.

To make the changes affect, the directions of IO-Lines have to be set to Output using UsbSetIODir or UsbSetPortDir.

Sets the direction bits of the port specified by PortNum.

If a bit is 1, the appropriate io line becomes an output, otherwise an input.

The assignments of PortNum to the io-ports are the same as in UsbSetPortState

Returns the state of the port specified by PortNum.

The assignments of PortNum to the io-ports are the same as for UsbSetPortState

As a non-working i2c slave or a short circuit of the i2c bus lines might halt a transfer, a timeout is implemented for i2c transfers. It can be set using the functions UsbSetTimeout or UsbI2cSetTimeout. The default timeout value is 10ms.
 

A usual i2c slave address is composed of a 7 bit address and 1 Read/Write bit:

Bit7	Bit6	Bit5	Bit4	Bit3	Bit2	Bit1	Bit0
A6	A5	A4	A3	A2	A1	A0	R/W

All i2c transfer functions expect just the 7 bit address (A0-6) for their "slaveaddress" parameter, as the R/W bit is added internally:
 

Bit7	Bit6	Bit5	Bit4	Bit3	Bit2	Bit1	Bit0
0	A6	A5	A4	A3	A2	A1	A0

function UsbI2CSetTimeout(DevNum : Byte; Timeout : Word) : Boolean;

Sets the timeout for I2C transfers in millisecond steps. The default timeout is 10 ms.

Sets the speed of i²c interface. If Speed=0 is passed, the i²c works with a clock of 100khz. Speed=1 switches i²c interface to high speed mode (400khz clock).

Writes the byte Data to the i²c-device with the 7-bit slave address SlaveAddr.

Writes the block of Data specified by pointer P with the length Length to the i²c device with 7-bit slave address SlaveAddr.

If Length is zero, 65536 Bytes will be written.

Reads a single Byte from i²c-device with the 7-bit slave address SlaveAddr. The read value will be passed to Data.

Reads a data block with the length of Length Bytes from the i²c-device with the 7-bit slave adress SlaveAddr.

If Length is zero, 65536 bytes will be read.

Writes the block of Data specified by pointer PWrite with the length WriteLen to the i²c device with slave address SlaveAddr. After writing a Count of Readlen Bytes will be read from the same i²c-device. The read values will be placed in the buffer PRead points to.

Between the write and the read transfer a restart condition will be sent.

If WriteLen or ReadLen is zero, 65536 bytes will be read or written.

function UsbEEpSetTimeout(DevNum : Byte; Timeout : Word) : Boolean;

Sets the timeout for the EEprom write cycle. This timeout should be greater than the twp value of the eeprom. The default timeout is 10ms.

Writes the Data byte Data to the address Addr of the internal EEProm.

Writes a data block specified by Pointer PData with a length of Length Bytes to the EEProm address Addr.

Reads a single data byte from address Addr of internal EEProm. The read value will be returned in Data. 

Reads a Data block with the length of Length Bytes from the internal EEProm. The read values will be written to the memory PData points to.

function UsbEEpSetAddr(DevNum, SlaveAddr : Byte) : boolean;

This function sets the i2c-slaveaddress of the eeprom.

The adresses of the 2 diffrent USB2-modules from  Braintechnology are:

If you use the new version you have to call UsbEEpSetAddr like this:

UsbEEpSetAddr(0, 0x51);

The SPI bus functions implement a SPI master and consists of 4 I/O lines:

PortA.7 = /SS (Slave select - Output)
PortA.6 = SCK (Clockline - Output)
PortA.5 = MOSI (Master Out Slave In - Output)
PortA.4 = MISO (Master In Slave Out - Output)

Data is transfered bit-wise synchronous to SCK over the data lines MOSI and MISO. /SS gets low before a data byte will be transfered and high after a byte has been transfered.
 

function UsbSpiInit(DevNum : Byte; LsbFirst : Boolean; SPIMode : Byte; Speed : Byte) : Boolean;

Initializes the Spi bus with the specified parameters:

If LsbFirst is true (1), the first bit transfered is the LSB (Bit 0), if it is false (0), the MSB (Bit 7) will be transfered first.

Speed selects the bitrate of the bus:

0 = 50 kHz
1 = 25 kHz
2 = 10 kHz
3 = 5 kHz
4 = 2 kHz
5 = 1 kHz

SPIMode defines the idle state of the clockline and the edges data is transfered:

Bit 0 = 0: The Idle state of SCK is 0. The leading edge is a 0 to 1 transition, trailing edge a 1 to 0 transition
Bit 0 = 1: The Idle state of SCK is 1. The leading edge is a 1 to 0 transition, trailing edge a 0 to 1 transition

Bit 1 = 0: Data is sampled at leading edge of SCK and Setup on the trailing edge
Bit 1 = 1: Data is sampled at trailing edge of SCK and Setup on the leading edge

function UsbSpiTransfer(DevNum : Byte; PWrite, PRead : Pointer; Len : Word) : Boolean;

Transfers a Datablock in both directions (in and out) over the SPI bus. Len specifies the count of byte to be transfered, PWrite has to point to a data block with data bytes to be written, PRead will receive the read data.

function UsbSpiTransferByte(DevNum : Byte; DatWrite : Byte; var PDatRead : Byte) : Boolean;

Transfers a single Byte (8 bit) in both directions using the SPI bus.

The parallel port functions implement the GPIF of the FX2 controller. The GPIF is basically a hardware-statemachine that can describe how the data should be transfered over the parallel bus. Although other characteristics of the bus can be selected, like the buswidth (8/16 bit), the clockrate (and source) of the statemachine that influences the burst rate, etc.

As it is not very easy to generate a GPIF waveforms there are 10 predefined "parallel modes" available that can be initialized using the function UsbParInit.

GPIF waveforms can also be created using the included program ParBusEditor or the GPIF Designer from Cypress. ParBusEditor creates directly a data block containing the graphically defined waveforms and parameters. The GPIF Designer from Cypress generates a gpif.c template that can be converted to a usb2dll data block using the included utility "GpifCconverter".
When a self generated waveform should be used the Parallel bus has to be initialized using the function UsbParInitUsingArray instead of UsbParInit.

As data is transfered in packets over the USB this behaviour will also be reflected in parallel bus transfers. The data is rather transfered in max. 512 byte (USB2) or 64 byte (USB1) sized rather than a single contiguos data packet. If the connected peripheral requires an equidistant data transfer (for example video/audio streaming applications) an external FIFO needs to be connected.

function UsbParInit(DevNum, mode :Byte) : boolean;


Initializes the Parallel interface (=Parallel bus). An initialization is necessary, to transfer Data over the parallel bus.

The following modes are implemented:

function UsbParInitUsingArray(DevNum, Data : Pointer) : boolean; 

Initializes the Parallel interface using a data block. If the above descibed modes don't fullfill your needs you can create a datablock using the Cypress GPID designer (+ GpifCconverter) or our tool ParBusEditor. Theese tools generate a data block that can be passed as a pointer to this function to initialize the parallel bus.

This function sets the timeout for Parallel bus transfers. If data is not transfer during the specified Timeout, the transfer will be stopped. The default value is 10ms.

The GPIF can contain 4 waveforms. This functions enables you to select which waveform should be used for a following write access (OutWfIdx) or read access (InWfIdx).

function UsbParOut(DevNum : Byte; PData : Pointer; Len : DWord) : boolean; 

Outputs a number of Len data words to the parallel bus. PData is a pointer to the data block to transfer. If the transfer times out the function returns with false (0). The timeout can be set using the functions UsbSetTimeout or UsbParSetTimeout.

Examples:

If the interface is in 8 Bit mode and 768 bytes have to be transferred:

UsbParOut(0, @Buffer, 768);

If the interface is in 16 Bit mode and 768 Bytes (=384 Words) have to be transmitted:

UsbParOut(0, @Buffer, 384);

function UsbParIn(DevNum : Byte; PData : Pointer; Len : DWord) : boolean; 

Reads Len data words from the parallel bus. PData is a pointer to the Data block, which should receive the read values. If the transfer times out the function returns with false (0). The timeout can be set using the functions UsbSetTimeout or UsbParSetTimeout.

Examples:

If the interface is in 8 Bit mode and 768 bytes have to be transferred:

UsbParOut(0, @Buffer, 768);

If the interface is in 16 Bit mode and 768 Bytes (=384 Words) have to be received:

UsbParOut(0, @Buffer, 384);

function UsbGetRdyState(DevNum : Byte; var Rdy : Byte) : boolean; stdcall;

Returns in Rdy the state of the RDYx-lines (RDY0, RDY1, etc.).

The state of Bit0 equals the state of RDY0, Bit 1=RDY1, ...

• Programming of examples and includes for Visual C++, Labview and Java
• Programming of an event mechanism, which calls special program sections after appearance of hardware interrupts (e.g. pressing a button connected to an io-line)
• ...and much more