Component - USBFS V2.30

®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
2.30
Features
 USB Full Speed device interface driver
 Support for interrupt, control, bulk, and isochronous transfer types
 Run-time support for descriptor set selection
 Optional USB string descriptors
 Optional USB HID class support
 Optional Bootloader support
 Optional Audio class support (See the USBFS Audio section)
 Optional MIDI devices support (See the USBFS MIDI section)
 Optional CDC class support (See the USBUART section)
General Description
The USBFS component provides a USB full-speed Chapter 9 compliant device framework. It
provides a low-level driver for the control endpoint that decodes and dispatches requests from
the USB host. Additionally, this component provides a USBFS customizer to make it easy to
construct your descriptor.
You have the option of constructing a HID-based device or a generic USB Device. Select HID
(and switch between HID and generic) by setting the Configuration/Interface descriptors.
Refer to the USB-IF device class documentation for additional information on descriptors
(http://www.usb.org/developers/devclass/).
Note Cypress offers a set of USB development tools, called SuiteUSB, available free of charge
when used with Cypress silicon. You can obtain SuiteUSB from the Cypress website:
http://www.cypress.com.
When to Use a USBFS
Use the USBFS component when you want to provide your application with a USB 2.0 compliant
device interface.
Cypress Semiconductor Corporation • 198 Champion Court • San Jose, CA 95134-1709 • 408-943-2600
Document Number: 001-81341 Rev. **
Revised June 14, 2012
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Quick Start
1. Drag a USBFS component from the Component Catalog onto your design.
2. Notice the clock errors in the Notice List window; double-click on an error to open the System
Clock Editor.
3. Configure the following clocks:
a) For PSoC 3 or PSoC 5 LP:
i) ILO: Select 100 kHz.
ii) IMO: Select Osc 24.000 MHz.
iii) USB: Enable and select IMOx2 – 48.000 MHz.
b) For PSoC 5:
i) ILO: Select 100 kHz.
ii) XTAL: Enable and configure Freq: 24 MHz. Make sure the external 24-MHz crystal is
installed on the DVK.
iii) IMO: Select XTAL.
iv) USB: Enable and select IMOx2 – 48.000 MHz.
v) PLL: Enable and configure Desired: 33 MHz (or greater).
vi) Master Clock: Select to “PLL_OUT”
4. Select Build to generate APIs.
Input/Output Connections
This section describes the input and output connections for the USBFS. An asterisk (*) in the list
of I/Os indicates that the I/O may be hidden on the symbol under the conditions listed in the
description of that I/O.
sof – Output *
The start-of-frame (sof) output allows endpoints to identify the start of the frame and synchronize
internal endpoint clocks to the host. This output is visible if the Enable SOF Output parameter in
the Advanced tab of the customizer is selected.
Page 2 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Component Parameters
Drag a USBFS component onto your design and double-click it to open the Configure USBFS
dialog.
The component is driven by information generated by the USBFS Configure dialog. This dialog,
or “customizer,” facilitates the construction of the USB descriptors and integrates the information
generated into the driver firmware used for device enumeration.
The USBFS component does not function without first running the wizard and selecting the
appropriate attributes to describe your device. The code generator takes your device information
and generates all of the needed USB descriptors.
The Configure USBFS dialog contains the following tabs and settings:
Device Descriptor Tab
Descriptor Root
Document Number: 001-81341 Rev. **
Page 3 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Endpoint Memory Management
The USBFS block contains 512 bytes of target memory for the data endpoints to use. However,
the architecture supports a cut-through mode of operation (DMA w/Automatic Memory
Management) that reduces the memory requirement based on system performance.
Some applications can benefit from using Direct Memory Access (DMA) to move data into and
out of the endpoint memory buffers.

Manual (default) – Select this option to use LoadInEP/ReadOutEP to load and unload the
endpoint buffers.
 Static Allocation – The memory for the endpoints is allocated immediately after a
SET_CONFIGURATION request. This takes longest when multiple alternate settings
use the same endpoint (EP) number.
 Dynamic Allocation – The memory for the endpoints is allocated dynamically after
each SET_CONFIGURATION and SET_INTERFACE request. This option is useful
when multiple alternate settings are used with mutually exclusive EP settings.


DMA w/Manual Memory Management – Select this option for manual DMA transactions.
The LoadInEP/ReadOutEP functions fully support this mode and initialize the DMA
automatically. This option is not supported for PSoC 5 silicon.
DMA w/Automatic Memory Management – Select this option for automatic DMA
transactions. This is the only configuration that supports combined data endpoint use of more
than 512 bytes. Use the LoadInEP/ReadOutEP functions for initial DMA configuration. This
option is not supported for PSoC 5 silicon.
PSoC does not support DMA transactions directly between USB endpoints and other
peripherals. All DMA transactions involving USB endpoints (in and out) must terminate or
originate with main system memory.
Applications requiring DMA transactions directly between USB endpoints and other peripherals
must use two DMA transactions. The two transactions move data to main system memory as an
intermediate step between the USB endpoint and the other peripheral.
Page 4 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Device Descriptor
Device Attributes

Vendor ID – Your company USB vendor ID (obtained from USB-IF)
Note Vendor ID 0x4B4 is a Cypress-only VID and may be used for development purposes
only. Products cannot be released using this VID; you must obtain your own VID.







Product ID – Your specific product ID
Device Release – Your specific device release (device ID)
Device Class – Device class is defined in Interface Descriptor, CDC, or Vendor-Specific
Device Subclass – Dependent upon Device Class
Manufacturing String – Manufacturer-specific description string to be displayed when the
device is attached.
Product String – Product-specific description string to be displayed when the device is
attached.
Serial String
Document Number: 001-81341 Rev. **
Page 5 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Configuration Descriptor
Configuration Attributes


Configuration string
Max Power (mA) – Enter the maximum power consumption of the USB device from the bus
when the device is fully operational, in this specific configuration.
Note The Device Power parameter reports whether the configuration is bus powered or self
powered. Device status reports whether the device is currently self powered. If a device is
disconnected from its external power source, it updates device status to indicate that it is no
longer self powered. A device cannot increase its power draw from the bus, when it loses its
external power source, beyond the amount reported by its configuration.


Device Power – Bus Powered or Self Powered device. The USBFS does not support both
settings simultaneously.
Remote Wakeup – Enabled or Disabled
Page 6 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Interface Descriptor
This level is used to add and delete Interface Alternate Settings. The interfaces are configured in
the Alternate Setting.
Alternate Setting 0 is automatically provided to configure your device. If your device uses
isochronous endpoints, note that the USB 2.0 specification requires that no device default
interface settings can include any isochronous endpoints with nonzero data payload sizes. This
is specified using Max Packet Size in the Endpoint Descriptor.
For isochronous devices, use an alternate interface setting other than the default Alternate
Setting 0 to specify nonzero data payload sizes for isochronous endpoints. Additionally, if your
isochronous endpoints have a large data payload, you should use additional alternate
configurations or interface settings to specify a range of data payload sizes. This increases the
chance that the device can be used successfully in combination with other USB devices.
Document Number: 001-81341 Rev. **
Page 7 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Interface Descriptor—Alternate Settings
Interface Attributes





Interface String
Interface Number – Computed by the customizer.
Alternate Settings – Computed by the customizer.
Class – HID, Vendor Specific, or Undefined
Subclass – Dependent on the selected class
Note String descriptors are optional. If a device does not support string descriptors, all
references to string descriptors within the device, configuration, and interface descriptors must
be set to zero.
HID Class Descriptor
The HID Class Descriptor item does not display by default. It is used to add a HID Report to the
Alternate Setting.
Page 8 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
To Add HID Class Descriptor
1. Select an Alternate Setting item in the Descriptor Root tree.
2. Under Interface Attributes on the right, select HID for the Class field.
Device Attributes



Descriptor Type – Constant name identifying type of class descriptor
Country Code – Numeric expression identifying country code of the localized hardware
HID Report – List of available report descriptors. Report descriptors are taken from the HID
Descriptor tab. This field is required.
Document Number: 001-81341 Rev. **
Page 9 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Endpoint Descriptor
Endpoint Attributes





Endpoint Number
Direction – Input or Output. USB transfers are host centric; therefore, IN refers to transfers to
the host; OUT refers to transfers from the host.
Transfer Type – Control (CONT), Interrupt (INT), Bulk (BULK), or Isochronous Data (ISOC)
transfers
Interval (ms) – Polling interval specific to this endpoint. A full-speed endpoint can specify a
period from 1 ms to 255 ms.
Max Packet Size (bytes) – For a full-speed device the Max Packet Size is 64 bytes for bulk
or interrupt endpoints and 512 (1023 for Automatic DMA mode) bytes for isochronous
endpoints.
The maximum packet size for the isochronous endpoints is limited by the local memory size
in the Manual Memory Management mode of operation, while the DMA w/Automatic Memory
Management mode of operation has no such limitation. This is because the local memory is
treated as a temporary buffer.
Page 10 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Import and Save Tool Buttons
The Save button allows you to save information about the component configuration into an XML
configuration file. In the drop-down list you can choose either Save Current Descriptor or Save
Root Descriptor. The first option saves the configuration of the selected descriptor. The second
option saves the whole device descriptor tree.
The Import button allows you to import the descriptor configuration. In the drop-down list you
can choose either Import Current Descriptor or Import Root Descriptor. The first option loads
the configuration of the selected descriptor. The second option loads the tree of descriptors. In
this case, previously configured descriptors are not removed.
Note The same Import and Save tool buttons are present on the other descriptors tabs: HID
Descriptor, Audio Descriptor, and CDC Descriptor. They are used to save and import
descriptor configurations that are configured on those tabs.
String Descriptor Tab
String Descriptors


LANGID – Language ID selection
String – Value of string descriptor
Document Number: 001-81341 Rev. **
Page 11 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Serial Number String




Value – Default string
User Entered Text – Enables the Value text box
User Call Back – The USBFS_SerialNumString() function sets the pointer to use the usergenerated serial number string descriptor. The application firmware may supply the source of
the USB device descriptor’s serial number string during run time.
Silicon Generated Serial Number – This number is applied to non-volatile memory in the
device at manufacturing time. It is not guaranteed to be unique.
Page 12 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
MS OS String Descriptor
Microsoft OS Descriptors provide a way for USB devices to supply additional configuration
information to the latest Microsoft operating systems.

Value – Constant string MSFT100
Document Number: 001-81341 Rev. **
Page 13 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
HID Descriptor Tab
The HID Descriptor tab allows you to quickly build HID descriptors for your device. Use the
Add Report button to add and configure HID Report Descriptors.
HID Descriptors


