Cyusb Linux User Guide

cyusb_linux_user_guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 18

Download
Open PDF In Browser	View PDF

1

CyUSB Suite for Linux
Version 1.0.5

User Guide

2
(C) Cypress Semiconductor Corporation / ATR Educational Devices (P) Ltd [ www.atr-labs.com ]

1

Document Version History
Version

Date

Author

Notes

1.0

07/25/12

V.Radhakrishnan

1.0.1

08/13/12

Cypress
Semiconductor

Updated for general software release.

1.0.2

10/01/12

Cypress
Semiconductor

Changes to fix false download failure to the
FX3 device.

1.0.3

01/23/13

Cypress
Semiconductor

Updated the library to allow more device ID
pairs to be supported.

1.0.4

07/11/13

Cypress
Semiconductor

Changes to the cyusb_linux utility to allow
automated firmware download to EEPROM or
SPI Flash.
Added download_fx3 and download_fx2
example utilities to faciltate firmware
download for FX3 and FX2LP devices.

1.0.5

05/08/15

Cypress
Semiconductor

Added streamer functionality to the
cyusb_linux utility.
Added a new console utility to measure data
transfer performance.

Original version submitted to Cypress for
review.

2

Chapter - 1 : Introduction
The CyUSB Suite for Linux provides a set of tools for users to program and communicate with
Cypress EZ-USB devices over the USB port. The software functionality is analogous to the Cypress
USBSuite software for Windows platforms, and is built around the open source libusb-1.0 library.
This document describes how to install, configure and use the CyUSB Suite for Linux software.
This software allows you to download (“Program”) firmware images onto the EZ-USB FX2,
FX2LP and EZ-USB FX3 based devices, and test the various interfaces / alternate interfaces on the
device.
This software does not include any firmware source code for the EZ-USB parts or tools for
generating the firmware binaries. A set of pre-compiled firmware binaries that are extracted from
the Software Development Kits (SDK) for FX2 and FX3 are included. The actual firmware itself is
developed using other tools offered by Cypress, notably the SDKs.
There are two companion documents available for Linux :
1. This guide, also known as the CyUSB Suite for Linux User Guide, and
2. The CyUSB Suite for Linux - Programmers Reference Manual, which describes the driver
for linux and how to build and integrate user-written applications with the driver.
The software itself has been developed on top of the opensource libusb driver available at
http://sourceforge.net/projects/libusb/files/libusb-1.0/
under which directory various versions are available. At the moment of this writing, the version
used is libusb-1.0.16.tar.bz2.
This version of the CyUSB Suite for Linux has been developed and tested on the following
environment :
1.

Linux Kernel - 3.13.0 ( stock kernel from http://www.kernel.org )

2.

Fedora - 14 distribution, Ubuntu 11.04, Ubuntu 12.04, Ubuntu 14.04

3.

Qt version 4.7

4.

libusb-1.0.16

The software tools allow you to do the following :
1. View the device, configuration, interface, alternate-interface and endpoint descriptors of
attached devices.
2. Select a specific interface+alt interface to communicate with.
3. Program the device ( download firmware ) as follows :
a)

For the FX2 based devices -> download into RAM (Internal/External), small
EEPROM or a large EEPROM

b)

For the FX3 based devices -> download into RAM, I2C based EEPROM or SPI
based flash

4. Test your own commands ( Vendor Extensions ) after downloading a specific firmware that
implements your command(s).
5. Perform Bulk/Isochronous data transfers from/to OUT and IN endpoints on the USB
devices.

3

Chapter - 2 : Installing the software
The software CyUSB Suite for Linux is available as a compressed tarball as follows :
cyusb_linux_1.0.5.tar.gz; where the 1.0.5 refers to the version number of the software
Copy the tar file to any of the local folder and extract it as shown below
[user@desktop /home/Cypress]$ tar zxvf cyusb_linux_1.0.5.tar
Once the archive is extracted, the following directory structure is created:
The bin directory contains the main executable program called cyusb_linux.
The configs directory contains 3 configuration files as under :
a)

cyusb.conf -> Contains VID and PID of list of Cypress devices, which are of
interest.User can add edit the file and add new VID - PID pairs to the list.

b)

88-cyusb.rules-> Udev rules written for Cypress devices.

c)

cy_renumerate.sh-> Udev script that runs whenever a Cypress device is connected
to or removed from the Host machine. This script is the means for CyUSB based
software tools to handle hotplug of devices of interest.

