AN PSoC 3 / PSoC 5: USB Vendor-Specific Device. Application Note Abstract. Introduction

Transcription

1 PSoC 3 / PSoC 5: USB Vendor-Specific Device Application Note Abstract AN56377 Author: Robert Murphy, Hridya Valsaraju Associated Project: Yes Associated Part Family: CY8C3xxx, CY8C5xxx Software Version: PSoC Creator 1.0 Associated Application Notes: None AN56377 discusses how to configure a PSoC 3 / PSoC 5 device as a USB Vendor-Specific device, implement vendor defined commands, and interface PSoC USB applications with a Graphical User Interface (GUI). This application note also explains the packet composition of a SETUP packet and also introduces to BULK transfers. Example projects include a data loopback example and a PC based PWM generator or measurement application. The GUI has been created using Microsoft Visual C# Express in conjunction with Cypress SuiteUSB.NET v3.4 tools. If you are new to PSoC USB, refer to the introductory application notes mentioned in the Related Resources section at the end of this application note. Introduction The USB Specification describes three types of requests to communicate to a device: standard, class, and vendor specific. All USB devices must support standard requests, which are basic status and configuration commands. Class and vendor-specific commands however are optional. Many USB devices are under a predefined USB class specification and support class commands. Examples of the more common device specifications are Human Interface Device (HID), Mass Storage Device, or Communication Device. There are some devices that do not fall under these or any other predefined class. These are called Vendor-Specific devices and are common with USB devices as it allows device designers to create custom communication protocols for USB. Normally, when you plug a class-specific device into a PC, such as a USB flash drive or a keyboard, you are not asked to provide a driver. This is because many operating systems have a class driver included with them, thus freeing developers from having to create a custom driver for their device. However, in applications that are vendor-specific, a driver needs to be created to implement and to initiate vendor specific commands. The example projects included with this application note use the generic Cypress provided USB driver, cyusb.sys, and a.net managed C# DLL, provided by Cypress Suite USB v3.4, for writing host applications. You can download both the driver and the.dll for free from the Cypress website, PSoC Creator automatically generates code to handle standard USB requests and some class requests. You only need to concentrate on the transfer of data to/from the PSoC using the provided PSoC Creator APIs, which are described in the USBFS component datasheet. This application note discusses how to use those API's in conjunction with custom functions to handle vendor specific commands. If you do not have any prior experience with USB, it is recommended that you read the Cypress application note AN57294 USB Peripheral Basics, as an introduction to USB. For other USB topics and examples, see the Related Resources section at the end of this application note. This application note is intended for use with the following hardware/software and is required to fully evaluate the projects associated with this application note: PSoC Creator 1.0 PSoC Programmer 3.12 PSoC Development Kit (CY8CKIT-001) Cypress Suite USB 3.4 Transfer Types Each USB device you plug into a host has different data transfer requirements. These requirements can consist of specific bandwidth, response time, or error checking. The USB Specification defines four various transfer types. Each transfer between the device and host uses one of these transfers and the one it is uses has an effect on the overall performance of the device. These four transfer types are Control, Bulk, Interrupt, and Isochronous. Control transfers are transfers that enable the host to gather information about a device, set a device address, or enable a certain configuration or feature set of a device. Control transfers also enable vendor-specific requests that allow vendors to create their own set of USB requests/commands. All USB devices must support control transfers for reasons that will be discussed in the next section. Error checking is supported by Control transfers. Bulk transfers are used in situations where devices need to move large amounts of data at variable times and where the transfer can use any available bus bandwidth. Bulk transfers are commonly seen in applications such as printers and June 13, 2011 Document No Rev *E 1

2 external USB storage drives. In these applications, if the bus is busy doing a more important task, bulk transfers can take longer to complete then compared to an idle bus due to limited available bandwidth. USB devices are not required to support bulk transfers. Error checking is supported by Bulk transfers. Interrupt transfers are used in situations where the device must periodically get the hosts attention. With an Interrupt transfer, the host will check in with the device. When using an interrupt transfer, the USB system guarantees that the transfer meets the maximum latency, which is defined in the endpoint descriptor. An interrupt transfer is commonly seen in applications such as a keyboard or mouse. USB devices are not required to support Interrupt transfers. Error checking is supported by Interrupt transfers. Isochronous transfers are used when a guaranteed delivery time of the data is required. The disadvantage to use an isochronous transfer is that it lacks error checking. This transfer type is seen in devices such as webcams or USB audio. Applications that use isochronous transfers must be able to accept and handle occasional errors in transmission. USB devices are not required to support isochronous transfers. This application note focuses on Control and Bulk transfers. For more information regarding the capabilities of the above transfer types, refer to Chapter 5 of the USB Specification. For information regarding if any of these transfer types are required for a specific class type you are implementing, refer to the specific class definition provided by USB Implementers Forum. USB Enumeration When a new device is detected, the host sends a series of requests to learn about the device and establish a communication path between the host and the device. This is accomplished with the use of control transfers and EP0. As mentioned earlier, all devices must support standard requests. It is with those standard requests that the host and device communicate with each other. Every control transfer is done through EP0, which is why it is also known as the control endpoint. Enumeration with the host is usually a transparent process to users with the exception of a driver install requirement with some devices if the host does not have native support for the specific device class. Control Transfers and Request Types When a host performs a request, this occurs in the form of a control transfer. A control transfer is meant to retrieve and send information regarding device configuration and device status in class-specific and vendor-specific devices and is initiated by the host. These transfers consist of three stages. Each of these stages consists of various packets as illustrated in Figure 1, which is based on a chart found in USB Complete by Jan Axelson. Figure 1. Flow Chart of Control Transfer As mentioned in the Introduction, most USB transfers will be handled by PSoC Creator API and with standard requests, which are already set up properly for the user in firmware. The following information contains detailed explanation of the control transfers that are used when dealing with vendor specific requests. The first stage in a control transfer is a SETUP stage, which consists of eight bytes, and is intended to identify the transfer and transmit the request. This transaction includes a token packet, which includes information regarding the receiver of the transaction and identifies the transaction as a SETUP. The next stage is the data packet, which contains additional information regarding the request. Figure 2, found in the USB Specification show the organization of the SETUP data packet on a byte-by-byte basis. Figure 2. SETUP Data Packet Format June 13, 2011 Document No Rev *E 2