HID Items List – Items to add in the HID report
Item Value – Value of the item that is selected either in HID Items List or in the tree
Audio Descriptor Tab
The Audio Descriptor tab is used to add and configure audio interface descriptors.
See the Audio Descriptor Tab section in USBFS Audio for more information.
MIDI Descriptor Tab
The MIDI Descriptor tab is used to add and configure MIDI Streaming interface descriptors.
See the MIDI Descriptor Tab section in USBFS MIDI MIDI for more information.
Page 14 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
CDC Descriptor Tab
The CDC Descriptor tab is used to add and configure communications and data interface
descriptors.
See the CDC Descriptor Tab section in USBUART for more information.
Advanced Tab
External Class
This parameter allows for the user firmware, or other components at the solutions level, to
manage the class requests. The USBFS_DispatchClassRqst() function should be implemented if
this parameter is enabled.
External Vendor
This parameter allows for the user firmware, or other components at the solutions level, to
manage the vendor-specific requests. The USBFS_HandleVendorRqst() function should be
implemented if this parameter is enabled.
Document Number: 001-81341 Rev. **
Page 15 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Enable VBUS Monitoring
The USB specification requires that no device supplies current on VBUS at its upstream facing
port at any time. To meet this requirement, the device must monitor for the presence or absence
of VBUS and remove power from the D+/D– pull-up resistor if VBUS is absent.
For bus-powered designs, power will obviously be removed when the USB cable is removed
from a host; however, for self-powered designs it is imperative for proper operation and USB
certification that your device complies with this requirement.
This parameter adds a single VBUS monitor pin to the design. By default, the drive mode of this
pin is configured to High Impedance Digital, and could be set to a different mode by using the
pin-specific API USBFS_VBUS_SetDriveMode(). This pin must be connected to the VBUS
through the resistive network and must be assigned in the Pin Editor. The
USBFS_VBusPresent() function returns the status of the VBUS. See the USB Compliance for
Self-Powered Devices section for additional information.
Enable SOF Output
This parameter enables the Start-of-Frame output.
Clock Settings
The USB hardware block requires that system clocks be configured through the PSoC Creator
Design-Wide Resources Clock Editor. Clock settings have the following requirements when
using the USBFS component:




The USB Clock must be enabled.
The ILO must be set to 100 kHz.
If the selected device is PSoC 5, the Bus Clock cannot be slower than 33 MHz [for Master
Clock, select “PLL_OUT (33.000 MHz)”].
If the selected device is PSoC 5, the IMO must be sourced from the external 24-MHz XTAL.
There are different ways to configure the system clocks to comply with these requirements.
Figure 1 and Figure 2 show the set of options you may use. Your design may require different
settings.
Page 16 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Figure 1. System Clock Configuration for PSoC 3
Document Number: 001-81341 Rev. **
Page 17 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
Figure 2. System Clock Configuration for PSoC 5
Application Programming Interface
Application Programming Interface (API) routines allow you to configure the component using
software. The following table lists and describes the interface to each function. The subsequent
sections discuss each function in more detail.
By default, PSoC Creator assigns the instance name “USBFS_1” to the first instance of a
component in a given design. You can rename it to any unique value that follows the syntactic
rules for identifiers. The instance name becomes the prefix of every global function name,
variable, and constant symbol. For readability, the instance name used in the following table is
“USBFS.”
Basic USBFS Device APIs
Function
Description
USBFS_Start()
Activates the component for use with the device and specific voltage mode.
USBFS_Init()
Initializes the component’s hardware.
Page 18 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Function
Description
USBFS_InitComponent()
Initializes the component’s global variables and initiates communication with
host by pull-up D+ line.
USBFS_Stop()
Disables the component.
USBFS_GetConfiguration()
Returns the currently assigned configuration. Returns 0 if the device is not
configured.
USBFS_IsConfigurationChanged()
Returns the clear-on-read configuration state.
USBFS_GetInterfaceSetting()
Returns the current alternate setting for the specified interface.
USBFS_GetEPState()
Returns the current state of the specified USBFS endpoint.
USBFS_GetEPAckState()
Determines whether an ACK transaction occurred on this endpoint.
USBFS_GetEPCount()
Returns the current byte count from the specified USBFS endpoint.
USBFS_InitEP_DMA()
Initializes DMA for EP data transfers.
USBFS_LoadInEP()
Loads and enables the specified USBFS endpoint for an IN transfer.
USBFS_ReadOutEP()
Reads the specified number of bytes from the Endpoint RAM and places it in
the RAM array pointed to by pSrc. Returns the number of bytes sent by the
host.
USBFS_EnableOutEP()
Enables the specified USB endpoint to accept OUT transfers.
USBFS_DisableOutEP()
Disables the specified USB endpoint to NAK OUT transfers.
USBFS_SetPowerStatus()
Sets the device to self powered or bus powered.
USBFS_Force()
Forces a J, K, or SE0 State on the USB D+/D– pins. Normally used for
remote wakeup.
USBFS_SerialNumString()
Provides the source of the USB device serial number string descriptor during
run time.
USBFS_TerminateEP()
Terminates endpoint transfers.
USBFS_VBusPresent()
Determines VBUS presence for self-powered devices.
Global Variables
Variable
USBFS_initVar
Description
Indicates whether the USBFS has been initialized. The variable is initialized to 0
and set to 1 the first time USBFS_Start() is called. This allows the component to
restart without reinitialization after the first call to the USBFS_Start() routine.
If reinitialization of the component is required, the variable should be set to 0
before the USBFS_Start() routine is called. Alternatively, the USBFS can be
reinitialized by calling the USBFS_Init() and USBFS_InitComponent() functions.
USBFS_device
Contains the started device number. This variable is set by the USBFS_Start() or
USBFS_InitComponent() APIs.
Document Number: 001-81341 Rev. **
Page 19 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
Variable
Description
USBFS_transferState
This variable is used by the communication functions to handle the current
transfer state.
Initialized to TRANS_STATE_IDLE in the USBFS_InitComponent() API and after
a complete transfer in the status stage.
Changed to the TRANS_STATE_CONTROL_READ or
TRANS_STATE_CONTROL_WRITE in setup transaction depending on the
request type.
USBFS_configuration
Contains the current configuration number, which is set by the host using a
SET_CONFIGURATION request. This variable is initialized to zero in
USBFS_InitComponent() API and returned to the application level by the
USBFS_GetConfiguration() API._
USBFS_configurationChanged
This variable is set to one after SET_CONFIGURATION and SET_INTERFACE
requests. It is returned to the application level by the
USBFS_IsConfigurationChanged() API.
USBFS_deviceAddress
Contains the current device address. This variable is initialized to zero in the
USBFS_InitComponent() API. The host starts to communicate to the device with
address 0 and then sets it to the value in the SET_ADDRESS request.
USBFS_deviceStatus
This is a two-bit variable that contains power status in the first bit
(DEVICE_STATUS_BUS_POWERED or DEVICE_STATUS_SELF_POWERED)
and remote wakeup status (DEVICE_STATUS_REMOTE_WAKEUP) in the
second bit. This variable is initialized to zero in USBFS_InitComponent() API,
configured by the USBFS_SetPowerStatus() API.
void USBFS_Start(uint8 device, uint8 mode)
Description:
This function performs all required initialization for the USBFS component.
Parameters:
uint8 device: Contains the device number from the appropriate device-descriptor set entered
with the USBFS customizer.
uint8 mode: Operating voltage. This determines whether the voltage regulator is enabled for
5-V operation or if pass-through mode is used for 3.3-V operation. Symbolic names and their
associated values are given in the following table.
Power Setting
Notes
USBFS_3V_OPERATION
Disable the voltage regulator and pass-through VCC
for pull-up
USBFS_5V_OPERATION
Enable the voltage regulator and use the regulator
for pull-up
USBFS_DWR_VDDD_OPERATION Enable or disable the voltage regulator depending
on VDDD voltage configuration in DWR
Return Value: None
Side Effects:
Page 20 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
void USBFS_Init(void)
Description:
This function initializes or restores the component according to the customizer Configure
dialog settings. It is not necessary to call USBFS_Init() because the USBFS_Start() routine
calls this function and is the preferred method to begin component operation.
Parameters:
None
Return Value: None
Side Effects:
None
void USBFS_InitComponent(uint8 device, uint8 mode)
Description:
This function initializes the component’s global variables and initiates communication with the
host by pull-up D+ line.
Parameters:
uint8 device: Contains the device number from the appropriate device-descriptor set entered
with the USBFS customizer.
uint8 mode: Operating voltage. This determines whether the voltage regulator is enabled for
5-V operation or if pass-through mode is used for 3.3-V operation. Symbolic names and their
associated values are given in the following table.
Power Setting
Notes
USBFS_3V_OPERATION
Disable the voltage regulator and pass-through VCC
for pull-up
USBFS_5V_OPERATION
Enable the voltage regulator and use the regulator
for pull-up
USBFS_DWR_VDDD_OPERATION Enable or disable the voltage regulator depending
on VDDD voltage configuration in DWR
Return Value: None
Side Effects:
None
void USBFS_Stop(void)
Description:
This function performs all necessary shutdown tasks required for the USBFS component.
Parameters:
None
Return Value: None
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 21 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
uint8 USBFS_GetConfiguration(void)
Description:
This function gets the current configuration of the USB device.
Parameters:
None
Return Value: uint8: Returns the currently assigned configuration. Returns 0 if the device is not configured.
Side Effects:
None
uint8 USBFS_IsConfigurationChanged(void)
Description:
This function returns the clear-on-read configuration state. It is useful when the PC sends
double SET_CONFIGURATION requests with the same configuration number.
Parameters:
None
Return Value: uint8: Returns a nonzero value when a new configuration has been changed; otherwise, it
returns zero.
Side Effects:
None
uint8 USBFS_GetInterfaceSetting(uint8 interfaceNumber)
Description:
This function gets the current alternate setting for the specified interface.
Parameters:
uint8 interfaceNumber: Interface number
Return Value: uint8: Returns the current alternate setting for the specified interface.
Side Effects:
Page 22 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
uint8 USBFS_GetEPState(uint8 epNumber)
Description:
This function returns the state of the requested endpoint.
Parameters:
uint8 epNumber: Data endpoint number
Return
Value:
uint8: Returns the current state of the specified USBFS endpoint. Symbolic names and their
associated values are given in the following table. Use these constants whenever you write
code to change the state of the endpoints, such as ISR code, to handle data sent or received.
Return Value
Description
USBFS_NO_EVENT_PENDING
The endpoint is awaiting SIE action
USBFS_EVENT_PENDING
The endpoint is awaiting CPU action
USBFS_NO_EVENT_ALLOWED The endpoint is locked from access
USBFS_IN_BUFFER_FULL
The IN endpoint is loaded and the mode is set to ACK IN
USBFS_IN_BUFFER_EMPTY
An IN transaction occurred and more data can be loaded
USBFS_OUT_BUFFER_EMPTY The OUT endpoint is set to ACK OUT and is waiting for
data
USBFS_OUT_BUFFER_FULL
Side Effects:
An OUT transaction has occurred and data can be read
None
uint8 USBFS_GetEPAckState(uint8 epNumber)
Description:
This function determines whether an ACK transaction occurred on this endpoint by reading
the ACK bit in the control register of the endpoint. It does not clear the ACK bit.
Parameters:
uint8 epNumber: Contains the data endpoint number.
Return Value: uint8: If an ACKed transaction occurred, this function returns a nonzero value. Otherwise, it
returns zero.
Side Effects:
None
uint16 USBFS_GetEPCount(uint8 epNumber)
Description:
This function returns the transfer count for the requested endpoint. The value from the count
registers includes two counts for the two-byte checksum of the packet. This function
subtracts the two counts.
Parameters:
uint8 epNumber: Contains the data endpoint number.
Return Value: uint16: Returns the current byte count from the specified USBFS endpoint or 0 for an invalid
endpoint.
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 23 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
void USBFS_InitEP_DMA(uint8 epNumber, uint8 *pData)
Description:
This function allocates and initializes a DMA channel to be used by the USBFS_LoadInEP()
or USBFS_ReadOutEP() APIs for data transfer. It is available when the Endpoint Memory
Management parameter is set to DMA.
This function is automatically called from the USBFS_LoadInEP() and USBFS_ReadOutEP()
APIs.
Parameters:
uint8 epNumber: Contains the data endpoint number.
uint8 *pData: Pointer to a data array that is related to the EP transfers.
Return Value: None
Side Effects:
None
void USBFS_LoadInEP(uint8 epNumber, uint8 *pData, uint16 length)
Description:
Manual mode: This function loads and enables the specified USB data endpoint for an IN
data transfer.
Manual DMA:

Configures DMA for a data transfer from data RAM to endpoint RAM.

Generates request for a transfer.
Automatic DMA:
Parameters:

Configures DMA. This is required only once, so it is done only when parameter pData is
not NULL. When the pData pointer is NULL, the function skips this task.

Sets Data ready status: This generates the first DMA transfer and prepares data in
endpoint RAM memory.
uint8 epNumber: Contains the data endpoint number.
uint8 *pData: Pointer to a data array from which the data for the endpoint space is loaded.
uint16 length: The number of bytes to transfer from the array and then send as a result of an
IN request. Valid values are between 0 and 512 (1023 for Automatic DMA mode).
Return Value: None
Side Effects:
Page 24 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
uint16 USBFS_ReadOutEP(uint8 epNumber, uint8 *pData, uint16 length)
Description:
Manual mode: This function moves the specified number of bytes from endpoint RAM to data
RAM. The number of bytes actually transferred from endpoint RAM to data RAM is the lesser
of the actual number of bytes sent by the host or the number of bytes requested by the
wCount parameter.
Manual DMA:

Configure DMA for a transfer data from endpoint RAM to data RAM.

Generate request for a transfer.

After the USB_ReadOutEP() API and before the expected data use it must wait for the
DMA transfer to complete. For example, by checking EPstate:
while (USBFS_GetEPState(OUT_EP) == USB_OUT_BUFFER_FULL);
Automatic DMA:

Parameters:
Configure DMA. This is required only once.
uint8 epNumber: Contains the data endpoint number.
uint8 *pData: Pointer to a data array to which the data from the endpoint space is loaded.
uint16 length: The number of bytes to transfer from the USB OUT endpoint and load into
data array. Valid values are between 0 and 512 (1023 for Automatic DMA mode). The
function moves fewer than the requested number of bytes if the host sends fewer bytes than
requested.
Return Value: uint16: Number of bytes received
Side Effects:
None
void USBFS_EnableOutEP(uint8 epNumber)
Description:
This function enables the specified endpoint for OUT transfers. Do not call this function for IN
endpoints.
Parameters:
uint8 epNumber: Contains the data endpoint number.
Return Value: None
Side Effects:
None
void USBFS_DisableOutEP(uint8 epNumber)
Description:
This function disables the specified USBFS OUT endpoint. Do not call this function for IN
endpoints.
Parameters:
uint8 epNumber: Contains the data endpoint number.
Return Value: None
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 25 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
void USBFS_SetPowerStatus(uint8 powerStatus)
Description:
This function sets the current power status. The device replies to USB GET_STATUS
requests based on this value. This allows the device to properly report its status for USB
Chapter 9 compliance. Devices can change their power source from self powered to bus
powered at any time and report their current power source as part of the device status. You
should call this function any time your device changes from self powered to bus powered or
vice versa, and set the status appropriately.
Parameters:
uint8 powerStatus: Contains the desired power status, one for self powered or zero for bus
powered. Symbolic names and their associated values are given here:
Power Status
USBFS_DEVICE_STATUS_BUS_POWERED
Description
Set the device to bus powered
USBFS_DEVICE_STATUS_SELF_POWERED Set the device to self powered
Return Value: None
Side Effects:
None
void USBFS_Force(uint8 state)
Description:
This function forces a USB J, K, or SE0 state on the D+/D– lines. It provides the necessary
mechanism for a USB device application to perform a USB Remote Wakeup. For more
information, see the USB 2.0 Specification for details on Suspend and Resume.
Parameters:
uint8 state: A byte indicating which of the four bus states to enable. Symbolic names and
their associated values are listed here:
State
Description
USBFS_FORCE_SE0
Force a Single Ended 0 onto the D+/D– lines
USBFS_FORCE_J
Force a J State onto the D+/D– lines
USBFS_FORCE_K
Force a K State onto the D+/D– lines
USBFS_FORCE_NONE
Return bus to SIE control
Return Value: None
Side Effects:
Page 26 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
void USBFS_SerialNumString(uint8 *snString)
Description:
This function is available only when the User Call Back option in the Serial Number String
descriptor properties is selected. Application firmware can provide the source of the USB
device serial number string descriptor during run time. The default string is used if the
application firmware does not use this function or sets the wrong string descriptor.
Parameters:
uint8 *snString: Pointer to the user-defined string descriptor. The string descriptor should
meet the Universal Serial Bus Specification revision 2.0 chapter 9.6.7
Return Value: None
Side Effects:
None
void USBFS_TerminateEP(uint8 epNumber)
Description:
This function terminates the specified USBFS endpoint. This function should be used before
endpoint reconfiguration.
Parameters:
uint8 epNumber: Contains the data endpoint number.
Return Value:
None
Side Effects:
The device responds with a NAK for any transactions on the selected endpoint.
uint8 USBFS_VBusPresent(void)
Description:
Determines VBUS presence for self-powered devices.
This function is available when the VBUS Monitoring option is enabled in the Advanced tab.
Parameters:
None
Return Value: The return value can be the following:
Return Value
Side Effects:
Description
1
VBUS is present
0
VBUS is absent
None
Human Interface Device (HID) Class Support
Function
Description
USBFS_UpdateHIDTimer()
Updates the HID Report timer for the specified interface and returns 1 if the timer
expired and 0 if not. If the timer expired, it reloads the timer.
USBFS_GetProtocol()
Returns the protocol for the specified interface
Document Number: 001-81341 Rev. **
Page 27 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
Global Variables
Variable
Description
USBFS_hidProtocol
This variable is initialized in the USBFS_InitComponent() API to the
PROTOCOL_REPORT value. It is controlled by the host using the
HID_SET_PROTOCOL request. The value is returned to the user code by the
USBFS_GetProtocol() API.
USBFS_hidIdleRate
This variable controls the HID report rate. It is controlled by the host using the
HID_SET_IDLE request and used by the USBFS_UpdateHIDTimer() API to reload
timer.
USBFS_hidIdleTimer
This variable contains the timer counter, which is decremented and reloaded by
the USBFS_UpdateHIDTimer() API.
uint8 USBFS_UpdateHIDTimer(uint8 interface)
Description:
This function updates the HID Report idle timer and returns the status and reloads the timer if
it expires.
Parameters:
uint8 interface: Contains the interface number.
Return Value: uint8: Returns the state of the HID timer. Symbolic names and their associated values are
given here:
Return Value
USBFS_IDLE_TIMER_EXPIRED
Notes
The timer expired.
USBFS_IDLE_TIMER_RUNNING The timer is running.
USBFS_IDLE_TIMER_IDEFINITE The report is sent when data or state changes.
Side Effects:
None
uint8 USBFS_GetProtocol(uint8 interface)
Description:
This function returns the HID protocol value for the selected interface.
Parameters:
uint8 interface: Contains the interface number.
Return Value: uint8: Returns the protocol value.
Side Effects:
None
Bootloader Support
The USBFS component can be used as a communication component for the Bootloader. You
should use the following configurations to support communication protocol from an external
system to the Bootloader:

Endpoint Number: EP1, Direction: OUT, Transfer Type: INT, Max Packet Size: 64
Page 28 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet

Full Speed USB (USBFS)
Endpoint Number: EP2, Direction: IN, Transfer Type: INT, Max Packet Size: 64
Full recommended configurations are stored in the template file (bootloader.root.xml). Select
Descriptor Root on the Device Descriptor tree, click the Import button, browse to the following
directory, and open the bootloader.root.xml file.
<INSTALL>\psoc\content\cycomponentlibrary\CyComponentLibrary.cylib\USBFS_v2.12\Custom\
template\
See the System Reference Guide for more information about the Bootloader.
The USBFS component provides a set of API functions for Bootloader use.
Function
Description
USBFS_CyBtldrCommStart()
Performs all required initialization for the USBFS component, waits on
enumeration, and enables communication.
USBFS_CyBtldrCommStop()
Calls the USBFS_Stop() function.
USBFS_CyBtldrCommReset()
Resets the receive and transmit communication buffers.
USBFS_CyBtldrCommWrite()
Allows the caller to write data to the bootloader host. The function handles polling
to allow a block of data to be completely sent to the host device.
USBFS_CyBtldrCommRead()
Allows the caller to read data from the bootloader host. The function handles
polling to allow a block of data to be completely received from the host device.
void USBFS_CyBtldrCommStart(void)
Description:
This function performs all required initialization for the USBFS component, waits on
enumeration, and enables communication.
Parameters:
None
Return Value: None
Side Effects:
This function starts the USBFS with 3-V operation.
void USBFS_CyBtldrCommStop(void)
Description:
This function performs all necessary shutdown tasks required for the USBFS component.
Parameters:
None
Return Value: None
Side Effects:
Calls the USBFS_Stop() function.
Document Number: 001-81341 Rev. **
Page 29 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
void USBFS_CyBtldrCommReset(void)
Description:
This function resets the receive and transmit communication buffers.
Parameters:
None
Return Value: None
Side Effects:
None
cystatus USBFS_CyBtldrCommWrite(uint8 *data, uint16 size, uint16 *count, uint8 timeOut)
Description:
This function allows the caller to write data to the bootloader host. It handles polling to allow
a block of data to be completely sent to the host device.
Parameters:
uint8 *data: Pointer to the block of data to send to the device.
uint16 size: Number of bytes to write.
uint16 *count: Pointer to an unsigned short variable to write the number of bytes actually
written.
uint8 timeout: Number of units to wait before returning because of a timeout.
Return Value: cystatus: Returns CYRET_SUCCESS if no problem was encountered or returns the value
that best describes the problem. For more information, see the “Return Codes” section of the
System Reference Guide.
Side Effects:
None
cystatus USBFS_CyBtldrCommRead(uint8 *data, uint16 size, uint16 *count, uint8 timeOut)
Description:
This function allows the caller to read data from the bootloader host. It handles polling to
allow a block of data to be completely received from the host device.
Parameters:
uint8 *data: Pointer to the area to store the block of data received from the device.
uint16 size: Number of bytes to read.
uint16 *count: Pointer to an unsigned short variable to write the number of bytes actually
read.
uint8 timeOut: Number of units to wait before returning because of a timeout.
Return Value: cystatus: Returns CYRET_SUCCESS if no problem was encountered or returns the value
that best describes the problem. For more information, see the “Return Codes” section of the
System Reference Guide.
Side Effects:
Page 30 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
USB Suspend, Resume, and Remote Wakeup
The USBFS component supports USB Suspend, Resume, and Remote Wakeup. Because these
features are tightly coupled into the user application, the USBFS component provides a set of
API functions.
Function
Description
USBFS_CheckActivity()
Checks and clears the USB bus activity flag. Returns 1 if the USB was active
since the last check, otherwise returns 0.
USBFS_Suspend()
Disables the USBFS block and prepares for power down mode.
USBFS_Resume()
Enables the USBFS block after power down mode.
USBFS_RWUEnabled()
Returns current remote wakeup status.
uint8 USBFS_CheckActivity(void)
Description:
This function returns the activity status of the bus and clears the status hardware to provide
fresh activity status on the next call of this routine.
This function provides a means to determine whether any USB bus activity occurred. The
application uses the function to determine if the conditions to enter USB Suspend were met.
Parameters:
None
Return Value: uint8 cystatus: Standard API return values.
Return Value
Side Effects:
Description
1
Bus activity was detected since the last call to this function
0
Bus activity was not detected since the last call to this function
None
Document Number: 001-81341 Rev. **
Page 31 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
void USBFS_Suspend(void)
Description:
This function disables the USBFS block and prepares for power down mode. It should be
called just before entering sleep.
USBFS_Suspend() also initializes the interrupt for the D+ pin for wakeup from the sleep
mode from the PICU source.
After the conditions to enter USB suspend are met, the application takes appropriate steps to
reduce current consumption to meet suspend current requirements. To put the USB SIE and
transceiver into power down mode, the application calls the USBFS_Suspend() API function
and the USBFS_CheckActivity() API to detect USB activity. This function disables the
USBFS block, but maintains the current USB address (in the USBCR register). The device
uses the sleep feature to reduce power consumption.
Parameters:
void
Return Value:
void
Side Effects:
None
void USBFS_Resume(void)
Description:
This function enables the USBFS block after power down mode. It should be called just after
waking from sleep.
While the device is suspended, it periodically checks to determine if the conditions to leave the
suspended state were met. One way to check resume conditions is to use the sleep timer to
periodically wake the device. The second way is to configure the device to wake up from the
PICU.
If the resume conditions are met, the application calls the USBFS_Resume() API function. This
function enables the USBFS SIE and Transceiver, bringing them out of power down mode. It
does not change the USB address field of the USBCR register; it maintains the USB address
previously assigned by the host.
Parameters:
void
Return Value:
void
Side Effects:
None
uint8 USBFS_RWUEnabled(void)
Description:
This function returns the current remote wakeup status.
If the device supports remote wakeup, the application can use this function to determine if the
host enabled remote wakeup. When the device is suspended and it determines the conditions
to initiate a remote wakeup are met, the application uses the USBFS_Force() API function to
force the appropriate J and K states onto the USB, signaling a remote wakeup.
Parameters:
void
Return Value:
True: Remote wakeup enabled
False: Remote wakeup disabled
Side Effects:
Page 32 of 66
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
uint8 USBFS_Resume_Condition(void)
Description:
This function enables the USBIO block after power down mode, reads the current state of the
D+ pin and disables the USBIO block backward when D+ pin is not in low level state.
This function is available for PSoC 5 silicon only, because this device doesn’t have standard
APIs for USB pins and wakeup source from the PICU is not available.
Parameters:
void
Return Value:
Zero for low level D+ pin state and not zero for high level.
Side Effects:
None
Sleep mode API usage example for PSoC 3 where a PICU source is used for wakeup:
USBFS_Suspend();
CyPmSaveClocks();
CyPmSleep(PM_SLEEP_TIME_NONE, PM_SLEEP_SRC_PICU);
CyPmRestoreClocks();
USBFS_Resume();
Sleep mode API usage example for PSoC 5 where a SleepTimer is used for wakeup:
USBFS_Suspend();
CyPmSaveClocks();
do
{
CyPmSleep(PM_SLEEP_TIME_NONE, PM_SLEEP_SRC_NONE);
}while(USBFS_Resume_Condition() != 0);
CyPmRestoreClocks();
USBFS_Resume();
Audio Class Support
See the Audio Class Support section in USBFS Audio for information.
MIDI Class Support
See the MIDI Support section in USBFS MIDI for information.
CDC Class Support
See the CDC Class Support section in USBUART for information.
Interrupt Service Routine
Empty SOF ISR is provided with this component. It is disabled by default. If your application
requires this interrupt it can be enabled by calling:
CyIntEnable(USBFS_SOF_VECT_NUM);
Document Number: 001-81341 Rev. **
Page 33 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
You can place custom code in the designated areas to perform whatever additional function is
required.
In the DMA with Manual and Automatic Memory Management mode, the Arbiter interrupt
(USBFS_arb_int) indicates the completion of service of a DMA request. It is critical for the
system to set the priority of this interrupt higher than the priority of the USBFS_ep_[0..8] and
USBFS_ord_int interrupts. Therefore, the priority for this interrupt is set to the
USBFS_ARB_PRIOR value in the USBFS_Init() function.
Sample Firmware Source Code
PSoC Creator provides many example projects that include schematics and example code in the
Find Example Project dialog. For component-specific examples, open the dialog from the
Component Catalog or an instance of the component in a schematic. For general examples,
open the dialog from the Start Page or File menu. As needed, use the Filter Options in the
dialog to narrow the list of projects available to select.
Refer to the “Find Example Project” topic in the PSoC Creator Help for more information.
Functional Description
The following diagram shows a simple bus-powered USB application with the D+ and D– pins
from the PSoC device.
VCC
U
S
B
VCC
DD+
GND
22 Ohm 1%
DD+
22 Ohm 1%
Simple USB Application
CY8C38
Family
USB Compliance
USB drivers can present various bus conditions to the device, including Bus Resets, and
different timing requirements. Not all of these can be correctly illustrated in the examples
provided. It is your responsibility to design applications that conform to the USB spec.
USB Compliance for Self-Powered Devices
If the device that you are creating is self powered, you must connect a GPIO pin to VBUS
through a resistive network and write firmware to monitor the status of the GPIO. You can use
the USBFS_Start() and USBFS_Stop() API routines to control the D+ and D– pin pull-ups. The
Page 34 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
pull-up resistor does not supply power to the data line until you call USBFS_Start().
USBFS_Stop() disconnects the pull-up resistor from the data pin.
The device responds to GET_STATUS requests based on the status set with the
USBFS_SetPowerStatus() function. To set the correct status, USBFS_SetPowerStatus() should
be called at least once if your device is configured as self powered. You should also call the
USBFS_SetPowerStatus() function any time your device changes status.
USB Standard Device Requests
This section describes the requests supported by the USBFS component. If a request is not
supported, the USBFS component responds with a STALL, indicating a request error.
Standard Device
Request
CLEAR_FEATURE
USB Component Support Description
Device
USB 2.0
Spec
Section
9.4.1
Interface
Endpoint
GET_CONFIGURATION
Returns the current device configuration value
9.4.2
GET_DESCRIPTOR
Returns the specified descriptor
9.4.3
GET_INTERFACE
Returns the selected alternate interface setting for the specified interface
9.4.4
GET_STATUS
Device
9.4.5
Interface
Endpoint
SET_ADDRESS
Sets the device address for all future device accesses
9.4.6
SET_CONFIGURATION
Sets the device configuration
9.4.7
SET_DESCRIPTOR
This optional request is not supported
9.4.8
SET_FEATURE
Device:
9.4.9
DEVICE_REMOTE_WAKEUP support is selected by the bRemoteWakeUp
component parameter.
TEST_MODE is not supported.
Interface
Endpoint: The specified Endpoint is halted.
SET_INTERFACE
Allows the host to select an alternate setting for the specified interface.
9.4.10
SYNCH_FRAME
Not supported. Future implementations of the component will add support
to this request to enable Isochronous transfers with repeating frame
patterns.
9.4.11
Document Number: 001-81341 Rev. **
Page 35 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
HID Class Request
Class Request
USBFS Component Support Description
Device
Class
Definition
for HID Section
GET_REPORT
Allows the host to receive a report by way of the Control pipe.
7.2.1
GET_IDLE
Reads the current idle rate for a particular Input report.
7.2.3
GET_PROTOCOL
Reads which protocol is currently active (either the boot or the report
protocol).
7.2.5
SET_REPORT
Allows the host to send a report to the device, possibly setting the state of
input, output, or feature controls.
7.2.2
SET_IDLE
Silences a particular report on the Interrupt In pipe until a new event occurs or
the specified amount of time passes.
7.2.4
SET_PROTOCOL
Switches between the boot protocol and the report protocol (or vice versa).
7.2.6
AUDIO Class Request
See the Audio Class Request section in USBFS Audio for information.
CDC Class Request
See the CDC Class Request section in USBUART for information.
USBFS Audio
The USBFS component provides support for Audio class descriptors. The USBFS Audio
interface is implemented according to the Universal Serial Bus Device Class Definition for Audio
Devices 1.0 and 2.0 specifications.
Component Parameters
Drag a USBFS component onto your design and double-click it to open the Configure USBFS
dialog.
Page 36 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Audio Descriptor Tab
The Audio Descriptor tab is used to add and configure audio interface descriptors.
To Add Audio Descriptors
1. Select the Audio Descriptors root item in the tree on the left.
2. Under the Audio Descriptors List on the right, select either the Audio Control or Audio
Streaming interface.
3. Under Item Value, enter bAlternateSetting and bInterfaceNumber values as appropriate.
Other fields are optional.
Note These values are set manually. By contrast, for the general interface descriptors, these
values are set automatically.
4. Click Add to add the descriptor to the tree on the left.
You can rename the Audio Interface x title by selecting a node and clicking on it.
To Add Class-Specific Audio Control or Audio Streaming Interface Descriptors
1. Select the appropriate AC Alternate Settings x or AS Alternate Settings x item in the tree
on the left.
2. Under the Audio Descriptors List on the right, select one of the items under Audio Control
Descriptors (1.0), Audio Control Descriptors (2.0), Audio Streaming Descriptors (1.0),
or Audio Streaming Descriptors (2.0) as appropriate.
Document Number: 001-81341 Rev. **
Page 37 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Versions 1.0 and 2.0 refer to the versions of the corresponding specification document
Universal Serial Bus Device Class Definition for Audio Devices.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add Audio Endpoint Descriptors
1. Select the appropriate AC Alternate Settings x or AS Alternate Settings x item in the tree
on the left.
2. Under the Audio Descriptors List on the right, select the Endpoint Descriptor item.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add Standard AS Isochronous Synch Endpoint Descriptor
1. Select the appropriate Endpoint Descriptor in the tree on the left.
2. Under the Audio Descriptors List on the right, select AS Endpoint Descriptor.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add the Configured Audio Interface Descriptor to the Device Descriptor Tree
1. Go to the Device Descriptor tab.
2. Select the Configuration Descriptor to which a new interface will belong.
3. Click the Add Interface tool button, choose Audio, and select the appropriate item to add.
Audio interfaces are disabled in the Device Descriptor tab list because they can only be
edited on the Audio Descriptor tab.
Note Click Apply or OK to save the changes on the various tabs. If you click Cancel, the
descriptors you added will not be saved.
Page 38 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
USBFS Audio Application Programming Interface
By default, PSoC Creator assigns the instance name “USBFS_1” to the first instance of a
component in a given design. You can rename it to any unique value that follows the syntactic
rules for identifiers. The instance name becomes the prefix of every global function name,
variable, and constant symbol. For readability, the instance name used in the following table is
“USBFS.”
Audio Class Support
Global Variables
Variable
Description
USBFS_currentSampleFrequency
Contains the current audio sample frequency. It is set by the host using a
SET_CUR request to the endpoint.
USBFS_frequencyChanged
Used as a flag for the user code, to inform it that the host has been sent a
request to change the sample frequency. The sample frequency will be sent
on the next OUT transaction. It contains the endpoint address when set. The
following code is recommended for detecting new sample frequency in main
code:
if((USBFS_frequencyChanged != 0) &&
(USBFS_transferState == USBFS_TRANS_STATE_IDLE))
{
/* Add core here.*/
USBFS_frequencyChanged = 0;
}
The USBFS_transferState variable is checked to make sure that the transfer
completes.
USBFS_currentMute
Contains the mute configuration set by the host.
USBFS_currentVolume
Contains the volume level set by the host.
Document Number: 001-81341 Rev. **
Page 39 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
USBFS Audio Functional Description
Audio Class Request
This section describes the requests supported by the USBFS component. If a request is not
supported, the USBFS component responds with a STALL, indicating a request error.
Class Request
SET_CUR
USBFS Component Support Description
Interface:
Device
Class
Definition
for Audio Section
5.2.1.1
MUTE_CONTROL
VOLUME_CONTROL
Endpoint:
SAMPLING_FREQ_CONTROL
GET_CUR
Interface:
5.2.1.2
MUTE_CONTROL
VOLUME_CONTROL
Endpoint:
SAMPLING_FREQ_CONTROL
GET_MIN
Interface:
5.2.1.2
VOLUME_CONTROL
GET_MAX
Interface:
5.2.1.2
VOLUME_CONTROL
GET_RES
Interface:
5.2.1.2
VOLUME_CONTROL
GET_STAT
The content of the status message is reserved for future use. For now, a null
packet should be returned in the data stage of the control transfer and the
received null packet should be ACKed.
5.2.4.2
USBFS MIDI
USBFS MIDI provides support for communicating with external MIDI equipment. It also provides
support for the USB device class definition for MIDI devices. You can use this component to add
MIDI I/O capability to a standalone device, or to implement MIDI capability for a host computer or
mobile device through that computer or mobile device's USB port. In such cases, it presents
itself to the host computer or mobile device as a class-compliant USB MIDI device and uses the
native MIDI drivers in the host.
Page 40 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Features:





Provides USB MIDI Class Compliant MIDI input and output
Supports hardware interfacing to external MIDI equipment using UART
Provides adjustable transmit and receive buffers managed using interrupts
Handles MIDI running status for both receive and transmit functions
Supports up to 16 input and output ports using only two USB endpoints by using virtual
cables.
The PSoC Creator Component Catalog contains a Schematic Macro implementation of a MIDI
interface. The macro consists of instances of the UART component with the hardware MIDI
interface configuration (31.25 kbps, 8 data bits) and a USBFS component with the descriptors
configured to support MIDI devices. This allows the end user to use a MIDI-enabled USBFS
component with minimal configuration changes.
To start a MIDI-based project, drag the USBMIDI Schematic Macro labeled ‘USBMIDI’ from the
Component Catalog onto your design. This macro has already been configured to function as an
external mode MIDI device with 1 input and 1 output. See the Component Parameters section of
this datasheet for information about modifying the parameters of this interface, such as the VID,
PID, and String Descriptors.
The UART component is connected to digital input and output Pins components. The output pin
is connected through the NOT gate to prepare the inverted signal to be supplied to the external
transistor. Refer to the MIDI 1.0 Detailed Specification for more details about the hardware MIDI
interface.
To update the USBMIDI Schematic Macro for the external mode with 2 inputs and 2
outputs:
1. Go to the MIDI Descriptor tab of the USBMIDI_1 component.
Document Number: 001-81341 Rev. **
Page 41 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
2. Click the Import MIDI Interface button, browse to the following directory, and open the
USBMIDI 2x2.midi.xml file.
<INSTALL>\psoc\content\cycomponentlibrary\CyComponentLibrary.cylib\USBFS_v2.12\Custom\
template\
3. Drag the UART Schematic Macro from the Component Catalog onto your design.
4. Configure the UART with the following options:
Name:
MIDI2_UART
Mode:
Full UART
Bits per second:
31250
Data bits:
8
Parity:
None
RX Buffer Size (bytes)
255
TX Buffer Size (bytes)
255
5. Connect the output pin through the NOT gate.
USBFS MIDI Parameters
Drag a USBMIDI macro onto your design and double-click it to open the Configure USBFS
dialog.
Page 42 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
MIDI Descriptor Tab
The MIDI Descriptor tab is used to add and configure MIDI Streaming interface descriptors.
To Add MIDI Descriptors
1. Select the MIDI Descriptors root item in the tree on the left.
2. Under Audio / MIDI Descriptors List on the right, select either the Audio Control or MIDI
Streaming interface.
3. Under Item Value, enter bAlternateSetting and bInterfaceNumber values as appropriate.
Other fields are optional.
Note These values are set manually. By contrast, for the general interface descriptors, these
values are set automatically.
4. Click Add to add the descriptor to the tree on the left.
You can rename the MIDI Interface x title by selecting a node and then clicking on it.
To Add Class-Specific Audio Control or MIDI Streaming Interface Descriptors
1. Select the appropriate AC Alternate Settings x or MS Alternate Settings x item in the tree
on the left.
2. Under the Audio / MIDI Descriptors List on the right, select one of the items under Audio
Control Descriptors (1.0), Audio Control Descriptors (2.0), or MIDI Streaming
Descriptors as appropriate.
Document Number: 001-81341 Rev. **
Page 43 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Versions 1.0 and 2.0 refer to the versions of the corresponding specification document
Universal Serial Bus Device Class Definition for Audio Devices.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add MIDI Endpoint Descriptors
1. Select the appropriate AC Alternate Settings x or MS Alternate Settings x item in the tree
on the left.
2. Under the Audio / MIDI Descriptors List on the right, select the Endpoint Descriptor item.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add Standard MS Bulk Data Endpoint Descriptor
1. Select the appropriate Endpoint Descriptor in the tree on the left.
2. Under the Audio / MIDI Descriptors List on the right, select MS Endpoint Descriptor.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add the Configured MIDI Interface Descriptor to the Device Descriptor Tree
1. Go to the Device Descriptor tab.
2. Select the Configuration Descriptor to which a new interface will belong.
3. Click the Add Interface tool button, choose MIDI, and select the appropriate item to add.
MIDI interfaces are disabled in the Device Descriptor tab list because they can only be
edited on the MIDI Descriptor tab.
Note Click Apply or OK to save the changes on the various tabs. If you click Cancel, the
descriptors you added will not be saved.
Page 44 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
USBFS MIDI Application Programming Interface
By default, PSoC Creator assigns the instance name “USBFS_1” to the first instance of a
component in a given design. You can rename it to any unique value that follows the syntactic
rules for identifiers. The instance name becomes the prefix of every global function name,
variable, and constant symbol. For readability, the instance name used in the following table is
“USBMIDI.”
MIDI Support
The following high-level APIs are available when the Enable MIDI Class API option in the MIDI
Descriptor tab is selected.
Function
Description
USBMIDI_MIDI_EP_Init()
Initializes the MIDI interface and UARTs to be ready to receive data from
the PC and MIDI ports.
USBMIDI MIDI_IN_Service()
Services the USB MIDI IN endpoint.
USBMIDI MIDI_OUT_EP_Service()
Services the USB MIDI OUT endpoint.
USBMIDI_PutUsbMidiIn()
Puts one MIDI message into the USB MIDI IN endpoint buffer. This is a
MIDI input message to the host.
USBMIDI_callbackLocalMidiEvent() Is a callback function from USBMIDI_midi.c to local processing in main.c.
Global Variables
Variable
Description
USBMIDI_midiInBuffer
Input endpoint buffer with a length equal to MIDI IN EP Max Packet Size. This
buffer is used to save and combine the data received from the UARTs,
generated internally by USBMIDI_PutUsbMidiIn() function messages, or both.
The USBMIDI_MIDI_IN_Service() function transfers the data from this buffer to
the PC.
USBMIDI_midiOutBuffer
Output endpoint buffer with a length equal to MIDI OUT EP Max Packet Size.
This buffer is used by the USBMIDI_MIDI_OUT_EP_Service() function to save
the data received from the PC. The received data is then parsed. The parsed
data is transferred to the UARTs buffer and also used for internal processing by
the USBMIDI_callbackLocalMidiEvent() function.
USBMIDI_midiInPointer
Input endpoint buffer pointer. This pointer is used as an index for the
USBMIDI_midiInBuffer to write data. It is cleared to zero by the
USBMIDI_MIDI_EP_Init() function.
USBMIDI_midi_in_ep
Contains the midi IN endpoint number, It is initialized after a
SET_CONFIGURATION request based on a user descriptor. It is used in MIDI
APIs to send data to the PC.
Document Number: 001-81341 Rev. **
Page 45 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
Variable
Description
USBMIDI_midi_out_ep
Contains the midi OUT endpoint number. It is initialized after a
SET_CONFIGURATION request based on a user descriptor. It is used in MIDI
APIs to receive data from the PC.
USBMIDI_MIDI1_InqFlags
These optional variables are allocated when External Mode is enabled. The
following flags help to detect and generate responses for SysEx messages.
USBMIDI_MIDI2_InqFlags
Flag
Description
USBMIDI_INQ_SYSEX_FLAG
Non-real-time SysEx message received.
USBMIDI_INQ_IDENTITY_REQ_
FLAG
Identity Request received. You should
clear this bit when an Identity Reply
message is generated.
void USBMIDI_MIDI_EP_Init(void)
Description:
This function initializes the MIDI interface and UARTs to be ready to receive data from the
PC and MIDI ports.
Parameters:
None
Return Value:
None
Side Effects:
Changes the priority of the UARTs’ TX and RX interrupts. For more information, see the
Interrupt Priority section
void USBMIDI_MIDI_IN_Service(void)
Description:
This function services the traffic from MIDI input ports (RX UARTs) or generated by the
USBMIDI_PutUsbMidiIn() function and sends the data to the USBMIDI IN endpoint. It is
non-blocking and should be called from the main foreground task. For more information
about the usage of this API, see the USBFS MIDI Functional Description section.
This function is not protected from reentrant calls. When you must use this function in
UART RX ISR to guaranty low latency, take care to protect it from reentrant calls.
Parameters:
None
Return Value:
None
Side Effects:
None
Page 46 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
void USBMIDI_MIDI_OUT_EP_Service(void)
Description:
This function services the traffic from the USBMIDI OUT endpoint and sends the data to
the MIDI output ports (TX UARTs). It is blocked by the UART when not enough space is
available in the UART TX buffer.
This function is automatically called from OUT EP ISR in DMA with Automatic Memory
Management mode. In Manual and DMA with Manual EP Management modes you must
call it from the main foreground task.
Parameters:
None
Return Value:
None
Side Effects:
None
uint8 USBMIDI_PutUsbMidiIn(uint8 ic, uint8* midiMsg, uint8 cable)
Description:
This function puts one MIDI message into the USB MIDI In endpoint buffer. This is a MIDI
input message to the host. This function is used only if the device has internal MIDI input
functionality. The USBMIDI_MIDI_IN_Service() function should also be called to send the
message from local buffer to the IN endpoint.
Parameters:
ic: The length of the MIDI message or command is described on the following table.
Value
Description
0
No message (should never happen)
1-3
Complete MIDI message in midiMsg
3 - IN EP Max Packet Size
Complete SysEx message (without the EOSEX byte) in
midiMsg
USBMIDI_MIDI_SYSEX
Start or continuation of SysEx message. Put event bytes
in the midiMsg buffer
USBMIDI_MIDI_EOSEX
End of SysEx message. Put event bytes in the midiMsg
buffer
USBMIDI_MIDI_TUNEREQ
0xF8 to 0xFF
Tune Request message (single-byte system common
message)
Single-byte real-time message
midiMsg: Pointer to MIDI message
cable: Cable number
Return Value:
Return Value
Side Effects:
Description
USBMIDI_TRUE
Host is not ready to receive this message
USBMIDI_FALSE
Success transfer
None
Document Number: 001-81341 Rev. **
Page 47 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
void USBMIDI_callbackLocalMidiEvent(uint8 cable, uint8* msgBuffer)
Description:
This is a callback function that locally processes data received from the PC in main.c. You
should implement this function if you want to use it. It is called from the USB output
processing routine for each MIDI output event processed (decoded) from the output
endpoint buffer.
Parameters:
cable: Cable number
msgBuffer: Pointer to the 3-byte MIDI message
Return Value:
None
Side Effects:
None
USBFS MIDI Functional Description
The MIDI descriptor tab allows you to easily create a MIDI interface device with one or more sets
of physical MIDI ports (you may have to place and configure instances of a UART component). It
handles all details of sending and receiving MIDI messages to external MIDI equipment. This is
referred to as external MIDI functionality and is an optional setting in the component.
The MIDI implementation internally handles running status when communicating with external
MIDI equipment. Running status is automatically implemented on the output to reduce serial data
traffic, and running status in managed on the input to correctly assemble complete MIDI
messages when the external MIDI equipment is sent using running status. Refer to MIDI 1.0
Detailed Specification for more details about Running Status feature.
Figure 3 shows the external mode USB-MIDI interface with two inputs and two outputs.
Figure 3. External Mode USB-MIDI Interface
MIDI1_UART Component
MIDI1_UART_RXISR
USBMIDI_MIDI_IN_Service()
MIDI1_UART_TXISR
USBMIDI Component
MIDI BULK IN EP
USB
MIDI BULK OUT EP
USBMIDI_MIDI_OUT_EP_Service()
External MIDI IN1
External MIDI OUT1
MIDI2_UART Component
MIDI2_UART_RXISR
USBMIDI_MIDI_IN_Service()
MIDI2_UART_TXISR
External MIDI IN2
External MIDI OUT2
Internal MIDI functionality
Switches or Sensors
USBMIDI_PutUsbMidiIn()
USBMIDI_MIDI_IN_Service()
USBMIDI_callbackGetUsbMidiOut()
Digital or Analog outputs
Page 48 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Implementing external functionality requires you to place and configure UART components with
the names “MIDI1_UART” and “MIDI2_UART”. These hardcoded names allow the USBMIDI
component to call UART APIs and automatically transfer received data from the host messages
to the external MIDI port. In Manual and DMA with Manual EP management mode, you must call
the USBMIDI_MIDI_OUT_EP_Service() API from the main loop.
For the opposite direction, to service MIDI event data from the UART components you must call
the USBMIDI_MIDI_IN_Service() API in the main loop for Manual and DMA with Manual memory
management mode. For DMA with Automatic mode, call this function from the user
section(MIDI[1..2]_UART_RXISR_END) of the Interrupt Service Routine for the RX portion of the
UART(MIDI[1..2]_UART_RXISR).
You can use local switches and sensors to create MIDI messages for the host (use the
USBMIDI_PutUsbMidiIn() function). MIDI messages from the host can directly control local
functions such as digital and analog outputs (implement the USBMIDI_callbackLocalMidiEvent()
function, which is called to process all received messages).
Interrupt Priority
The data received from the host is serviced inside the MIDI BULK OUT EP ISR. When you select
a small UART TX Buffer Size, the code waits for the UART transmit operation to complete and
continues filling the TX buffer. The priority of the Interrupt Service Routine for the TX portion of
the UART should be higher than the MIDI BULK OUT EP ISR priority. The
USBMIDI_MIDI_EP_Init() function automatically changes the default priority for the mentioned
interrupt to the USBMIDI_CUSTOM_UART_TX_PRIOR_NUM value. Cypress recommends that
you select UART TX Buffer Size to be the same or greater than MIDI BULK OUT EP Max
Packet Size. The optimal Max Packet Size is 32.
The priority of the UART RX ISR should be higher than TX ISR so that the four bytes of
hardware FIFO overloads are not allowed. The optimal UART RX Buffer Size is 255. The
USBMIDI_MIDI_EP_Init() function automatically changes the default priority for the UART RX
interrupt to the USBMIDI_CUSTOM_UART_RX_PRIOR_NUM value. The
USBMIDI_MIDI_EP_Init() function automatically changes the default priority for the UART RX
interrupt to the USBMIDI_CUSTOM_UART_RX_PRIOR_NUM value.
USBUART
The PSoC Creator Component Catalog contains a Schematic Macro implementation of a CDC
interface (also known as USBUART). This is a USBFS component with the descriptors
configured to implement a CDC interface. This allows you to use a CDC-enabled USBFS
component with minimal configuration required.
Document Number: 001-81341 Rev. **
Page 49 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
To start a USBUART-based project, drag the USBUART Schematic Macro labeled ‘USBUART
(CDC Interface)’ from the Component Catalog onto your design. This macro has already been
configured to function as a CDC device. See the Component Parameters section of this
datasheet for information about modifying the parameters of this interface, such as the VID, PID,
and String Descriptors.
USBUART Parameters
Drag a USBUART macro onto your design and double-click it to open the Configure USBFS
dialog.
CDC Descriptor Tab
The CDC Descriptor tab is used to add and configure communications and data interface
descriptors.
To Add CDC Descriptors
1. Select the CDC Descriptors root item in the tree on the left.
2. Under the CDC Descriptors List on the right, select either the Communications or Data
interface.
3. Under Item Value, enter bAlternateSetting and bInterfaceNumber values as appropriate.
Other fields are optional.
Page 50 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Note These values are set manually. By contrast, for the general interface descriptors these
values are set automatically.
4. Click Add to add the descriptor to the tree on the left.
5. You can rename the CDC Interface x title by selecting a node and clicking on it.
To Add Functional Descriptors
1. Select the appropriate Communications Alternate Settings x item in the tree on the left.
2. Under the CDC Descriptors List on the right, select one of the items under Functional
Descriptors as appropriate.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add Endpoint Descriptors
1. Select the appropriate Communications Alternate Settings x or Data Alternate Settings x
item in the tree on the left.
2. Under the CDC Descriptors List on the right, select the Endpoint Descriptor item.
3. Under Item Value, enter the appropriate values under Specific.
4. Click Add to add the descriptor to the tree on the left.
To Add the Configured CDC Interface Descriptor to the Device Descriptor Tree
1. Go to the Device Descriptor tab.
2. Select the Configuration Descriptor to which a new interface will belong.
3. Click the Add Interface tool button, choose CDC, and select the appropriate item to add.
CDC interfaces are disabled in the Device Descriptor tab list because they can only be
edited on the CDC Descriptor tab.
Note Click Apply or OK to save the changes on the various tabs. If you click Cancel, the
descriptors you added will not be saved.
Document Number: 001-81341 Rev. **
Page 51 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
USBUART Application Programming Interface
By default, PSoC Creator assigns the instance name “USBUART_1” to the first instance of a
component in a given design. You can rename it to any unique value that follows the syntactic
rules for identifiers. The instance name becomes the prefix of every global function name,
variable, and constant symbol. For readability, the instance name used in the following table is
“USBUART.”
CDC Class Support
The following high-level APIs are available when the Enable CDC Class API option in the CDC
Descriptor tab is selected. These APIs do not support DMA with Automatic Memory
Management.
Function
Description
USBUART_CDC_Init()
Initializes the CDC interface to be ready for the receive data from the PC
USBUART_PutData()
Sends a specified number of bytes from the location specified by a pointer to the
PC
USBUART_PutString()
Sends a null terminated string to the PC
USBUART_PutChar()
Writes a single character to the PC
USBUART_PutCRLF()
Sends a carriage return (0x0D) and line feed (0x0A) to the PC
USBUART_GetCount()
Returns the number of bytes that were received from the PC
USBUART_CDCIsReady()
Returns a nonzero value if the component is ready to send more data to the PC
USBUART_DataIsReady()
Returns a nonzero value if the component received data or received a zerolength packet
USBUART_GetData()
Gets a specified number of bytes from the input buffer and places them in a data
array specified by the passed pointer
USBUART_GetAll()
Gets all bytes of received data from the input buffer and places them into a
specified data array
USBUART_GetChar()
Reads one byte of received data from the buffer
USBUART_IsLineChanged()
Returns the clear-on-read status of the line
USBUART_GetDTERate()
Returns the data terminal rate set for this port in bits per second
USBUART_GetCharFormat()
Returns the number of stop bits
USBUART_GetParityType()
Returns the parity type for the CDC port
USBUART_GetDataBits()
Returns the number of data bits for the CDC port
USBUART_GetLineControl()
Returns the line control bitmap
Page 52 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
Global Variables
Variable
Description
USBUART_lineCoding
Contains the current line coding structure. The host sets it using a
SET_LINE_CODING request and returns it to the user code using the
USBUART_GetDTERate(), USBUART_GetCharFormat(),
USBUART_GetParityType(), and USBUART_GetDataBits() APIs.
USBUART_lineControlBitmap
Contains the current control-signal bitmap. The host sets it using a
SET_CONTROL_LINE request and returns it to the user code using the
USBUART_GetLineControl() API.
USBUART_lineChanged
Used as a flag for the USBUART_IsLineChanged() API, to inform it that the host
has been sent a request to change line coding or control bitmap.
USBUART_cdc_data_in_ep
Contains the data IN endpoint number. It is initialized after a
SET_CONFIGURATION request based on a user descriptor. It is used in CDC
APIs to send data to the PC.
USBUART_cdc_data_out_ep
Contains the data OUT endpoint number. It is initialized after a
SET_CONFIGURATION request based on user descriptor. It is used in CDC
APIs to receive data from the PC.
void USBUART_CDC_Init(void)
Description:
This function initializes the CDC interface to be ready for the receive data from the PC. This
API should be called after the device has been configured.
Parameters:
None
Return Value:
None
Side Effects:
None
void USBUART_PutData(uint8* pData, uint16 length)
Description:
This function sends a specified number of bytes from the location specified by a pointer to
the PC.
Parameters:
pData: Pointer to the buffer containing data to be sent
length: Specifies the number of bytes to send from the pData buffer. Maximum length is
limited by the maximum packet size for the endpoint.
Return Value:
None
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 53 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
void USBUART_PutString(char8* string)
Description:
This function sends a null terminated string to the PC.
Parameters:
string: Pointer to the string to be sent to the PC
Return Value:
None
Side Effects:
None
void USBUART_PutChar(char8 txDataByte)
Description:
This function writes a single character to the PC.
Parameters:
txDataByte: Character to be sent to the PC
Return Value:
None
Side Effects:
None
void USBUART_PutCRLF(void)
Description:
This function sends a carriage return (0x0D) and line feed (0x0A) to the PC.
Parameters:
None
Return Value:
None
Side Effects:
None
uint16 USBUART_GetCount(void)
Description:
This function returns the number of bytes that were received from the PC.
Parameters:
None
Return Value:
uint16: Returns the number of received bytes
Side Effects:
None
uint8 USBUART_DataIsReady(void)
Description:
This function returns a nonzero value if the component received data or received a zerolength packet. The USBUART_GetAll() or USBUART_GetData() API should be called to
read data from the buffer and reinitialize the OUT endpoint even when a zero-length packet
is received.
Parameters:
None
Return Value:
uint8: If the OUT packet is received, this function returns a nonzero value. Otherwise, it
returns zero.
Side Effects:
None
Page 54 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
uint8 USBUART_CDCIsReady(void)
Description:
This function returns a nonzero value if the component is ready to send more data to the
PC; otherwise, it returns zero. The function should be called before sending new data, to
be sure that the previous data has finished sending.
Parameters:
None
Return Value:
uint8: If the buffer can accept new data, this function returns a nonzero value. Otherwise, it
returns zero.
Side Effects:
None
uint16 USBUART_GetData(uint8* pData, uint16 length)
Description:
This function gets a specified number of bytes from the input buffer and places them in a
data array specified by the passed pointer. The USBUART_DataIsReady() API should be
called first, to be sure that data is received from the host.
Parameters:
pData: Pointer to the data array where data will be placed
length: Number of bytes to read into the data array from the RX buffer. The maximum
length is limited by the number of received bytes.
Return Value:
uint16: Number of bytes received
Side Effects:
None
uint16 USBUART_GetAll(uint8* pData)
Description:
This function gets all bytes of received data from the input buffer and places them into a
specified data array. The USBUART_DataIsReady() API should be called first, to be sure
that data is received from the host.
Parameters:
pData: Pointer to the data array where data will be placed.
Return Value:
uint16: Number of bytes received.
Side Effects:
None
uint8 USBUART_GetChar(void)
Description:
This function reads one byte of received data from the buffer.
Parameters:
None
Return Value:
uint8: Received one character
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 55 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
uint8 USBUART_IsLineChanged(void)
Description:
This function returns the clear-on-read status of the line.
Parameters:
None
Return Value:
uint8: If SET_LINE_CODING or CDC_SET_CONTROL_LINE_STATE requests are
received, it returns a nonzero value. Otherwise, it returns zero.
Return Value
Description
USBUART_LINE_CODING_CHANGED
Line coding changed
USBUART_LINE_CONTROL_CHANGED Line control changed
Side Effects:
None
uint32 USBUART_GetDTERate(void)
Description:
This function returns the data terminal rate set for this port in bits per second.
Parameters:
None
Return Value:
uint32: Returns a value of the data rate in bits per second
Side Effects:
None
uint8 USBUART_GetCharFormat(void)
Description:
This function returns the number of stop bits.
Parameters:
None
Return Value:
uint8: Returns the number of stop bits.
Return Value
USBUART_1_STOPBIT
Description
1 stop bit
USBUART_1_5_STOPBITS 1,5 stop bits
USBUART_2_STOPBITS
Side Effects:
Page 56 of 66
2 stop bits
None
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
uint8 USBUART_GetParityType(void)
Description:
This function returns the parity type for the CDC port.
Parameters:
None
Return Value:
uint8:
Return Value
Side Effects:
Description
USBUART_PARITY_NONE
None
USBUART_PARITY_ODD
Odd
USBUART_PARITY_EVEN
Even
USBUART_PARITY_MARK
Mark
USBUART_PARITY_SPACE
Space
None
uint8 USBUART_GetDataBits(void)
Description:
This function returns the number of data bits for the CDC port.
Parameters:
None
Return Value:
uint8: Returns the number of data bits. The number of data bits can be 5, 6, 7, 8, or 16.
Side Effects:
None
uint16 USBUART_GetLineControl (void)
Description:
This function returns the line control bitmap.
Parameters:
None.
Return Value: uint8:
Return Value
Notes
USBUART_LINE_CONTROL_DTR
Indicates that a DTR signal is present. This signal
corresponds to V.24 signal 108/2 and RS232 signal
DTR.
USBUART_LINE_CONTROL_RTS
Carrier control for half-duplex modems. This signal
corresponds to V.24 signal 105 and RS232 signal
RTS.
Note Some terminal emulation programs do not properly handle these control signals.
Side Effects:
None
Document Number: 001-81341 Rev. **
Page 57 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
USBUART Functional Description
CDC Class Request
This section describes the requests supported by the USBUART component. If a request is not
supported, the USBUART component responds with a STALL, indicating a request error.
Class Request
USBUART Component Support Description
Communications
Class Subclass
Specification for
PSTN Devices
SET_LINE_CODING
Allows the host to specify typical asynchronous linecharacter formatting properties. It applies to data transfers
both from the host to the device and from the device to the
host.
6.3.10
GET_LINE_CODING
Allows the host to find out the currently configured line
coding.
6.3.11
SET_CONTROL_LINE_STATE Generates RS
6.3.12
Code Example (CE60246) USBUART Migration
Before the addition of USBUART CDC support in the USBFS v2.0 component (available in PSoC
Creator 2.0 or later), a USBUART component was available as a Code Example component in
CE60246 - USBUART in PSoC® 3 / PSoC 5. This Code Example USBUART is no longer
supported and you are encouraged to migrate to the official component. This section details the
steps required to complete this migration.
Schematic
1. Open your existing design in PSoC Creator 2.0 or later.
2. Take note of your existing component name, Vendor ID, Product ID, Device Release,
Manufacturer String, and Product String in your existing USBUART component.
3. Delete your existing USBUART component.
4. Place a ‘USBUART (CDC Interface)’ component from the PSoC Creator Component Catalog
onto your design.
5. Open the new component and configure the component with the parameters noted from the
previous USBUART design. See the Component Parameters section of this datasheet for
details about how to enter the VID, PID, and various device strings into the new component.
Page 58 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Full Speed USB (USBFS)
API
Table 1 outlines the required API changes to migrate from the CE60246 USBUART to the
USBFS v2.0+ version of the USBUART. Most changes are minor modifications and should have
a minimal effect on the existing project. Note that the USBFS v2.0+ version of the USBUART
includes a larger selection of CDC-specific APIs (see the CDC Class Support API list earlier in
the datasheet).
Table 1. API Migration
CE60246 API
USBFS v2.0+ API
Changes Required in Migration
void USBUART_1_Init(void)
void USBUART_1_CDC_Init(void)

