PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) 1.60 Features • USB Full Speed device interface driver • Support for interrupt, control, bulk, and isochronous transfer types • Runtime support for descriptor set selection • Optional USB string descriptors • Optional USB HID class support • Optional Boot Loader support General Description The USBFS component provides a USB full speed Chapter 9 compliant device framework. The component 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 enable easy descriptor construction. You have the option of constructing an 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 web site: 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. 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. Cypress Semiconductor Corporation • 198 Champion Court • San Jose, CA 95134-1709 • 408-943-2600 Document Number: 001-65431 Rev. ** Revised December 14, 2010 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 3. Configure the following clocks: • ILO: Select 100 kHz. • IMO: Select Osc 24.000 MHz. • USB: Enable and select IMOx2 – 48.000 MHz. Note If the selected device is PSoC 3 ES2 or PSoC 5, you must also configure the PLL to "Desired 33 MHz" and the Master Clock to "PLL_OUT (33.000 MHz)". 4. Select Build to generate APIs; refer to the Sample Firmware Source Code section for an example demonstrating the basic functionality of the USBFS component, as well as the basic set-up instructions. Input/Output Connections This section describes the various 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 "out_sof" parameter in advanced configuration tab is set to enable. 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: Page 2 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Device Descriptor Tab 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 or it is 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-65431 Rev. ** Page 3 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet Endpoint Memory Management 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 at once after SET_CONFIGURATION request. The largest length is taken when multiple Alternate settings uses same EP number. • Dynamic Allocation - The memory for the endpoints is allocated dynamically after each SET_CONFIGURATION and SET_INTERFACE requests. This option is useful when multiple alternate settings are used with mutually exclusive EP settings. DMA w/Manual Memory Management – Select this option to expose the DMA interface registers, in addition to the LoadInEP/ReadOutEP functions. PSoC 3 does not support DMA transactions directly between USB endpoints and other peripherals. All DMA transactions involving USB endpoints (IN & OUT) must terminate or originate with main system memory. Applications requiring DMA 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 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Configuration Descriptor Configuration Attributes • Configuration string • Max Power (mA) Enter the maximum power consumption of the USB device from the bus in this specific configuration when the device is fully operational. Note A device configuration reports whether the configuration is bus-powered or selfpowered. 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 may not 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 usages simultaneously. • Remote Wakeup – Enabled or Disabled Document Number: 001-65431 Rev. ** Page 5 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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 will use isochronous endpoints, note that the USB 2.0 specification requires that all device default interface settings must not include any isochronous endpoints with non-zero data payload sizes. This is specified via Max Packet Size in the endpoint descriptor. For isochronous devices, you should use an alternate interface setting other than the default Alternate Setting 0 to specify non-zero data payload sizes for isochronous endpoints. Additionally, if your isochronous endpoints have a large data payload size, it is recommended that additional alternate configurations or interface settings be used 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. Page 6 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Interface Descriptor—Alternate Settings Interface Attributes • Interface String • Interface Number — The interface number is computed by the customizer • Alternate Settings — The alternate setting is computed by the customizer • Class – HID, Vendor Specific or Undefined • Subclass – Dependent upon 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 an HID Report to the Alternate Setting. Document Number: 001-65431 Rev. ** Page 7 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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. Page 8 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) 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, Interrupt, Bulk, or Isochronous Data transfers • Interval (ms) – Polling interval specific to this endpoint. A full-speed endpoint can specify a desired 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 1023 bytes for isochronous endpoints. Document Number: 001-65431 Rev. ** Page 9 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet String Descriptor Tab String Descriptors • LANGID – Language ID selection. • String – Value of string descriptor. Page 10 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Serial Number String • Value – Default string. • User Entered Text – Enables Value text box. • User Call Back – USBFS_SerialNumString function sets pointer to use the user generated serial number string descriptor. The application firmware may supply the source of the USB device descriptor’s serial number string during runtime. • Silicon Generated Serial Number Document Number: 001-65431 Rev. ** Page 11 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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" Page 12 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) 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. Document Number: 001-65431 Rev. ** Page 13 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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 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 and the descriptor is added to the tree on the left. You can rename the "Audio Interface x" title by selecting a node and then 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. Page 14 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) 2. Under the Audio Descriptors List on the right, select one of the items under "Audio Control Descriptors" or "Audio Streaming Descriptors" as appropriate. 3. Under Item Value, enter the appropriate values under "Specific." 4. Click Add and the descriptor is added 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 "Endpoint Descriptor” item. 3. Under Item Value, enter the appropriate values under "Specific." 4. Click Add and the descriptor is added 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 and the descriptor is added 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 Audio Interface tool button, and select the appropriate item to add. Audio interfaces will be grayed out in the Device Descriptor tab list because they can only be edited on the Audio Descriptor tab. Document Number: 001-65431 Rev. ** Page 15 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet Note Click Apply or OK to save the changes on the various tabs. If you click Cancel all the descriptors you added will not be saved. Advanced Tab External Class This parameter allows for the user firmware, or other components at the solutions level, to provide handling of the class requests. 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 provide handling of the vendor specific requests. USBFS_HandleVendorRqst() function should be implemented if this parameter is enabled. Enable VBUS Monitoring The USB specification requires that no device shall supply 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. This pin must be connected to the VBUS and must be assigned in the Pin Editor. See the USB Compliance for Self Powered Devices section for additional information. Page 16 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Enable SOF output This parameter enables Start-of-Frame output. Placement USB is implemented as a fixed function block. Resources Resource Type Resources USBFS Clock Macrocells Interrupts Dividers 0 0 7 API Memory (Bytes) USB Fixed Blocks Flash RAM Pins (per External I/O) 1 3767 119 2 Clock Settings The USB hardware block requires system clocks to 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 3 ES2 or PSoC 5, the Bus Clock cannot be slower than 33 MHz [for Master Clock, select PLL_OUT (33.000 MHz)]. There are different ways to configure the system clocks to comply with these requirements. The following shows one set of options you may use. Your design may require different settings. Document Number: 001-65431 Rev. ** Page 17 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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 cover 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 Activate the component for use with the device and specific voltage mode. USBFS_Init Initialize component’s hardware. USBFS_InitComponent Initialize component’s global variables and initiate communication with Host by pull up D+ line. Page 18 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Function Full Speed USB (USBFS) Description USBFS_Stop Disable component. USBFS_GetConfiguration Returns the currently assigned configuration. Returns 0 if the device is not configured. USBFS_GetInterfaceSetting Returns the current alternate setting for the specified interface. USBFS_GetEPState Returns the current state of the specified USBFS endpoint. USBFS_GetEPAckState Identifies whether ACK was set by returning a non-zero value. USBFS_GetEPCount Returns the current byte count from the specified USBFS endpoint. 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. The function 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 runtime. USBFS_TerminateEP Terminates Endpoint transfers. Global Variables Variable Description USBFS_initVar 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 in 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. Alternately, 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 USBFS_Start() or USBFS_InitComponent() APIs. USBFS_transferState This variable used by the communication functions to handle current transfer state. Initialized to TRANS_STATE_IDLE in USBFS_InitComponent() API and after complete transfer in status stage. Changed to the TRANS_STATE_CONTROL_READ or TRANS_STATE_CONTROL_WRITE in Setup transaction depend on request type. Document Number: 001-65431 Rev. ** Page 19 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet Variable Description USBFS_configuration Contains current configuration number which is set by the Host using SET_CONFIGURATION request. This variable is initialized to zero in USBFS_InitComponent() API, returns to the application level by the USBFS_GetConfiguration() API._ USBFS_deviceAddress Contains current device address. This variable is initialized to zero in USBFS_InitComponent() API. Host starts to communicate to device with address 0 and then set it to whatever value using SET_ADDRESS request. USBFS_deviceStatus This is two bit variable which contain power status in first bit (DEVICE_STATUS_BUS_POWERED or DEVICE_STATUS_SELF_POWERED) and remote wakeup status (DEVICE_STATUS_REMOTE_WAKEUP) in 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: Performs all required initialization for USBFS Component. Parameters: (uint8) device: Contains the device number from the desired device descriptor set entered with the USBFS customizer. (uint8) mode: The operating voltage. This determines whether the voltage regulator is enabled for 5V 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 voltage regulator and pass-thru Vcc for pull-up USBFS_5V_OPERATION Enable voltage regulator and use regulator for pullup USBFS_DWR_VDDD_OPERATION Enable or Disable voltage regulator depend on Vddd Voltage configuration in DWR. Return Value: None Side Effects: None void USBFS_Init(void) Description: 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 Page 20 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) void USBFS_InitComponent (uint8 device, uint8 mode) Description: Initialize component’s global variables and initiate communication with Host by pull up D+ line. Parameters: (uint8) device: Contains the device number from the desired device descriptor set entered with the USBFS customizer. (uint8) mode: The operating voltage. This determines whether the voltage regulator is enabled for 5V operation or if pass through mode is used for 3.3V operation. Symbolic names and their associated values are given in the following table. Power Setting Notes USBFS_3V_OPERATION Disable voltage regulator and pass-thru Vcc for pull-up USBFS_5V_OPERATION Enable voltage regulator and use regulator for pullup USBFS_DWR_VDDD_OPERATION Enable or Disable voltage regulator depend on Vddd Voltage configuration in DWR. Return Value: None Side Effects: This function called from the Reset ISR to initialize communication. void USBFS_Stop(void) Description: Performs all necessary shutdown task required for the USBFS Component. Parameters: None Return Value: None Side Effects: None uint8 USBFS_GetConfiguration(void) Description: 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 Document Number: 001-65431 Rev. ** Page 21 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet uint8 USBFS_GetInterfaceSetting(uint8 interfaceNumber) Description: 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: None uint8 USBFS_GetEPState(uint8 epNumber) Description: Returns the state of the requested endpoint. Parameters: (uint8) epNumber: The data endpoint number. Return Value: (uint8) Returns the current state of the specified USBFS endpoint. Symbolic names provided, 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 Indicates that the endpoint is awaiting SIE action USBFS_EVENT_PENDING Indicates that the endpoint is awaiting CPU action USBFS_NO_EVENT_ALLOWED Indicates that 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: Determines whether or not an ACK transaction occurred on this endpoint by reading the ACK bit in the control register of the endpoint. This function does not clear the ACK bit. Parameters: (uint8) epNumber: Contains the data endpoint number. Return Value: (uint8): If an ACKed transaction occurred then this function returns a non-zero value. Otherwise a zero is returned. Side Effects: None Page 22 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) uint16 USBFS_GetEPCount(uint8 epNumber) Description: Returns the transfer count for the requested endpoint. The value from the count registers includes 2 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 void USBFS_LoadInEP(uint8 epNumber, uint8 *pData, uint16 length) Description: Loads and enables the specified USB data endpoint for an IN interrupt or bulk transfer. Parameters: (uint8) epNumber: Contains the data endpoint number. (uint8) *pData: A 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. Return Value: None Side Effects: None uint16 USBFS_ReadOutEP(uint8 epNumber, uint8 *pData, uint16 length) Description: 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. Parameters: (uint8) epNumber: Contains the data endpoint number. (uint8) *pData: A 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 USB OUT endpoint and loads it into data array. Valid values are between 0 and 512. 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: Enables the specified endpoint for OUT bulk or interrupt transfers. 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-65431 Rev. ** Page 23 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet void USBFS_DisableOutEP(uint8 epNumber) Description: 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 void USBFS_SetPowerStatus(uint8 powerStatus) Description: Sets the current power status. The device will reply to USB GET_STATUS requests based on this value. This allows the device to properly report its status for USB Chapter 9 compliance. Devices may 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 are provided 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: Forces a USB J, K, or SE0 state on the D+/D- lines. This function provides the necessary mechanism for a USB device application to perform a USB Remote Wakeup. For more information, refer to 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 provided, and their associated values are listed here: State 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: None Page 24 of 37 Description Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) void USBFS_SerialNumString(uint8 *snString) Description: This function available only when the "User Call Back" option in the "Serial Number String" descriptor properties is selected. Application firmware may provide the source of the USB device serial number string descriptor during runtime. Default string will be used if the application firmware does not use this function or sets the wrong string descriptor. Parameters: (uint8) *snString: pointer to user defined string descriptor. 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: Terminates the specified USBFS endpoint. This function is usable before endpoint reconfiguration. Parameters: (uint8) epNumber: Contains the data endpoint number. Return Value: None Side Effects: Device response NAK to the IN or OUT token to the terminated endpoint. 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 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 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 HID_SET_IDLE request and used by the USBFS_UpdateHIDTimer() API to reload timer. USBFS_hidIdleTimer This variable contains timer counter, which is decremented and reloaded by the USBFS_UpdateHIDTimer() API. Document Number: 001-65431 Rev. ** Page 25 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet uint8 USBFS_UpdateHIDTimer(uint8 interface) Description: Updates the HID Report idle timer and returns the status. 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 are provided 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 Returned if the report is sent when data or state changes. Side Effects: None uint8 USBFS_GetProtocol(uint8 interface) Description: 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 Boot Loader Support The USBFS component could be used as a communication component for the Bootloader. The following configurations should be used to support communication protocol from an external system to the Bootloader: • Endpoint Number: EP1, Direction: OUT, Transfer Type – INT, Max Packet Size: 64 • 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 bootloader.root.xml file. <INSTALL>\psoc\content\cycomponentlibrary\CyComponentLibrary.cylib\USBFS_v1_60\Custom \template\ See more information about Bootloader in System Reference Guide. The USBFS Component provides a set of API functions for the Bootloader usage. Function USBFS_CyBtldrCommStart Page 26 of 37 Description Performs all required initialization for USBFS Component, waits on the enumeration and enables the communication. Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Function Full Speed USB (USBFS) Description 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 boot loader host. The function will handle 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 boot loader host. The function will handle polling to allow a block of data to be completely received from the host device. void USBFS_CyBtldrCommStart(void) Description: Performs all required initialization for USBFS component, waits on the enumeration and enables the communication. Parameters: None Return Value: None Side Effects: This function starts the USBFS with 3 V operation. void USBFS_CyBtldrCommStop(void) Description: Parameters: Return Value: Side Effects: Performs all necessary shutdown task required for the USBFS component. None None Calls the USBFS_Stop() function. void USBFS_CyBtldrCommReset(void) Description: Resets the receive and transmit communication buffers. Parameters: None Return Value: None Side Effects: None Document Number: 001-65431 Rev. ** Page 27 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet cystatus USBFS_CyBtldrCommWrite(uint8 *data, uint16 size, uint16 *count, uint8 timeOut) Description: Allows the caller to write data to the boot loader host. The function will handle polling to allow a block of data to be completely sent to the host device. Parameters: (uint8) *data: A pointer to the block of data to send to the device. (uint16) size: The 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 1 if no problem was encountered or returns the value that best describes the problem. Side Effects: None cystatus USBFS_CyBtldrCommRead(uint8 *data, uint16 size, uint16 *count, uint8 timeOut) Description: Allows the caller to read data from the boot loader host. The function will handle polling to allow a block of data to be completely received from the host device. Parameters: (uint8) *data: A pointer to the area to store the block of data received from the device. (uint16) size: The 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 1 if no problem was encountered or returns the value that best describes the problem. Side Effects: None USB Suspend, Resume, and Remote Wakeup The USBFS Component supports USB Suspend, Resume, and Remote Wakeup. Since 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 This function disables the USBFS block and prepare for power down mode. USBFS_Resume This function enables the USBFS block after power down mode. USBFS_RWUEnabled This function returns current remote wake up status. Page 28 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) uint8 USBFS_CheckActivity(void) Description: Returns the activity status of the bus. Clears the status hardware to provide fresh activity status on the next call of this routine. This function provides a means to check if 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. Side Effects: Return Value Description 1 If bus activity was detected since the last call to this function 0 If bus activity was not detected since the last call to this function None void USBFS_Suspend(void) Description: This function disables the USBFS block and prepare for power down mode. Should be called just prior to entering sleep. Once 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: void USBFS_Resume(void) Description: This function enables the USBFS block after power down mode. Should be called just after awaking 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. If the resume conditions were 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, maintaining the USB address previously assigned by the host. Parameters: void Return Value: void Side Effects: Document Number: 001-65431 Rev. ** Page 29 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet uint8 USBFS_RWUEnabled(void) Description: This function returns current remote wake up status. If the device supports remote wakeup, the application is able to determine if the host enabled remote wakeup with the USBFS_RWUEnabled() API function. 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 Bus, signaling a remote wakeup. Parameters: void Return Value: TRUE - Remote Wake Up Enabled FALSE - Remote Wake Up Disabled Side Effects: Audio Class Support Global Variables Variable Description USBFS_currentSampleFreq uency Contains the current audio Sample Frequency. It is set by the Host using SET_CUR request to the endpoint. This variable is used as a flag for the user code, to be aware that Host has been sent request for changing Sample Frequency. Sample frequency will be sent on the next OUT transaction. It is contains endpoint address when set. The following code is recommended for detecting new Sample Frequency in main code: if((USBFS_frequencyChanged != 0) && (USBFS_transferState == USBFS_ frequencyChanged USBFS_TRANS_STATE_IDLE)) { /* Add core here.*/ USBFS_frequencyChanged = 0; } USBFS_transferState variable is checked to be sure that transfer completes. USBFS_currentMute USBFS_currentMute: Contains mute configuration set by Host. USBFS_currentVolume USBFS_currentVolume: Contains volume level set by Host. Sample Firmware Source Code PSoC Creator provides numerous 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. Page 30 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Functional Description The following diagram shows a simple bus-powered USB application with the D+ and D- pins from the PSoC device. USB Compliance USB drivers may 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 will be 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 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 Document Number: 001-65431 Rev. ** Page 31 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet Standard Device Request USB Component Support Description USB 2.0 Spec Section 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: DEVICE_REMOTE_WAKEUP support is selected by the bRemoteWakeUp Component Parameter. TEST_MODE is not supported. 9.4.9 Interface: Endpoint: The specified Endpoint is halted. SET_INTERFACE This request 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 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 Page 32 of 37 Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Class Request Full Speed USB (USBFS) USBFS Component Support Description Device Class Definition for HID Section 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 Class Request GET_CUR USBFS Component Support Description Interface: MUTE_CONTROL VOLUME_CONTROL Device Class Definition for Audio Section 5.2.1.1 Endpoint: SAMPLING_FREQ_CONTROL SET_CUR Interface: MUTE_CONTROL VOLUME_CONTROL 5.2.1.2 Endpoint: SAMPLING_FREQ_CONTROL Document Number: 001-65431 Rev. ** Page 33 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet DC and AC Electrical Characteristics USB DC Specifications Parameter VUSB_5 Description Min Typ Max Units 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 – 7 10 mA – 5 8 mA Device supply current in device VDDD = 5 V, connected to USB – sleep mode host, PICU configured to wake on USB resume signal 0.5 1.2 mA VDDD = 5 V, disconnected from – USB host 0.3 1.0 mA VDDD = 3.3 V, connected to – USB host, PICU configured to wake on USB resume signal 0.5 1.2 mA VDDD = 3.3 V, disconnected from USB host 0.3 1.0 mA IUSB_Configured IUSB_Suspended Device supply for USB operation Conditions Device supply current in device VDDD = 5 V active mode, bus clock and VDDD = 3.3 V IMO = 24 MHz – USB Driver AC Specifications Parameter Description Conditions Min Typ Max 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 Page 34 of 37 V Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) Component Changes This section lists the major changes in the component from the previous version. Version 1.60 Description of Changes Reason for Changes / Impact Added function USBFS_TerminateEP(uint8 ep) to NAK an endpoint. This function is usable before endpoint reconfiguration or device mode switching. Initialize USBFS_hidProtocol variable to HID_PROTOCOL_REPORT value in USBFS_InitComponent() and USBFS_reInitComonent() functions. To comply with HID "7.2.6 Set_Protocol Request" --"When initialized, all devices default to report protocol." Added support 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 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" Boot loader APIs were renamed to have Preparation for future ability to boot from multiple instance name ahead. The backward compatible interfaces. defines added. Added characterization data to datasheet Minor datasheet edits and updates 1.50.a Made datasheet change log cumulative Customer convenience. 1.50 USB Suspend, Resume, and Remote Wakeup functionality has been added. USB device should support suspend and resume functionality. Most APIs renamed to remove foreign notation, old names are supported for backward compatibility. To comply with corporate coding standards. GET_INTERFACE/SET_INTERFACE requests support has been added. A device must support the GetInterface/SetInterface requests if it has alternate settings for that interface. Specific APIs were integrated to support the boot loader: CyBtldrCommStart, CyBtldrCommStop, CyBtldrCommReset, CyBtldrCommWrite, CyBtldrCommRead. USB could be used as a communication component for the Boot Loader with this feature. Added generic USB Bulk Wraparound Transfer example to data sheet. 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. 'Advanced' tab layout modified. The data grid was replaced with check boxes with information about each parameter. This was done to improve usability. Document Number: 001-65431 Rev. ** Page 35 of 37 Full Speed USB (USBFS) PSoC® Creator™ Component Data Sheet 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 1ms, but was not used by the component. If 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. 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. 1.30 Updated the Configure dialog and data sheet. 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. 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. 1.10.b The tool reports an error/warning if the component is Added information to the component that 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 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. Page 36 of 37 Added the Enable SOF Output parameter to the Advanced tab of the Configure dialog. Updated the USBFS_ReadOutEP() function in the data sheet to reflect the correct return value. Document Number: 001-65431 Rev. ** PSoC® Creator™ Component Data Sheet Full Speed USB (USBFS) © Cypress Semiconductor Corporation, 2009-2010. 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 life-support 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. Document Number: 001-65431 Rev. ** Page 37 of 37