3 bmrequesttype is a byte that defines the direction of the transfer, the type of request, and the recipient of the request. Bit 7 defines the transfer direction. Here, it is determined if the data will be transferred from host to device, or device to host. Bit 6 and 5 defines the request type of the transfer such as Standard, Class, or Vendor. Bits 4 though 0 define who the request is directed to. This can be a device, interface, endpoint, or other. brequest is a byte that specifies a request. As mentioned earlier, all USB devices must respond to a Standard request. For simplicity, we will use a standard request as an example. The USB Specification currently defines eleven standard requests for control transfers, which are listed in Figure 3. Figure 3. Standard Device Request Table been made. In the SET_ADDRESS example, this value is set to 0. wlength is a two byte value that contains the number of bytes in the data stage that will follow the SETUP stage. If the direction of the transaction, indicated by the Direction bit in bmrequesttype, is an input request (device-to-host), the device can never send more than the number of bytes indicated by wlength. It may however return less. If the request is an output (host-to-device), then wlength will indicate the exact number of bytes to follow. A value 0 in wlength indicates that there is not a data stage. The final packet in the setup stage is the handshake packet and it contains the device acknowledgment of the SETUP stage. The only only acceptable response for the handshake packet is an ACK. In fact, devices must accept and acknowledge every SETUP. If there happens to be an error in the packet, the device will not respond with a handshake. The next stage is the Data stage which consists of multiple IN or OUT transactions and will send the required data in the direction specified in the SETUP transaction. In some control transfers, this stage is optional and can be omitted. This stage is comprised of a token packet, which identifies who will receive the data and defines if this transfer will be an IN or OUT, a data packet, and a handshake packet. Unlike the Setup transaction, an ACK, NAK, or STALL can occur in the handshake stage. The final stage is a Status stage where the device will return the overall status of the transfer. This can take the form of an ACK, NAK, or STALL. For more information in greater detail regarding the composition of the packets along with explanation of the Product Identifier (PID) and Cyclic Redundancy Check (CRC), refer to Chapter 8 of the USB Specification. A flow chart, from the USB Specification, of the overall various control transfers can be seen in Figure 4. Figure 4. Control Transfers Types Let's say for example that a SET_ADRESS request was sent. If we looked at the SETUP packet on a bus analyzer, we would see bits 6 and 5 of bmrequesttype set to 00'b signifying a standard request and brequest set to 0x05. While it is not clear from Figure 3, be aware that CLEAR_FEATURE has a value of 0x00, GET_CONFIGURATION has a value of 0x01, and so on. This is how we can derive a value of 0x05 for SET_ADDRESS from the table. wvalue is a two byte value, which the host uses to pass information to the device. What specifically goes into these two bytes is dependent on what request has been made. Using the SET_ADDRESS example I gave, referencing Figure 2, we can see that the device address will be located in wvalue. windex is a two byte value that the host will use to pass additional information to the device. Normally, this value references an interface or endpoint. What specifically goes into these two bytes is also dependent on what request has There are also some timing requirements associated with a control transfer. PSoC handles the appropriate timing but the following information is provided for additional reference. All standard device requests without a data stage must be completed in 50 ms. Standard device requests with a data stage must start to return data 500 ms after the request. o Each data packet must be sent within 500 ms of the successful transmission of the previous packet. o The status stage must complete within 50 ms after the transmission of the last data packet. June 13, 2011 Document No Rev *E 3

4 The SET_ADDRESS command must process the command and return a status within 50 ms. The device then has 2 ms to change address before the next request is sent. By understanding the composition of a control transfer, you should have a better understanding of how a vendor specific device functions and also understand why a user would want to use a vendor specific device. With this information having been presented, let's now look at how to apply it to a USB application. Project 1: Bulk Loopback Example Start by opening PSoC Creator and create an empty project named USB Loopback. After the project is open, place the USBFS component in the schematic entry page (TopDesign.cysch). This component can be found in the Component Catalog. Figure 5. USBFS Component on Top Schematic View Manually selecting pins in this design is not required as upon building the project, the Device Fitter in PSoC Creator automatically assigns the two USB pins to their dedicated pin locations (P15[6] and P15[7]) as seen in Figure 7. Figure 7. USB Pins Placement The next step is to configure the USB component. Important information regarding the configuration wizard can be found in the USBFS component datasheet. Start by double-clicking the USBFS component in PSoC Creator from TopDesign.cysch. Beginning with the 'Device Descriptor' section, configure the parameters as shown in Figure 8. Figure 8. USBFS Device Descriptor Window After the components are placed, go to the Workspace Explorer window and double-click on Loopback.cydwr. Click on the Clocks tab and then double-click on one of the clocks to open the GUI clock configuration. Adjust the PLL, USB, and IMO settings as required so that the clock configuration looks similar to Figure 6. IMO MHz ILO 100 khz PLL Input: IMO, Desired 48 MHz Master Clock PLL Out USB Clock IMO x 2 Figure 6. System Clocks Configuration for Project 1 Vendor ID - For this application, leave the Vendor ID to the default value of 0x4b4. This Vendor ID is assigned by the USB Implementers Forum. For your product, obtain your own unique Vendor ID from the USB Implementers Forum. Product ID - The entry for this field is determined by the user to suit their own product identification scheme. For this example, the default value of 0x8051 is changed to a new Product ID value of 0x1002. The Vendor ID and Product ID fields are reported to the host computer when PSoC 3 or PSoC 5 is connected to the USB. These fields are used to ensure that the correct driver is loaded and the host computer application used recognizes this example. Changing these values in the PSoC Creator project requires editing the driver file and the GUI code. Device Release - The entry for this field is determined by the vendors to suit their own product identification scheme. A typical use of this entry is a zero based value to identify revisions of a product. As this is the first product release for this application note, set this value to 0. June 13, 2011 Document No Rev *E 4

