Troubleshooting PSoC® 3, PSoC 4 L-Series, and PSoC 5LP USB Designs - KBA210620

Version: *A

 

Answer:

This guide provides troubleshooting steps for common issues that can occur in your USB designs based on PSoC 3, PSoC 4 L-series, and PSoC 5LP families. If you are new to USB in PSoC family devices, get started with AN57294 - USB 101: An Introduction to Universal Serial Bus 2.0

1. USB Enumeration Issues 

Symptom: The USB device is not shown in the Device Manager after you plug the board to a USB Host such as a PC.

  • USB subsection hardware not designed properly: Check the USB hardware port connection on the board as follows:   
        
    • Ensure that 22-Ω resistors are connected in series to the D+ and D- lines.
    •   
    • Ensure that the D+ and D- lines are not reversed.
    •   
    • Ensure that VDD is not less than 3.3 V. The USB block cannot operate if the VDD supply is below this voltage. See the device datasheet for the exact voltage specification.
    •   
    • When the USB Component is started in firmware by calling the USBFS_Start() API, it pulls the D+ line HIGH. For Full Speed devices, the internal pull-up of the USB device is 1.5 kΩ, and pull-down on the Host side is 15 kΩ. Therefore, the voltage level on the D+ line when the device is plugged into a USB port and the USB Component in firmware is started should be close to VDD. If this behavior is not observed, it indicates a hardware issue on the board.
    •   
    • In case of PSoC4L designs 0.1uF capacitor needs to be added between VBUS line and Ground.
    •  
      

    For testing, use the code example USBFS_HID available with PSoC Creator. Program the PSoC device with the HID code example and check if the mouse pointer is moving. HID does not need any special drivers, so the project should work automatically. If not, the issue is with the USB port connectivity.

  • Supply voltage is not configured properly in the firmware: Check the voltage provided as a parameter in the USBFS_Start(uint8 device,uint8 mode) API function. If the board is powered with a 5-V supply, the argument mode must be assigned as USBFS_5V_OPERATION. In this case, the internal regulator is enabled. If the board power supply is 3 V, the macro USBFS_3V_OPERATION must be used. If the supply voltage is unknown, it is better to use USBFS_5V_OPERATION because in this case the internal regulator is enabled.
  • Descriptors not configured properly: If the project is working, it indicates that there are issues with the descriptor configurations. Make sure that the USB device is configured properly in the Component Configuration window in PSoC Creator.
  • Global Interrupts not enabled: Make sure that you have enabled global interrupts by using the CYGlobalIntEnable API macro before starting the USBFS Component.
  • Unplug- Replug events not handled: If the board is self-powered (not powered from the USB port), firmware is always running regardless of whether the board is plugged to the USB port of the Host. If firmware does not have a way to detect unplug and re-plug events, it does not restart the USB Component, and therefore, enumeration is not done. When the board is self-powered, you should monitor the VBUS line of the USB port to detect USB plugging/unplugging and thus take care of the enumeration of the USB device. Monitor the VBUS line by using any Digital Input pin externally connected to the VBUS line of the USB bus. Code 1 shows how to handle plug-unplug events. 
            

    uint8 USB_Started_Flag ;
       for (;;) 
       {
           if (VBUS_MONITOR_PIN_Read() == 0)
           {
               USBFS_Stop();
               USB_Started_Flag = 0; 
           }
           else if (USB_Started_Flag == 0 )
           {
               USBFS_Start(device, USBFS_3V_OPERATION ); 
           } /* User Application Code */

Code 1. Pseudocode to Detect Connect-Disconnect Events

2. Driver Binding Issues 

Symptom: You get an error message that your device driver is not installed

  • PID mismatch in the .inf file: If the PID of the device does not match the PIDs defined in the INF file of the driver installed, edit the INF file
     
      For generic USB devices, the INF file to be used is cyusb.inf if you have installed Cypress Suite USB, or cyusb3.inf if you have installed EZ-USB FX3 SDK. Locate the INF file based on the driver suite that you have installed. In these .inf files, VID 0x04B4 and a list of PIDs are listed. If you are using any of these PIDs and the Cypress VID 0x4B4, you can point to this .inf file. If you are using another PID that is not present in the .inf file, you cannot to point to this .inf file. In this case, you should modify the .inf file. 
     
      Open the .inf file and add a line in the “Device” section corresponding to the OS, with the new PID, similar to the existing VID and PID details. Similarly, add another line in the “Strings” section, similar to the existing lines in the section, but with the new VID and PID.
     
      See “Appendix E: Adding Custom VID and PID to the .inf file” section in the document AN65209 - Getting Started with FX2LP for an example of editing the cyusb.inf file for a custom PID.
     
      IMPORTANT: Note the following: 
     
      Changing the .inf file causes the driver signature to be lost. In the final product, the driver must be signed. Some operating systems do not allow installing drivers that are unsigned. If driver signature enforcement is disabled during bootup, this issue does not occur.
     
      To troubleshoot your designs, you can disable Driver Signature Enforcement. On Windows 7, do the following:  
        
    • During bootup, press F8
    •   
    • From the list of options that appears, select “Disable driver signature enforcement”.
    •  

3. Issues When PSoC Configured as USBUART 

Symptom: You have configured USB in the PSoC device as a CDC device; it has not enumerated as a COM port. 

  • If the USBUART Component is used, a separate .inf (USBUART_cdc.inf) file is generated in the Generated Source folder. This .inf points to the Windows serial driver. For proper enumeration of a USBUART device, you need to point to this file from Device Manager.   
        
    • Open Device Manager and right-click on the device, and select Update Driver Software.
    •   
    • Choose Browse my computer for driver software > Let me pick from a list of device drivers on my computer > Have Disk.
    •   
    • Navigate to the project folder and select …/Generated_Source//USBUART_cdc.inf.
    •   
    • Click Next to point to the .inf file.
    •  
  • If there are multiple interfaces in the same device, you should have the Interface Association Descriptor. See the “Compound and Composite Devices” section in the application note AN58726 - USB HID Intermediate with PSoC® 3 and PSoC 5LP

4. Firmware Issues with Endpoint Configurations 

Symptom: The device enumerates properly but IN/OUT data transfer does not happen as expected. 

  • Transferring data before enumeration: The data transfer should be implemented only after completion of the enumeration process. The firmware must wait until the USBFS_GetConfiguration() API function returns a non-zero value. The following pseudocode demonstrates this. 
         

    USBFS_Start(USBFS_DEVICE, USBFS_5V_OPERATION);
       while (0u == USBFS_GetConfiguration());

      

    Code 2: Pseudocode for Waiting Until the Device Is Enumerated 

  • DMA with automatic memory mode usage: If you are using DMA with automatic memory management, initially you should register the IN data buffer and out data buffer with the endpoint (EP) number, buffer pointer, and length. You must call the following API functions after the configuration is set by the Host.
         

    USBFS_LoadInEP(IN_EP,&BufferIn[0],64);
       USBFS_ReadOutEP(OUT_EP,&BufferOut[0],64);

      

    Code 3: Pseudocode for IN and OUT EP Initialization

     
     
      These functions do not initiate any data transfer. Now, for actual IN transfer, call the USBFS_LoadInEP() API function with the data pointer as ‘NULL’. In OUT transfers, you do not need to call any API functions. The OUT data is saved to the buffer automatically. To receive data further, you must re-enable the OUT EP by calling the USBFS_EnableOutEP() API function. 
         

    USBFS_LoadInEP(IN_EP,NULL,64);     //IN EP reading data
       USBFS_EnableOutEP(OUT_EP);     //Clearing OUT EP after reading OUT data  

      

    Code 4: Function Usage in DMA with Automatic Memory Management Mode

     
     
      For more details, see the project “Project 3: Increasing USB Throughput with DMA” in AN56377 - PSoC 3 and PSoC 5LP - Introduction to Implementing USB Data Transfers
  • Handling multiple requests from Windows 7 OS host: The Windows 7 OS may send double SET_CONFIGURATION requests with the same configuration number. In this case, user-level code should re-enable OUT endpoints after each request. 
     
      Call the USBFS_IsConfigurationChanged( ) API function to detect configuration changes from the PC. If it returns a nonzero value, the USBFS_GetConfiguration() API function is called to get the configuration number. The usage model for this is shown in Code 5: 
         

    if(USBFS_IsConfigurationChanged() != 0)
       {
           if(USBFS_GetConfiguration() != 0)
           {
               USBFS_EnableOutEP(OUT_EP);
           }
       } 

      

    Code 5 : Pseudocode for Usage Model in Main Loop

  • Handling data packets of size maximum payload: Issues may occur if you are sending data packets of maximum payload size. Windows OS needs a short packet as an indication that data transfer is complete. If not, it does not consider the whole transfer as complete. See KBA89052 for more details.
  • Toggle Error: The USB hardware receives OUT packet without checking for data toggle error (received packet data toggle bit is the same as i n previous packet).The firmware should take care of the toggle bit error checking. 

5. USB Analyzers 

Analyzing USB packets using USB analyzers is helpful in identifying the exact step where issues occur. In the case of enumeration or usual data transfer issues, checking USB packets tells you where exactly the issue is.

An analyzer throws errors if there is any violation in the USB protocol. The analyzer groups the data packets based on the USB transfer type. Figure 1 shows a typical USB packet during enumeration. 

Figure 1: USB HID Device Enumeration Captured by Beagle USB480

See application note AN57294: USB 101: An Introduction to Universal Serial Bus 2.0 ; Section 12: USB Enumeration and Configuration and Section 13: Debugging the Communication for more details on the enumeration procedure and USB Analyzers respectively.