API name change
uint8 USBUART_1_bGetRxCount
(void)
uint16 USBUART_1_GetCount(void)


API name change
void USBUART_1_ReadAll(uint8*
pData)
uint16 USBUART_1_GetAll(uint8*
pData)


API name change
void USBUART_1_Write(uint8
*pData, uint8 bLength)
void USBUART_1_PutData(uint8*
pData, uint16 length)


API name change

API name change
uint8 USBUART_1_bTxIsReady(void) uint8 USBUART_1_CDCIsReady(void)
Return value changed from
uint8 to uint16
Return value changed from
void to uint16
Length parameter type
changed from uint8 to uint16
Note The table assumes the component name is “USBUART_1”
Resources
USB is implemented as a fixed-function block. The component utilizes 6 Interrupts and 2 Pins.
API Memory Usage
The component memory usage varies significantly, depending on the compiler, device, number
of APIs used and component configuration. The following table provides the memory usage for
all APIs available in the given component configuration.
The measurements have been done with the associated compiler configured in Release mode
with optimization set for Size. For a specific design the map file generated by the compiler can
be analyzed to determine the memory usage.
PSoC 3 (Keil_PK51)
Configuration
Default USBFS
PSoC 5 (GCC)
PSoC 5LP (GCC)
Flash
SRAM
Flash
SRAM
Flash
SRAM
Bytes
Bytes
Bytes
Bytes
Bytes
Bytes
6004
133
4332
154
4516
154
Document Number: 001-81341 Rev. **
Page 59 of 66
®
Full Speed USB (USBFS)
PSoC Creator™ Component Datasheet
PSoC 3 (Keil_PK51)
Configuration
Maximum, with HID,CDC
and MIDI
PSoC 5 (GCC)
PSoC 5LP (GCC)
Flash
SRAM
Flash
SRAM
Flash
SRAM
Bytes
Bytes
Bytes
Bytes
Bytes
Bytes
11553
302
8504
172
8696
172
DC and AC Electrical Characteristics
Specifications are valid for –40 °C ≤ TA ≤ 85 °C and TJ ≤ 100 °C, except where noted.
Specifications are valid for 1.71 V to 5.5 V, except where noted.
USB DC Specifications
Parameter
Min
Typ
Max
USB configured, USB
regulator enabled
4.35
–
5.25
V
VUSB_3.3
USB configured, USB
regulator bypassed
3.15
–
3.6
V
VUSB_3
USB configured, USB
regulator bypassed
2.85
–
3.6
V
VDDD = 5 V
–
10
–
mA
VDDD = 3.3 V
–
8
–
mA
VDDD = 5 V, connected to
USB host, PICU configured to
wake on USB resume signal
–
0.5
–
mA
VDDD = 5 V, disconnected
from USB host
–
0.3
–
mA
VDDD = 3.3 V, connected to
USB host, PICU configured to
wake on USB resume signal
–
0.5
–
mA
VDDD = 3.3 V, disconnected
from USB host
–
0.3
–
mA
VDDD = 5 V, bus clock ≥ 33
MHz
–
55
–
mA
VDDD = 3.3 V, bus clock ≥ 33
MHz
–
40
–
mA
VUSB_5
Description
Device supply for USB
operation
Conditions
Units
PSoC 3
IUSB_Configured
IUSB_Suspended
Device supply current in
device active mode, bus clock
and IMO = 24 MHz
Device supply current in
device sleep mode
PSoC 5
IUSB_Configured
Page 60 of 66
Device supply current in
device active mode
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Parameter
IUSB_Suspended
Description
Device supply current in
device sleep mode
Full Speed USB (USBFS)
Conditions
Min
Typ
Max
Units
VDDD = 5 V, connected to
USB host
–
0.5
–
mA
VDDD = 3.3 V, connected to
USB host
–
0.5
–
mA
Min
Typ
Max
USB Driver AC Specifications
Parameter
Description
Conditions
Units
Tr
Transition rise time
–
–
20
ns
Tf
Transition fall time
–
–
20
ns
TR
Rise/fall time matching
90%
–
111%
VCRS
Output signal crossover voltage
1.3
–
2
Document Number: 001-81341 Rev. **
V
Page 61 of 66
Full Speed USB (USBFS)
®
PSoC Creator™ Component Datasheet
Component Changes
This section lists the major changes in the component from the previous version.
Version
2.30
Description of Changes
Fixed unexpected endpoint reconfiguration after A device with multiple interfaces and alternate settings
SET_INTERFACE request sent to interface not must reconfigure only endpoints which are required by
related to affected endpoint.
SetInterface request.
Added user code sections(`#START`...`#END`)
to the SET_CUR/GET_CUR Audio class
requests handler.
2.20
Reason for Changes / Impact
To let the user update volume control requests handler
with multi-channel audio volume control support.
Added PSoC 5LP silicon support.
Updated characterization data.
Minor datasheet edits.
2.12
Added MIDI devices support:

Added the new “MIDI Descriptor” tab. This
tab allows the user to configure MIDI
descriptors.

Optional high level APIs.
The MIDI interface has been implemented as
described in Universal Serial Bus Device Class
Definition for MIDI Devices v1.0 documentation.
Added the USBFS_Resume_Condition() API for A PSoC 5 device has neither PICU wakeup source nor
PSoC 5 only device to check the condition for
standard D+ pin APIs to check the condition for waking
resume.
up. This function reads the D+ pin level through USBIO
block and returns the resume condition.
Reorganized the datasheet.
2.11
Added all USBFS APIs with the
CYREENTRANT keyword when they are
included in the .cyre file.
Not all APIs are truly reentrant. Comments in the
component API source files indicate which functions
are candidates.
This change is required to eliminate compiler warnings
for functions that are not reentrant used in a safe way:
protected from concurrent calls by flags or Critical
Sections.
The data toggle is always set to DATA0 when
performing an IN data transfer for an
isochronous endpoint.
According to the USB 2.0 specification for Isochronous
Transactions, a full-speed device should only send
DATA0 PIDs in data packets.
Fixed the Stop_DMA function to free all of the
endpoint DMA TDs used for Mode 3 operation.
This function stopped only one channel.
Changed default driver mode for the VBUS
monitor input pin to High Impedance and
removed the suppressing API generation for
this pin.
This change allows you to reduce power consumption
for low power projects.
Page 62 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Version
Description of Changes
Full Speed USB (USBFS)
Reason for Changes / Impact
2.10
Fixed handling of the class-specific requests in
USBFS_DispatchClassRqst() function.
The Audio requests were stalled.
2.0
Added CDC class support:
The CDC interface has been implemented as
described in Section 4 of the USB Class Definitions for
Communications Devices v1.2 documentation.