5 Device Class - This field enables you to define the USB peripheral as either one of the approved USB class devices or as a unique vendor specific device. In this application note the USB interface is defined as a vendor specific device. Use the drop down menu to select Vendor-Specific. Device Subclass - The USB peripheral is defined as a vendor specific device so this field must be left as No subclass. Manufacturing String - Enter your company's name in this field. For this application note, Cypress is entered. Product String - Enter the product name in this field. For this application note, PSoC Loopback is entered. Serial Number String - Enter the product serial number in this field. For this application note, this field is left blank. Endpoint Memory Management - This example project does not use the DMA capability of PSoC 3 and PSoC 5. Select the 'Manual (default)' and 'Static Allocation radio button. Press the Apply button to save the configuration settings. Now select the Configuration Descriptor to continue configuring the USB interface shown in Figure 9. Figure 9. USBFS Configuration Descriptor Window Press the Apply button to save the configuration settings. Next, select 'Alternative Setting 0' and configure the settings as seen in Figure 10. Figure 10. USBFS Alternate Setting 0 Window Interface String - Leave this field blank, because only one interface is described for the USB interface. Interface Number - This field is filled in by PSoC Creator based on the previous entries listed in this application note. Alternate Strings - This field is filled in by PSoC Creator based on the previous entries listed in this application note. Class - Use the drop down menu and select Vendor-Specific. Subclass - Because this example project is a vendor specific class, leave the subclass field in its default setting of No subclass. Press the Apply button to save the settings. Finally, we need to define the endpoints that this example uses to send and receive the host data. Click on Endpoint Descriptor to begin configuring the Endpoints as shown in Figure 11. Figure 11. USBFS Endpoint Configuration Window Configuration String - This field can be left blank because there is only one configuration. This is described in the Device Descriptor strings. Max Power - A bus powered USB interface is defined. The USB Specification defines a device as either a low power device requiring a maximum of one 100 ma unit of power, or as a high power device requiring five units of power. In this application, a full speed USB interface is defined to fit the low power definition. This device can draw a maximum of 100 ma. Your product may require less than one unit load and you can declare the actual maximum ma value used. Device Power - A USB peripheral is defined as being either bus or self powered. For this application note, the peripheral is declared as a bus powered device. Additional USB compliance requirements are needed for a self powered device. However, these requirements are beyond the scope of this application note. Remote Wakeup - The USB Bulk Loopback application does not need to wake a host computer from a standby condition. This field is left 'Disabled'. Endpoint Number - Select an endpoint from the drop down menu. For this example, EP1 is selected. Direction - USB is a host centric interface. All transfers are considered from the host computer perspective. Taking this into account, this application receives data from the host and transfers data from PSoC 3 and PSoC 5 into the host computer. As a result, for this application, both Out and In June 13, 2011 Document No Rev *E 5

6 endpoints must be defined. Define the direction as OUT for this endpoint. Transfer Type - Select a transfer type from the drop down menu. For this example, BULK is selected. Interval - For full speed bulk endpoints, such as those defined for this application, the Interval field does not apply. It is safer to leave it at its default value. Additional information on this field is available in Table 9-13 of the USB 2.0 Specification. Press the Add Endpoint button and repeat the previous steps to define the following additional endpoints: Cypress USB products. A robust API simplifies communications between the host and peripheral device. For this application, a GUI has been created to communicate with the PSoC device by sending and receiving various packets of data. This is shown in Figure 13. Commented source code for this GUI is attached with the project files accompanying this application note. Figure 13. USB Bulk Loopback Example GUI EP2, OUT, BULK, 10, 64 EP3, OUT, BULK, 10, 64 EP4, OUT, BULK, 10, 64 EP5, IN, BULK, 10, 64 EP6, IN, BULK, 10, 64 EP7, IN, BULK, 10, 64 EP8, IN, BULK, 10, 64 Because the USBFS component is a software component, it does not need any wiring tool connections. PSoC Creator will enable the required routing internal to the chip upon generation of the project file. Build the project to generate the APIs. Select 'Build' from the top menu and then 'Build USB Loopback'. PSoC Creator automatically generates the source code files needed for this example project. You only need to add some custom code to the appropriate files. After the project is built, you can begin to add the code in main.c to finalize the project. The required code is located in Appendix 1: main.c for Project 1 of this application note. After modifying main.c rebuild the project. You are now ready to program the firmware into PSoC 3 and PSoC 5. Press the 'Program' icon in PSoC Creator to load the firmware through the PSoC Programmer utility. Figure 12. PSoC Creator Program Button A message stating that the PSoC 3 and PSoC 5 device was successfully programmed is displayed in the bottom status bar of PSoC Creator. Configure the CY8CKIT-001 Configure the development board using the following steps: Set J8 to VBUS Set SW3 to 3.3V Creating a GUI using Cypress Suite USB 3.4 The Cypress Suite USB 3.4 is a powerful yet easy to use tool that enables you to create.net managed C# applications, in conjunction with using Microsoft Visual Studio, to communicate with PSoC 3, PSoC 5, and other Create INF to bind cyusb.sys to PSoC 3 and PSoC 5 As a vendor class device, the generic USB vendor specific driver cyusb.sys is used as an example. To bind this Windows compatible driver to the vendor specific device, you must supply an INF that tells Windows the services and driver needed for the PSoC 3 example. The code in Appendix 2: cyusb.inf for Project 1 is an example of an INF that provides the necessary information to Windows to enable the device to enumerate and enable communications. Project 2: USB Vendor Commands This project discusses the implementation of two vendor commands that are defined to perform the following actions: 1. Change the duty cycle of a PWM output signal to a value inputted by the user on a host computer GUI application. 2. Initiate streaming data to the host computer from any PSoC 3 / PSoC 5 register whose address is selected by the user through the GUI. This implementation helps to monitor any variable at high speed during run time. This is done by using the host computer connected to a PSoC 3 based product. June 13, 2011 Document No Rev *E 6