The docs subdirectory contains the documentation in PDF format (requires Acrobat Reader
or equivalent).
The fx2_images subdirectory contain some standard firmware images for the FX2LP devkit
The fx3_images subdirectory contains some standard frmware images for the FX3 devkit
The gui_src subdirectory contains the source code for the CyUSB library and the
CyUSB_Linux GUI.
The include subdirectory contains the header files controlcenter.h and cyusb.h
The lib subdirectory contains the library file libcyusb.so. This would need to be accessible
for the main program to work.
The src folder contains a set of example programs that make use of the cyusb APIs to
perform various types of USB data transfers.
The test_cases directory contains a simple program to generate test case data.
Firmware Download and Initialization
The Cypress EZ-USB FX2 and FX3 devices work on the principle of Re-Enumeration. i.e after a
new firmware image is downloaded, the device would Re-Enumerate as a new device. We would
need to detach the earlier device and attach to this new device, which is done automatically through
the interaction of a custom udev script called 88-cyusb_rules, and a custom shell script called
renumerate.sh.
The 88-cyusb_rules specify that the renumerate.sh script needs to be invoked by the udev layer
whenever a device matching the rules in this file, is plugged in or disconnected from the host PC.
The file cy_renumerate.sh is a simple shell script that executes whenever a USB device of interest
is added or removed from a host computer. This script is responsible for notifying the cyusb_linux
application that a Cypress USB device has been connected or disconnected from the PC.

4

The Figure below gives the graphical representation of entire cyusb_linux:

/etc/cyusb.conf
This file lists the devices
of interest to the application

The renumerate.sh script sends a
SIGUSR1 to the application
whenever a new device of interest
has been added or removed.

/etc/udev/rules.d/88-cyusb.rules
This file contains the udev rules that
are executed whenever a device of interest
is connected or removed.

cy_renumerate.sh
The Script that is used to signal the
application that a new device has been
added or removed.

cyusb_linux
The Application gets a notification/signal
whenever a device of interest is connected
or removed.

• Building and installing the software
Refer to the README file for pre-requisites required for the installation and functioning of
this software. Ensure that all of the pre-requisite software modules are installed before
starting to compile and install the CyUSB Suite.
Once the files are extracted in the local directory, Open the terminal and point to the
directory where files were extracted. Type the following commands to build and install the
executable.
For example: If the files were in /home/Cypress:
[user@desktop /home/Cypress]$ make
[user@desktop /home/Cypress]# ./install.sh (Requires super-user privileges to copy the
configuration files into system folders like /etc and /usr/bin)
This will install the cyusb_linux application, which can then be launched from the terminal.
This application can be executed in normal user mode without super-user (root) privileges.
This script also sets an environment variable called CYUSB_ROOT to point to the path
where the files are located.

5

Chapter - 3 : Using the application
Open a terminal and launch the application by typing “cyusb_linux”.
E.g. :[user@desktop /home]$ cyusb_linux.
**Make sure to run the application as normal user.
Refer to Figure below for description.
Device selection area
Click on a device to select it

Summary
information

Detailed information
about descriptors

On selecting a device, detailed information is displayed about all its descriptors in the display area
as shown in the following diagram :

6

Programming the device :
On clicking the Program tab, we get the following screen :

7

You can select to download a firmware image to either RAM, or an I2C EEPROM or an SPI flash
on the target, but REMEMBER to make the necessary jumper adjustments !! (Read the h/w manual
)
If you click on the Select File button, you get a standard file dialog box which allows you to
navigate and select a firmware image to download.
Also, since this application can be used for both FX2 as well as FX3 devices, the application grays
out the tab accordingly, i.e if an FX3 device has been selected for programming, the FX2 tab is
grayed out and vice-versa.
Once a file image has been selected for download, clicking the Start Download button actually
downloads the file into the target. Typically, the device would now Re-Enumerate as a new device
and appear again with a new device address in the device list window shown earlier.

8
Going back to the Descriptors tab will show the details of the device, both in the detailed window
as well as the sumary window.

The device may now present itself with multiple interfaces with different capabilities, and it is now
very important to actually select the appropriate alternate interface for further interaction, such as
for data transfers (bulk/isoc) etc. This can be done using the Set Alt. IF button as under :

9
Using the Vendor Extensions tab :
This tab allows you to send custom control requests to the device.
For convenience, many standard options for the FX2 are already integrated into the display such as
RAM (External) Download, RAM(External) Upload, EEPROM Download, EEPROM Upload, Get
Chip Revision, and Renumerate.
The Custom option can be used to send any arbitrary command after setting appropriate values in
the Control Setup packet fields such as bmRequestType, bRequest, wValue, wIndex, and wLength.
In case the custom command also has an OUT data phase, the data can be input using the Data-Out
HEX or Data-Out ASCII fields.
If the command has an IN data phase, the data and the command status are displayed in the DATA /
Status text box.

The Select button can be used to download a specific firmware image to test out a vendor command
and the Execute Command button is used to actually execute the vendor command.

10
Performing BULK IN/OUT transfers :
After selecting a device and an appropriate interface+alt interface that supports Bulk transactions,
when the Data Transfers tab is selected and Bulk Tab selected inside that tab, you will find that the
appropriate Endpoints for OUT/IN are automatically available in the drop down combo boxes.
To send data out, we can use one of the following :
1.
2.
3.
4.
5.

A constant data pattern, example 512 bytes of the character 'A', or
A random data pattern, using a random number generator program of the glibc library, or
An incrementing data pattern, with the start number being specified in the Value field, or
Select a file using the Out-File button and choosing any file from the system, or
Send selected values typed in through a text box in ASCII or HEX format.