Added new “CDC Descriptor” tab. This tab
allows the user to configure CDC
descriptors.

SET_LINE_CODING/GET_LINE_CODING
CLR_CUR/SET_CONTROL_LINE_STATE
CDC class request support.

Optional high level APIs.
Added Audio Class 2.0 class support.
On the “Audio” tab, added two new groups of
available descriptors.
New descriptors represent USB Device Class
Definition for Audio Devices release 2.0 specification.
They are called “Audio Control Descriptors
(2.0)” and “Audio Streaming Descriptors (2.0)”.
Existing groups “Audio Control Descriptors” and
“Audio Streaming Descriptors” were renamed to
“Audio Control Descriptors (1.0)” and “Audio
Streaming Descriptors (1.0)”.
Added DMA transfers implementation:

Mode2: Manual DMA with Manual Memory
Management

Mode3: Auto DMA with Auto Memory
Management

USBFS_InitEP_DMA() API has been
added.

USBFS_LoadInEP()/USBFS_ReadOutEP()
APIs modified to support DMA transfers.
Document Number: 001-81341 Rev. **
DMA transaction releases the CPU use during data
transfers.
Page 63 of 66
Full Speed USB (USBFS)
Version
Description of Changes
Added function
USBFS_IsConfigurationChanged().
®
PSoC Creator™ Component Datasheet
Reason for Changes / Impact
Win 7 OS could send double SET_CONFIGURATION
requests with same configuration number. In this case
user-level code should re-enable OUT endpoints after
each request.
This function should be used to detect that
configuration has been changed from the PC. If it
returns a nonzero value, the
USBFS_GetConfiguration() API is can be used to get
the configuration number.
Usage model in main loop:
if(USBFS_IsConfigurationChanged() !=
0)
{
if(USBFS_GetConfiguration() != 0)
{
USBFS_EnableOutEP(OUT_EP);
}
}
1.60
Fixed issue with Wakeup from Sleep mode.
USB_BUS_RST_CNT register is nonretention and
should be reloaded after sleep mode for correct USB
enumeration of PSoC 3 ES2 and PSoC 5 silicon.
Moved the endpoint memory management
group box from the device options panel to the
root device options panel.
Endpoint memory management settings should be
global for whole configuration.
Added function USBFS_TerminateEP(uint8 ep)
to NAK an endpoint.
This function can be used before endpoint
reconfiguration or device mode switching.
Initialized USBFS_hidProtocol variable to
HID_PROTOCOL_REPORT value in
USBFS_InitComponent() and
USBFS_reInitComponent() functions.
To comply with HID “7.2.6 Set_Protocol Request” --“When initialized, all devices default to report protocol.”
Added support for
SET_FEATURE/CLR_FEATURE requests to
an interface.
For passing WHQL test.
Added logic to the SET_IDLE request handling
to support proper timing.
To comply with HID "7.2.4 Set_Idle Request"
Added support for Audio class requests:
SET_CUR/CLR_CUR to an interface and
Endpoint for Sampling Frequency, Mute, and
Volume controls.
To comply with Audio Class Definition “5.2.1.1 Set
Request” and “5.2.1.2 Get Request”
Renamed Bootloader APIs to have instance
name first. Added the backward compatible
defines.
Preparation for future ability to boot from multiple
interfaces.
In the previous version these settings were individual
for each device descriptor.
Added characterization data to datasheet
Page 64 of 66
Document Number: 001-81341 Rev. **
®
PSoC Creator™ Component Datasheet
Version
Description of Changes
Full Speed USB (USBFS)
Reason for Changes / Impact
Minor datasheet edits and updates
1.50.a
Made datasheet change log cumulative
Customer convenience.
1.50
Added USB Suspend, Resume, and Remote
Wakeup functionality.
The USB device should support suspend and resume
functionality.
Renamed most APIs to remove Hungarian
To comply with corporate coding standards.
notation, old names are supported for backward
compatibility.
Added GET_INTERFACE/SET_INTERFACE
requests support.
A device must support the GetInterface/SetInterface
requests if it has alternate settings for that interface.
Integrated specific APIs to support the
bootloader: CyBtldrCommStart,
CyBtldrCommStop, CyBtldrCommReset,
CyBtldrCommWrite, CyBtldrCommRead.
USB could be used as a communication component for
the Bootloader with this feature.
Added generic USB Bulk Wraparound Transfer
example to datasheet.
Described generic USB usage for user.
Added the extern_cls and extern_vnd
parameters to the Advanced tab of the
Configure dialog.
These parameters enable other components at the
solutions level, to provide their handling of Vendor and
Class requests themselves.
Restriction has been added to DMA w/Manual
Memory Management section.
This restriction shows how to properly use Mode 2/3
transfers.
Modified 'Advanced' tab layout.
Replaced the data grid with check boxes with
information about each parameter to improve usability.
Added Audio Descriptors tab to the Configure
dialog.
This allows you to add and configure audio descriptors
for your component.
Removed SOF ISR enable/disable from
Start/Stop APIs.
SOF interrupts occur each 1 ms, but were not used by
the component. If an application requires this interrupt,
it can be enabled by calling:
CyIntEnable(USBFS_SOF_VECT_NUM);
1.30.b
Added information to the component that
The tool reports an error/warning if the component is
advertizes its compatibility with silicon revisions. used on incompatible silicon. If this happens, update to
a revision that supports your target device.
1.30.a
Moved local parameters to formal parameter
list.
Document Number: 001-81341 Rev. **
To address a defect that existed in PSoC Creator v1.0
Beta 4.1 and earlier, the component was updated so
that it could continue to be used in newer versions of
the tool. This component used local parameters, which
are not exposed to the user, to do background
calculations on user input. These parameters have
been changed to formal parameters which are visible,
but not editable. There are no functional changes to
the component but the affected parameters are now
visible in the “expression view” of the customizer
dialog.
Page 65 of 66
Full Speed USB (USBFS)
Version
1.30
Description of Changes
Updated the Configure dialog and datasheet.
®
PSoC Creator™ Component Datasheet
Reason for Changes / Impact
Added the Enable SOF Output parameter to the
Advanced tab of the Configure dialog.
Updated the USBFS_ReadOutEP() function in the
datasheet to reflect the correct return value.
1.20.b
Added information to the component that
The tool reports an error/warning if the component is
advertizes its compatibility with silicon revisions. used on incompatible silicon. If this happens, update to
a revision that supports your target device.
1.20.a
Moved local parameters to formal parameter
list.
1.10.b
Added information to the component that
The tool reports an error/warning if the component is
advertizes its compatibility with silicon revisions. used on incompatible silicon. If this happens, update to
a revision that supports your target device.
1.10.a
Moved local parameters to formal parameter
list.
To address a defect that existed in PSoC Creator v1.0
Beta 4.1 and earlier, the component was updated so
that it could continue to be used in newer versions of
the tool. This component used local parameters, which
are not exposed to the user, to do background
calculations on user input. These parameters have
been changed to formal parameters which are visible,
but uneditable. There are no functional changes to the
component but the affected parameters are now visible
in the “expression view” of the customizer dialog.
To address a defect that existed in PSoC Creator v1.0
Beta 4.1 and earlier, the component was updated so
that it could continue to be used in newer versions of
the tool. This component used local parameters, which
are not exposed to the user, to do background
calculations on user input. These parameters have
been changed to formal parameters which are visible,
but un-editable. There are no functional changes to the
component but the affected parameters are now visible
in the “expression view” of the customizer dialog.
© Cypress Semiconductor Corporation, 2012. The information contained herein is subject to change without notice. Cypress Semiconductor Corporation assumes no responsibility for the use of
any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any license under patent or other rights. Cypress products are not warranted nor intended to be used
for medical, life support, life saving, critical control or safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, Cypress does not authorize its products for
use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress products in lifesupport systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges.
PSoC® is a registered trademark, and PSoC Creator™ and Programmable System-on-Chip™ are trademarks of Cypress Semiconductor Corp. All other trademarks or registered trademarks
referenced herein are property of the respective corporations.
Any Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide patent protection (United States and
foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a personal, non-exclusive, non-transferable license to copy, use, modify, create
derivative works of, and compile the Cypress Source Code and derivative works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in
conjunction with a Cypress integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code except as
specified above is prohibited without the express written permission of Cypress.
Disclaimer: CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes without further notice to the materials described herein.
Cypress does not assume any liability arising out of the application or use of any product or circuit described herein. Cypress does not authorize its products for use as critical components in lifesupport systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a life-support systems application
implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges.
Use may be limited by and subject to the applicable Cypress software license agreement.
Page 66 of 66
Document Number: 001-81341 Rev. **