7 PSoC Creator is used to configure the PSoC 3 or PSoC 5 device with the components used in this example. Create a new project in PSoC Creator named PSoC USB Vendor Commands. Add the following components to the Top Schematic: USBFS PWM ADC Digital Port to use with PWM Analog Port to use with ADC DMA Interrupt to use with DMA Logic Low to use with PWM After adding these components your schematic looks similar to Figure 14. Figure 14. Project 2 Schematic View Configuring the PSoC Components Prior to configuring the individual components, configure the clock settings for this example exactly the same way as they were in Figure 6 of Project 1. IMO MHz ILO 100 khz PLL Input: IMO, Desired 48 MHz Master Clock PLL Out USB Clock IMO x 2 PSoC 3 Pin Assignments In the.cywdr PSoC 3 configuration window, route the digital and analog ports to specific pins. Exactly like in Project 1, the USBFS pins are automatically routed. Only the ADC and PWM pins remain unassigned. For this example, the digital pin is routed to P6[7] and the analog pin to P6[5], as shown in Figure 15. Figure 15. Project 2 Pin Assignments Now configure the individual components that were previously added to this design. To configure the components in PSoC Creator, first select the component on the schematic, then right click and select "Configure" from the available options. A detailed explanation of the reason to use the various components is listed below. The USBFS component is used for communications between PSoC 3 or PSoC 5 and the host computer. The DMA component is used to dump data into the USB Data Register from the user specified register. The PWM component provides you a configurable duty cycle. The ADC is used for easy demonstration of stream from register functionality. The Interrupt is triggered when each DMA transaction is completed. The Analog port pin feeds input from a potentiometer on the development board. The Clock is used for the PWM component. Configuring the USBFS Component In this example, the USB component is configured to report itself to the host computer as a vendor specific peripheral device. PSoC Creator generates most of what is necessary to communicate over USB, simplifying what you need to do for this design. After selecting Configure (as discussed in the previous section), a new window opens. This window enables you to customize the USB component descriptor configuration for this application. Select 'Device Descriptor' to begin customizing the device attributes. The Device Descriptor should look like Figure 16. Figure 16. USBFS Configuration Window The Digital port is used to connect to the output of the PWM. June 13, 2011 Document No Rev *E 7

8 Vendor ID - For this application, leave the Vendor ID to the default value of 0x4b4. This Vendor ID is assigned to Cypress by the USB Implementers Forum. For your product, you must obtain your own unique Vendor ID from the USB Implementers Forum. Product ID - The entry for this field is determined by the vendors to suit their own product identification scheme. For this example, the default value of 0x8051 is changed to a new Product ID value of 0x1122. The Vendor ID and Product ID fields are reported to the host computer when PSoC 3 is connected to the USB. These fields are used to ensure that the correct driver is loaded and that the host computer application used recognizes this example. Device Release - The entry for this field is determined by the vendors to suit their own product identification scheme. A typical use of this entry is a zero based value to identify revisions of a product. As this is the first product for this application note, this value is set to 0. Device Class - This field enables you to define the USB peripheral as either one of the approved USB Class devices or as a unique Vendor Specific device. In this application note, the USB interface is defined as a vendor specific device. Use the drop down menu to select Vendor-Specific. Device Subclass - The USB peripheral is defined as a Vendor specific device, so this field must be left as No subclass. Manufacturing String - You can enter your company's name in this field. For this application note, Cypress is entered. Product String - You can enter the Product name in this field. For this application note, Vendor Commands is entered. Serial Number String - You can enter the Product serial number in this field. For this application note, this field is left blank. Endpoint Memory Management - Select Manual (default) and Static Allocation radio buttons. Press the Apply button to save the configuration settings. Now select the Configuration Descriptor to continue configuring the USB interface as seen in Figure 17. Figure 17. USBFS Configuration Window Configuration String - This field can be left blank, because there is only one configuration. This is described in the Device Descriptor strings. Max Power - A bus powered USB interface is defined. The USB Specification defines a device as either a low power device requiring a maximum of one 100 ma unit of power, or as a high power device requiring five units of power. In this application, a full speed USB interface is defined and it fits the low power definition. This device can draw a maximum of 80 ma. Your product may require less than one unit load and you can declare the actual maximum ma value used. Device Power - A USB peripheral is defined as being either bus or self powered. For this application note, the peripheral is declared as a bus powered device. Additional USB compliance requirements are needed for a self powered device. However, these requirements are beyond the scope of this application note. Remote Wakeup - The USB Control application does not need to wake a host computer from a stand-by condition. This field is left as 'Disabled'. Press the Apply button to save the configuration settings. Next, select Alternative Setting 0 and begin configuring the settings based on Figure 18. Figure 18. Alternate Setting 0 Window June 13, 2011 Document No Rev *E 8