To receive data from the device, we just set the data size to a multiple of the maximum packet size
for the endpoint, and click the receive button. The actual data may be less than what we specified
and this is reflected in the Data In transfer statistics fields.
Both data out and data in are shown in their respective windows.
In case the device has an appropriate loopback firmware image loaded, we can also click the
loopback checkbox to automatically loopback the data after a write, i.e a SEND would
automatically result in a RECEIVE.
For an example of a bulk out with a loopback and using a constant data of '0xA5' and sending 64
bytes, see picture below :

Note: For this example, we have downloaded cyfxbulklpautoenum.img image file, which loops
back any data it receives on Bulk-IN to Bulk-OUT to the EZ-USB FX3 device.

11
As another example, using the same image, but now using a 64-byte randomly generated data with
loopback, see image below :

As yet another example, using the same firmware image, but we now use an incrementing data
pattern, with a start value of 0x01 and we send 32 bytes only :

We can also use the out-file button to select a file from the computer to transmit and we can use the
in-file button to capture the data sent out into a new file. We can use command line tools to do a diff
to ensure that the data sent out is in fact correctly received without any data transmission errors.

12
You can also use the program in the test_cases directory to generate large amounts of data to store
in a file and then send/receive and do further testing.
As a final example, we can enter random data directly in the Data-Out ASCII field or Data-Out
HEX field and the system automatically calculates the length. If loopback is selected, we can see
the data transferred out and back in :

In the event of an endpoint Halt or Stall condition, we can clear the endpoint by issuing an explicit
Clear Halt command by clicking the respective buttons under the Endpoint OUT and Endpoint IN
drop down boxes.
Performing Isochronous Transfers :
After selecting a device and an appropriate interface+alt interface that supports Isoc transactions,
when the Data Transfers tab is selected and Isochronous Tab selected inside that tab, you will find
that the appropriate Endpoints for OUT/IN are automatically available in the drop down combo
boxes.
The drop-down box for Num Pkts allows you to select the number of packets you wish to send or
receive from the device. In the example shown below, we have used the cyfxisosrcsink.img which
discards all data written to the OUT endpoint and generates a constant data pattern thru the IN
endpoint.

13

In the example below we have selected 128 packets. The Max Packet Size field in the Transfer
Statistics panel shows the data automatically retrieved from the device's descriptors, which in this
case happens to be 1024 bytes. This means we are about to transfer 128 KB of data.

14
Generally, for large isochronous transfers, we recommend that the Display Dump be disabled since
it serves no purpose and also the objective is to estimate the speed of transfer and display would
vitiate the timings.
In the example above, we can see that 128 KB of data has been sent and 128 KB of data has been
received (by clicking SEND and RECEIVE separately), and the data transfer rate is about 4.923
MB per sec and 5.120 MB per second respectively.
Measuring Transfer Performance:
The Streamer tab under Data Transfers can be used to perform continuous data transfers and
measure the transfer performance. Since only one endpoint is selected for testing, the USB device
implementation used should be capable of endlessly sending or receiving data on the selected
endpoint.
For example, the cyfxbulksrcsink.img or cyfxisosrcsink.img files can be used to measure the data
rates of bulk and isochronous transfers when using the FX3 device.
On selecting the streamer tab, you can see the following screen:

The drop down list next to Endpoint will list all of the bulk, interrupt and isochronous endpoints
that are part of the active interface and alternate setting. The size listed is the product of the
maximum packet size and the burst length for the endpoint. For isochronous endpoints, the number
of bursts per frame (MULT) value is also considered when calculating the endpoint size.
The streamer application measures data rate by maintaining a queue of asynchronous data transfer
requests. The Queue Depth setting specifies the number of elements in the queue, and the Transfer
Size specifies the size of each request in terms of the endpoint size.
Once the parameters have been selected, hit the Start button. The number of Passing/Failing
transfers and the measured performance are continously reflected in the output boxes on the right
side of the screen. The following picture shows the output when measuring bulk transfer rate using
the cyfxbulksrcsink firmware example:

15

The following picture shows the output obtained when measuring isochronous transfer rate using
the cyfxisosrcsink firmware example:

Hit the Stop button to stop transfers and return to any other activity. The application will take a few
seconds to stop the transfers and respond to further user input.

16

Chapter - 4 : Known Issues and Solutions
1. The cyusb library and application can only support 10 devices at a time. Please recompile
the library and application after modifying the MAXDEVICES definition in cyusb.h, if a
greater number devices is to be supported.
2. The cyusb library only looks at the first 100 VID/PID pair entries from the cyusb.conf file
for driver binding. Please recompile the library and application after modifying the
MAX_ID_PAIRS definition in cyusb.h, if this limit is to be changed.



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 18
Language                        : en-IN
Author                          : viny
Creator                         : Writer
Producer                        : OpenOffice.org 3.3
Create Date                     : 2017:12:18 13:03:22+05:30

EXIF Metadata provided by EXIF.tools