9 Interface String - This field can be left blank, because only one interface is described for the USB interface. Interface Number - This field is filled in by PSoC Creator based on the previous entries made in the Configure USBFS window. Alternate Settings - This field is filled in by PSoC Creator based on the previous entries made in the Configure USBFS window. Use the drop down menu and select Vendor-Specific. CMP Type 1: Less Kill Mode: Disabled (Advanced tab) Interrupts: None (Advanced tab) Figure 20. PWM Configuration Subclass - Because the USB device we create belongs to a vendor specific class, the Subclass field can be left in its default setting of No subclass. Press the Apply button to save the settings. Next, configure the endpoint that this example uses to send data to the host computer. A OUT EP is all that is required because all required IN transfers will occur with a control transfer which is done through EP0. Click on 'Endpoint Descriptor' and configure it based on Figure 19. Figure 19. Endpoint Configuration Window Configuring the DMA Component After opening the configuration window for the DMA, select the following settings for the DMA component: Hardware Request: Disabled Hardware Termination: Disabled Configuring the ADC Component Open the configuration window for the DelSig ADC and select the required ADC settings. In this project, the following settings are similar to Figure 21. Power: High power Conversion: Continuous Endpoint Number - Select an endpoint from the drop down menu. For this example, EP1 is selected. Direction - USB is a host centric interface. All transfers are considered from the host computer perspective. Hence, we define the direction of the endpoint as IN because we stream data from the PSoC USB device into the host computer. Transfer Type - Select a transfer type from the drop down menu. For this example, BULK is selected. Resolution: 8 Conversion Rate: Input Range: Vssa to Vdda (Single Ended) Input Buffer Gain: 1 Reference: Internal Reference Figure 21. DelSig ADC Configuration Interval - For a full speed bulk IN endpoint, such as that defined for this application, the Interval field does not apply. It may be safely left with its default value. Additional information on this field is available in Table 9-13 of the USB 2.0 specification. Configuring the PWM Component After opening the configuration window for PWM_1, select the following settings for the PWM component as seen in Figure 20. Leave the other settings with their default settings: Resolution: 8-bit PWM Mode: One output Period: 255 CMP Value 1: 127 June 13, 2011 Document No Rev *E 9

10 Customizing PSoC Creator Generated Source Code Files PSoC Creator automatically generates the source code file needed for this example project. You only need to add the custom code to the appropriate files. After the project is built, add the code to complete the project in the main.c, USBFS_1_vnd.c, and isr_1.c files. Figure 22. Cypress Suite USB 3.4 GUI for PSoC 3 USB Control Customizing main.c Place the code found in Appendix 3: main.c for Project 2 into the projects main.c file. Customizing USBFS_1_vnd.c Place your custom vendor specific code in this file. This portion of code defines the vendor commands that enable PSoC 3 to carry out specific tasks. The code for this is located in Appendix 4: USBFS_1_vnd.c for Project 2. Customizing isr_1.c The interrupt MyDMADone gets asserted when each DMA transfer is over. When each packet of 64 bytes is filled in the EP1 buffer by DMA, this interrupt is triggered and the variable FINISHED is set to 1. The code snippet for the ISR is located in Appendix 5: isr_1 for Project 2. After modifying the source files, rebuild the project. You are now ready to program the custom firmware into PSoC 3. Pressing the 'Program' icon in PSoC Creator, loads the firmware through the PSoC Programmer utility. A message will be displayed in the bottom status bar of PSoC Creator stating that the PSoC 3 device is successfully programmed. A driver is also required for this example project. The generic cyusb.sys is used in this project and an example.inf file can be found in Appendix 6: cyusb.inf for Project 2. Analyzing the Bus Analyzer Files Figure 23 shows a bus analyzer USB trace of the data transferred after pressing "Stream from register" in the GUI shown in Figure 22. This example uses a 2 Hz square wave input to the ADC which was provided externally via a Function Generator. On PSoC 3 devices, address 0x4e10 is used as it is the address of lower byte of the decimator output which contains the lower byte ADC conversion result. On PSoC 5 devices, address 0x40004e10 is used. Figure 23. Bus Analyzer USB Trace of a IN Data Transfer Configure the CY8CKIT-001 The PSoC 3 development kit has a variable resistor that connects to the analog port defined earlier. Configure the development board using the following steps: Wire connection from VR to P6[5] Connect J11 Jumper Set J8 to VBUS Set SW3 to 3.3 V Graphical User Interface and Driver File For this example project, a GUI is created to capture the streamed data from the register. Similar to the GUI in Project 1, this GUI also uses Cypress Suite USB.dll with Microsoft Visual Studio. A screen shot of the GUI created is shown in Figure 22 Commented source code for this GUI is available as an attachment to this application note. Transferring data to the host is a simple IN transfer, which is seen in many other Cypress USB application notes. But where the bus analyzer data really gets interesting is during the SETUP transaction. With the GUI, when we change the Duty Cycle of the PWM on the PSoC, we perform a control transfer. Looking at Appendix 5: isr_1 for Project 2, you will see that changing the duty cycle has a vendor command of 0xB1. Figure 24 below shows the control transfer for our application. Notice that it lacks a data stage and only consists of a setup and status stage. June 13, 2011 Document No Rev *E 10

11 Figure 24. Duty Cycle Change Control Transfer If we expand out the setup stage, we see the following token, data, and handshake packet in Figure 25. Figure 25. Duty Cycle Change Control Transfer Focusing on the data packet and referring to Figure 2 in the application note, we can decode the data to understand what is being actually being transferred. The first byte is the bmrequesttype. We know the following about our Device. Data Transfer Direction: Host-to-Device Type: Vendor Recipient: Device Using Figure 2, the information above gives a value of 0x40 for bmrequesttype, which can be seen in Figure 25. The second byte in our data packet is brequest which is a value of 0xB1 and can be seen in Figure 25 as well. Next byte in the packet is wvalue. In the GUI, The Duty Cycle was set to a value of 30. A decimal value of 30 converts into 0x1E, which is indeed the 3 rd byte. Since wlength (last two bytes) contains a value of 0x0000, we can see that the data stage was skipped and the status stage appears following the setup stage. Related Resources Application Notes: Beginner Level: USB Peripheral Basics AN57294 PSoC 3 / PSoC 5 USB HID Fundamentals AN57473 Intermediate Level: PSoC 3 / PSoC 5 USB HID Intermediate - AN58726 Example Projects: USBUART in PSoC 3 / PSoC 5 Isochronous Transfers in PSoC 3 / PSoC 5 Interrupt Loopback in PSoC 3 / PSoC 5 About the Authors Name: Robert Murphy Title: Application Engineer Background: Robert Murphy graduated from Purdue University with a Bachelors Degree in Electrical Engineering Technology. Contact: [email protected] Name: Hridya Valsaraju Title: Applications Engineer Contact: [email protected] Summary This application note shows how easy it can be to implement vendor commands with minor effort. All that is required is some changes to the SETUP transaction, firmware to handle the vendor request, and a driver for the vendor specific device. With those three together, the potential possibilities for USB applications becomes even greater then what can be accomplished with standard devices classes alone. References For more information on the USB protocol and vendor commands, refer to the USB 2.0 Specification available at USB Complete by Jan Axelson is also a great learning tool which discussed the topic in this application note in greater detail. June 13, 2011 Document No Rev *E 11

12 Appendix 1: main.c for Project 1 #include <device.h> uint8 OutBuffer[64]; uint8 RcvdBuffer[64]; void main() uint8 i; uint8 my_bc = 0; /* Enable Global Interrupts */ CYGlobalIntEnable; USBFS_1_Start(0, USBFS_1_3V_OPERATION); /* Start USBFS device 0 and with 3V operation */ while(!usbfs_1_bgetconfiguration()); /* Wait for Device to enumerate */ /* Enable EP1-4 OUT */ USBFS_1_EnableOutEP(1); USBFS_1_EnableOutEP(2); USBFS_1_EnableOutEP(3); USBFS_1_EnableOutEP(4); for(;;) if(usbfs_1_bgetepstate(1) == USBFS_1_OUT_BUFFER_FULL) my_bc = USBFS_1_wGetEPCount(1); /* get the size of requested transfer */ USBFS_1_ReadOutEP(1, OutBuffer, my_bc); /* read the data and copy into OutBuffer */ for(i = 0; i<64; i++) RcvdBuffer[i] = OutBuffer[i]; USBFS_1_EnableOutEP(1); /* prime the pump for the next OUT */ if(usbfs_1_bgetepstate(2) == USBFS_1_OUT_BUFFER_FULL) my_bc = USBFS_1_wGetEPCount(2); /* get the size of requested transfer */ USBFS_1_ReadOutEP(2, OutBuffer, my_bc); /* read the data and copy into OutBuffer */ for(i = 0; i<64; i++) RcvdBuffer[i] = OutBuffer[i]; USBFS_1_EnableOutEP(2); /* prime the pump for the next OUT */ if(usbfs_1_bgetepstate(3) == USBFS_1_OUT_BUFFER_FULL) my_bc = USBFS_1_wGetEPCount(3); /* get the size of requested transfer */ USBFS_1_ReadOutEP(3, OutBuffer, my_bc); /* read the data and copy into OutBuffer */ for(i = 0; i<64; i++) RcvdBuffer[i] = OutBuffer[i]; USBFS_1_EnableOutEP(3); /* prime the pump for the next OUT */ if(usbfs_1_bgetepstate(4) == USBFS_1_OUT_BUFFER_FULL) my_bc = USBFS_1_wGetEPCount(4); /* get the size of requested transfer */ USBFS_1_ReadOutEP(4, OutBuffer, my_bc); /* read the data and copy into OutBuffer */ for(i = 0; i<64; i++) RcvdBuffer[i] = OutBuffer[i]; /* prime the pump for the next OUT */ USBFS_1_EnableOutEP(4); if(usbfs_1_bgetepstate(5) == USBFS_1_IN_BUFFER_EMPTY) USBFS_1_LoadInEP(5, RcvdBuffer, my_bc); /* Perform IN transfer */ June 13, 2011 Document No Rev *E 12

13 if(usbfs_1_bgetepstate(6) == USBFS_1_IN_BUFFER_EMPTY) USBFS_1_LoadInEP(6, RcvdBuffer, my_bc); /* Perform IN transfer */ if(usbfs_1_bgetepstate(7) == USBFS_1_IN_BUFFER_EMPTY) USBFS_1_LoadInEP(7, RcvdBuffer, my_bc); /* Perform IN transfer */ if(usbfs_1_bgetepstate(8) == USBFS_1_IN_BUFFER_EMPTY) USBFS_1_LoadInEP(8, RcvdBuffer, my_bc); /* Perform IN transfer */ June 13, 2011 Document No Rev *E 13

14 Appendix 2: cyusb.inf for Project 1 [Version] Signature="$CHICAGO$" Class=USB ClassGUID=36FC9E60-C465-11CF provider=%cypress% ;---Uncomment and complete below to support WHQL submission---; ;CatalogFile= ;DriverVer=mm/dd/yyyy,x.y.v.z ; [Manufacturer] %MfgName%=Cypress [Cypress] %VID_04b4&PID_1002.DeviceDesc%=CYUSB, USB\VID_04b4&PID_1002 ; This entry contains the VID/PID in the ; PSoC 3 / PSoC 5 firmware ; to do ; replace 04b4 (x2) with your unique VID ; replace 1002 (x2) with your unique PID [DestinationDirs] CYUSB.Files = 10,System32\Drivers [CYUSB.Files] CYUSB.SYS [CYUSB.NT] CopyFiles=CYUSB.Files AddReg=CYUSB.AddReg [CYUSB.NT.HW] AddReg=CYUSB.AddReg.Guid [CYUSB.NT.Services] Addservice = CYUSB, 0x , CYUSB.AddService [CYUSB.AddReg] HKR,,DevLoader,,*ntkern HKR,,NTMPDriver,,CyUsb.sys [CYUSB.AddReg.Guid] HKR,,DriverGUID,,%CYUSB.GUID% ;======================================= [CYUSB.AddService] DisplayName = %CYUSB.SvcDesc% ServiceType = 1 ; SERVICE_KERNEL_DRIVER StartType = 3 ; SERVICE_DEMAND_START ErrorControl = 1 ; SERVICE_ERROR_NORMAL ServiceBinary = %10%\System32\Drivers\CYUSB.SYS LoadOrderGroup = Base [Strings] PROVIDER="Cypress" MFGNAME="Cypress Semiconductor" CYUSB_INSTALL="Cypress Installation Disk" VID_04b4&PID_1002.DeviceDesc="Cypresss PSoC 3 and PSoC 5 USB BULK Loopback example project." ; VID/PID combination programmed in PSoC 3 and PSoC 5 ; firmware ; To do ; replace "Cypress..." string with your own ; meaningful text ; replace the XXXX with your unique VID ; replace the YYYY with your unique PID CYUSB.SvcDesc="Cypress USB Device" CYUSB.GUID="AE18AA60-7F6A-11d4-97DD B959" ; Replace GUID with your own unique GUID June 13, 2011 Document No Rev *E 14

15 Appendix 3: main.c for Project 2 #include <device.h> uint8 MyChannel; uint8 MYTD; int STARTbit = 0; uint8 FINISHED = 0 ; extern uint16 RegAddHi; extern T_USBFS_1_EP_CTL_BLOCK USBFS_1_EP[]; void main() CYGlobalIntEnable; /*Enable Global Interrupts*/ PWM_1_Start(); ADC_DelSig_1_Start(); ADC_DelSig_1_StartConvert(); ADC_DelSig_1_IsEndConversion(ADC_DelSig_1_WAIT_FOR_RESULT); USBFS_1_Start(0, USBFS_1_3V_OPERATION); while(!usbfs_1_bgetconfiguration()); MyDmaDone_Start(); #if (defined( C51 )) MyChannel = MyDMA_DmaInitialize(1,0,0,0); #else /* PSoC 5 */ MyChannel = MyDMA_DmaInitialize(1, 0, RegAddHi, HI16(CYDEV_USB_ARB_RW1_DR)); #endif MYTD = CyDmaTdAllocate(); /* Get a TD*/ CyDmaTdSetConfiguration(MYTD,64,DMA_INVALID_TD, MyDMA TD_TERMOUT_EN ); /* Set TD to transfer 64 bytes */ /* Associate the TD with the channel. */ CyDmaChSetInitialTd(MyChannel, MYTD); /* Enable the channel */ CyDmaChEnable(MyChannel, 1); while(1) if(startbit == 1) /*We are implementing the transfer in register level since the endpoint data register is configured as the DMA destination. We directly use the APIs (which are simpler to use) if we leave out the DMA in between. Refer to the PSoC3 Register TRM for a detailed description of these registers.*/ /* load the write address pointer of the endpoint into the USBFS_ARB_RW1_WA registers */ CY_SET_REG8(&USBFS_1_ARB_RW1_WA_PTR[0], USBFS_1_EP[1].buffOffset & 0xFFu); CY_SET_REG8(&USBFS_1_ARB_RW1_WA_MSB_PTR[0], (USBFS_1_EP[1].buffOffset >> 8u)); /* Request DMA action. */ CyDmaChSetRequest(MyChannel, CPU_REQ); /* Set the count and data toggle */ CY_SET_REG8(&USBFS_1_SIE_EP1_CNT0_PTR[0], (0x40 >> 8u) (USBFS_1_EP[1].epToggle)); /* count is 64 */ CY_SET_REG8(&USBFS_1_SIE_EP1_CNT1_PTR[0], 0x40 & 0xFFu); /* load the read address pointer of the endpoint into the USBFS_ARB_RW1_RA registers */ CY_SET_REG8(&USBFS_1_ARB_RW1_RA_PTR[0], USBFS_1_EP[1].buffOffset & 0xFFu); CY_SET_REG8(&USBFS_1_ARB_RW1_RA_MSB_PTR[0], (USBFS_1_EP[1].buffOffset >> 8u)); USBFS_1_EP[1].apiEpState = USBFS_1_NO_EVENT_PENDING; /* Write the Mode register */ CY_SET_REG8(&USBFS_1_SIE_EP1_CR0_PTR[0], USBFS_1_EP[1].epMode); while(!finished); /* Wait for DMA done interrupt*/ FINISHED=0; /* [] END OF FILE */ June 13, 2011 Document No Rev *E 15

16 Appendix 4: USBFS_1_vnd.c for Project 2 Add the custom declarations to the VENDOR_SPECIFIC_DECLARATIONS section: /******************************************************************************* * Vendor Specific Declarations ********************************************************************************/ /* `#START VENDOR_SPECIFIC_DECLARATIONS` Place your declaration here */ #include "device.h" #include "CyDmac.h" #define StartStream 0xA1 #define ChangeDC 0xB1 #define StopStream 0xE1 extern int STARTbit; extern uint8 MYTD; extern T_USBFS_1_TD CurrentTD; extern int MyChannel; extern uint8 FINISHED; uint8 pdc, CmpVal; uint16 RegAddHi = 0x4000; uint16 RegAddLo; uint8 USBFS_1_InitNoDataControlTransfer(void); /* `#END` */ Now add the custom vendor command code to the USBFS_1_HandleVendorRqst() function: /* `#START VENDOR_SPECIFIC_CODE` Place your vendor specific request here */ switch (CY_GET_REG8(USBFS_1_bRequest)) case StartStream: RegAddHi = CY_GET_REG16(USBFS_1_wValue); // Read the upper 16 bits from the wvalue field of setup packet RegAddLo = CY_GET_REG16(USBFS_1_wIndex); //Read the lower 16 bits from the windex field of setup packet #if (defined( C51 )) /* PSoC3 CyDmaTdSetAddress(MYTD, RegAddLo, CYDEV_USB_ARB_RW1_DR); #else/* PSoC5 MyChannel = MyDMA_DmaInitialize(1, 0, RegAddHi, HI16(USBFS_1_ARB_RW1_DR)); CyDmaTdSetAddress(MYTD, RegAddLo,LO16(CYDEV_USB_ARB_RW1_DR)); /* Associate the TD with the channel. */ CyDmaChSetInitialTd(MyChannel, MYTD); //enable the channel CyDmaChEnable(MyChannel, 1); #endif requesthandled = USBFS_1_InitNoDataControlTransfer(); STARTbit =1; break; case ChangeDC: pdc = CY_GET_REG8(USBFS_1_wValueLo); //Read the desired dutycycle value from wvalue field CmpVal = pdc*0.01*255; PWM_1_WriteCompare(CmpVal); requesthandled = USBFS_1_InitNoDataControlTransfer(); break; case StopStream: STARTbit=0; //stop streaming requesthandled = USBFS_1_InitNoDataControlTransfer(); break; /* `#END` */ June 13, 2011 Document No Rev *E 16

17 Appendix 5: isr_1 for Project 2 /******************************************************************************* * Place your includes, defines and code here ********************************************************************************/ /* `#START MyDmaDone_intc` */ extern uint8 FINISHED; /* `#END` */ /******************************************************************************* * Function Name: MyDmaDone_Interrupt ******************************************************************************** * Summary: * The default Interrupt Service Routine for MyDmaDone. * * Add custom code between the coments to keep the next version of this file * from over writting your code. * * Parameters: * * Return: * void. * *******************************************************************************/ CY_ISR(MyDmaDone_Interrupt) /* Place your Interrupt code here. */ /* `#START MyDmaDone_Interrupt` */ FINISHED=1; /* `#END` */ June 13, 2011 Document No Rev *E 17

18 Appendix 6: cyusb.inf for Project 2 [Version] Signature="$CHICAGO$" Class=USB ClassGUID= 36FC9E60-C465-11CF provider=%cypress% ; ---Uncomment and complete below to support WHQL submission---; ;CatalogFile= ;DriverVer=mm/dd/yyyy,x.y.v.z ; [Manufacturer] %MfgName%=Cypress [Cypress] %VID_04b4&PID_1122.DeviceDesc%=CYUSB, USB\VID_04b4&PID_1122 ; This entry contains the VID/PID in the ; PSoC 3 firmware ; to do ; replace 04b4 (x2) with your unique VID ; replace 1122 (x2) with your unique PID [DestinationDirs] CYUSB.Files = 10, System32\Drivers [CYUSB.Files] CYUSB.SYS [CYUSB.NT] CopyFiles=CYUSB.Files AddReg=CYUSB.AddReg [CYUSB.NT.HW] AddReg=CYUSB.AddReg.Guid [CYUSB.NT.Services] Addservice = CYUSB, 0x , CYUSB.AddService [CYUSB.AddReg] HKR,,DevLoader,,*ntkern HKR,,NTMPDriver,,CyUsb.sys [CYUSB.AddReg.Guid] HKR,,DriverGUID,,%CYUSB.GUID% ;======================================= [CYUSB.AddService] DisplayName = %CYUSB.SvcDesc% ServiceType = 1 ; SERVICE_KERNEL_DRIVER StartType = 3 ; SERVICE_DEMAND_START ErrorControl = 1 ; SERVICE_ERROR_NORMAL ServiceBinary = %10%\System32\Drivers\CYUSB.SYS LoadOrderGroup = Base [Strings] PROVIDER="Cypress" MFGNAME="Cypress Semiconductor" CYUSB_INSTALL="Cypress Installation Disk" VID_04b4&PID_1122.DeviceDesc="Cypresss PSoC 3 USB Control example project." ; VID/PID combination programmed in PSoC 3 ; firmware ; To do ; replace "Cypress..." string with your own ; meaningful text ; replace the XXXX with your unique VID ; replace the YYYY with your unique PID CYUSB.SvcDesc="Cypress USB Device" June 13, 2011 Document No Rev *E 18

19 Document History Document Title: PSoC 3 / PSoC 5 USB Vendor-Specific Device AN56377 Document Number: Revision ECN Orig. of Change Submission Date Description of Change ** BHA/HRID 11/18/2009 New application note *A HRID 08/19/2010 Updated with PSoC 5 *B HRID 11/23/2010 The Code Font size has been changed in page 6, 7, 8,9,10 and 11. *C RLRM 04/11/2011 The application note has been extensively updated. The projects have also been updated. The project from AN57294 is also merged into this application note. *D RLRM 05/06/2011 Updated Figure 1, 2, 3, 4, and 23 *E RLRM 06/13/2011 Broken links fixed and document formatted as per template. PSoC is a registered trademark of Cypress Semiconductor Corp. PSoC Designer and PSoC Creator are trademarks of Cypress Semiconductor Corp. All other trademarks or registered trademarks referenced herein are the property of their respective owners. Cypress Semiconductor 198 Champion Court San Jose, CA Phone: Fax: Cypress Semiconductor Corporation, 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. This 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 life-support 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. June 13, 2011 Document No Rev *E 19