Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 2782
Joined: Thu Jul 11, 2013 2:37 pm

STICKY: USB device not working on Raspberry Pi Zero, 1, 2, 3? Click here!

Sun Aug 25, 2013 8:34 pm

Is your USB device not working with the Raspberry Pi? This sticky should help you.

USB support on Raspberry Pi models that use BCM2835/6/7 differs from the level of support found on PC hardware. It is provided by an On-The-Go host controller: this is more usually found as the USB charging/PC connectivity port on a mobile phone or as the single USB port that supports a flash drive on a TV/media box. While the hardware on these models is technically capable of implementing all USB2.0 and USB1.1 features, there are some known limitations.

USB devices aren't all created equal either. There are many devices out there that don't quite meet the respective USB specification. While they may work reasonably well with a PC, if they have non-compliant behaviour they are more likely to have problems when plugged into a Raspberry Pi. Several of the misbehaving devices have been caught in the wild and workarounds are possible.

More background information is available on the site documentation page: https://www.raspberrypi.org/documentati ... /README.md

Debugging problems yourself
  1. Are you up to date?
    You should use sudo apt-get update && sudo apt-get upgrade to get the latest firmware and kernel that will contain many patches not present in the default installs of Raspbian. If you are using a different distro on the Pi, then you should check around the distro's website or guides to see how to update it.
  2. Does it enumerate?
    If a device doesn't work, then the first step is to see if it is detected at all. There are two commands that can be entered into a terminal for this: lsusb and dmesg. The first will print out all devices attached to USB, whether they are actually recognised or not, and the second will print out the kernel message buffer (which can be quite big after booting: try doing sudo dmesg -C then plug in your device and retype dmesg to see new messages).

    As an example with a USB pendrive:

    Code: Select all

    pi@raspberrypi ~ $ lsusb
    Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp.
    Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
    Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp.
    Bus 001 Device 005: ID 05dc:a781 Lexar Media, Inc.
    pi@raspberrypi ~ $ dmesg
    ... Stuff that happened before ...
    [ 8904.228539] usb 1-1.3: new high-speed USB device number 5 using dwc_otg
    [ 8904.332308] usb 1-1.3: New USB device found, idVendor=05dc, idProduct=a781
    [ 8904.332347] usb 1-1.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
    [ 8904.332368] usb 1-1.3: Product: JD Firefly
    [ 8904.332386] usb 1-1.3: Manufacturer: Lexar
    [ 8904.332403] usb 1-1.3: SerialNumber: AACU6B4JZVH31337
    [ 8904.336583] usb-storage 1-1.3:1.0: USB Mass Storage device detected
    [ 8904.337483] scsi1 : usb-storage 1-1.3:1.0
    [ 8908.114261] scsi 1:0:0:0: Direct-Access     Lexar    JD Firefly       0100 PQ: 0 ANSI: 0 CCS
    [ 8908.185048] sd 1:0:0:0: [sda] 4048896 512-byte logical blocks: (2.07 GB/1.93 GiB)
    [ 8908.186152] sd 1:0:0:0: [sda] Write Protect is off
    [ 8908.186194] sd 1:0:0:0: [sda] Mode Sense: 43 00 00 00
    [ 8908.187274] sd 1:0:0:0: [sda] No Caching mode page present
    [ 8908.187312] sd 1:0:0:0: [sda] Assuming drive cache: write through
    [ 8908.205534] sd 1:0:0:0: [sda] No Caching mode page present
    [ 8908.205577] sd 1:0:0:0: [sda] Assuming drive cache: write through
    [ 8908.207226]  sda: sda1
    [ 8908.213652] sd 1:0:0:0: [sda] No Caching mode page present
    [ 8908.213697] sd 1:0:0:0: [sda] Assuming drive cache: write through
    [ 8908.213724] sd 1:0:0:0: [sda] Attached SCSI removable disk
    In this case, there are no error messages in dmesg and the pendrive is detected by usb-storage. If your device did not have a driver available, then typically only the first 6 new lines will appear in the dmesg printout.

    If there are errors with enumeration, then there are a few usual suspects:
    1. Power
      Several models of Raspberry Pi have limitations on the amount of downstream power available to USB devices. See here for further details: https://www.raspberrypi.org/documentati ... owerlimits
      You should use a good-quality powered hub when using these devices: some devices may advertise that they use lower power than they actually do, especially things like wireless LAN dongles and USB HDDs. Also, some hub power supplies advertise that they give out much more power than they actually can. Be sure to check your USB device with an alternative source of power: if you continue to receive the same result, you can rule power out as a cause of the issue.
    2. Number of hubs
      There is a limit to the number of cascaded hubs you can use with the Raspberry Pi. If your device refuses to work when used with a multi-port hub, then use lsusb -t to display a "tree" of which devices physically connect to what. There is always at least 1 hub in a model B: the ethernet chip is actually a 3-port hub and a USB ethernet device.

      Code: Select all

      	/:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=dwc_otg/1p, 480M
          |__ Port 1: Dev 2, If 0, Class=hub, Driver=hub/3p, 480M
              |__ Port 1: Dev 3, If 0, Class=vend., Driver=smsc95xx, 480M
              |__ Port 3: Dev 5, If 0, Class=stor., Driver=usb-storage, 480M

      Some hubs are very cheaply built. They will combine two smaller (usually 4-port) hub chips into a single package to make a 7 or 10 port hub, which will show up as an additional step in the tree. This can mean that devices only work in some of the hub's ports, usually the first few that are only connected via 1 hub chip. BCM283x SoCs will support a cascade of 3 USB2.0 compliant hub chips, including the hub inside the Ethernet port. Move devices around to see if they work in any of the other hub ports.
  3. No drivers?
    If a device enumerates without any errors, but doesn't appear to do anything, then it is likely there are no drivers installed for it. Search around based on the manufacturer's name for the device or the USB IDs that are displayed in lsusb (e.g. 05dc:a781). The device may not be supported with default Linux drivers, and you may need to download or compile your own third-party software.
  4. Poor performance, but no errors in dmesg
    First, be sure that it is actually the USB device itself which is causing the problem. Doing other activity such as other wireless devices using the same network, other devices using the USB bus may impact performance. Try to replicate the problem with a minimum number of other devices plugged in.
    Some devices can become flakey after a while because they heat up. For example, wireless LAN dongles can become quite warm if in constant use: try unplugging the device, leave it for a few minutes and plug back in. Does it still exhibit the same behaviour?
  5. Device disconnects or continually reconnects
    This again is usually caused by problems with power, so double-check your supply. If it's not power, then it can also be a symptom of getting too many errors from the device which causes Linux to reset the device. Try moving the device to a different hub port as described above.
Asking for help
The chances are that someone else already has your device and has posted on the forum about it. Do a search, or even a google search.

If you're going to post about an issue with a device, then provide all the information that will be useful. Describe the setup: include in your post the entire output of lsusb -v, dmesg and uname -a. Good problem reports give lengthy but precise information as to what you did, what you expected, and what actually happened.

General information
  • There is a single USB root port on the Raspberry Pi.
    This means that the USB2.0 bus bandwidth of 480mbps is shared between all attached devices. If you are using multiple high-bandwidth devices at once, then it is possible that some may go slower. The Pi's driver implements a quality-of-service mechanism for more time-critical information than e.g. traffic to and from an attached USB HDD or the SMSC 9512 ethernet controller.
  • There is a soft limit to the number of devices active at once.
    Due to the way the Raspberry Pi hardware works, there is a maximum of 8 simultaneously active USB transactions. This is less of a limitation than it first appears: the driver will make near-optimal use of each of the 8 channels which means that in many cases you can have more than 8 devices plugged in at once, and use them, because once one device has finished its task then the channel used is free to do other work. In many cases with multiple devices in use, you will be limited by the overall bandwidth of USB2.0 rather than the number of host channels. Devices that hog channels for long periods of time may suffer slowdown, however.
  • Higher-level parts of the USB protocol are implemented in software.
    The On-the-Go hardware has simpler support for USB than the typical hardware found in PCs. To make up for this, the dwc_otg USB driver has to perform more software processing than an equivalent ehci USB driver. This is of particular importance where split transactions, which communicate with USB1.1 devices on the USB2.0 bus, are used. The work to make this software as efficient and as fast as possible is ongoing: see the points about the FIQ implementation.
  • The FIQ (fast interrupt)
    The existing driver is vulnerable to interrupt latency created by other parts of the Linux kernel taking a long time to do things with interrupts disabled. To make the dwc_otg driver less vulnerable to being disturbed by other activity in the Linux kernel, we have implemented a FIQ (fast interrupt) that uses the priority mechanism of the ARM CPU to ensure that certain types of USB transactions, namely "split" transactions between a USB1.1 device and a USB2.0 bus, get completed reliably. This solves the majority of issues with missing keypresses on keyboards, for example. There are some limitations with the current implementation, see the "Known Issues" section.

Known issues:
  • Hubs can only be chained to a certain depth.
    There is a maximum of four cascaded USB2.0 hubs that can be operated between a USB device and the Pi's root port. USB1.1 devices should work with a maximum of four hubs.
  • High-speed high-bandwidth Isochronous is subject to data loss.
    Typical symptoms include corrupted video from webcams that transmit uncompressed data, and corruption on HD video streams from DVB dongles.
    This is mainly due to interrupt latency preventing isochronous packets from being requested (or transmitted) at the desired rate by the USB core. Isochronous is also particularly demanding of the dwc_otg driver, which may cause less responsiveness when lots of isochronous traffic is active.
  • Split transactions that span multiple packets are disrupted
    Typical symptoms are static in the background of audio recordings or sound output.
    Audio playback or record requires a multi-step split transcation, which must be precisely scheduled and completed in the right order and at the right time. If the USB driver misses sending a split transaction packet, then the data is usually lost. The greater the bitrate or number of audio channels used, the greater the corruption of the signal. Adding to the interrupt loading of the Pi through use of the SD card or ethernet will increase the static.
  • Single-TT hubs perform very badly with multiple USB1.1 devices plugged in.
    Hubs have a mechanism to separate low- and full-speed devices from USB2.0 high-speed devices. This is called a transaction translator - which is responsible for performing the USB1.1-speed transactions. There are two options for implementing a hub - one with a single TT for all ports (the "cheap" option), and one TT per port. If multiple USB1.1 devices are plugged into a hub with a single TT, then all these devices must be talked to through this TT. The FIQ enforces a one-at-a-time rule whan talking to a device behind a TT. Exclusive access to a transaction translator means that for hubs with only 1 TT there is a limit on the number of devices that can be used at any one time, or scheduling conflicts cause lost packets. USB audio is particularly vulnerable when sharing a TT with other USB1.1 devices. The use of multi-TT hubs is strongly recommended - you can get this information from a lsusb -v | less and scrolling through to the listing for the external hub.
  • As an advanced trick for audio devices, try removing the HID endpoint that many of these use (for vol up/down, mute etc) by unbinding the usb-hid driver from the device. See this Ubuntu forum post: http://ubuntuforums.org/showthread.php? ... ost8512485 - you will need to adapt it for your needs.
  • Use reduced resolution settings on webcams or video streaming devices to reduce corruption. Alternatively, switched to compressed MJPEG data streams if possible.
  • For devices that otherwise refuse to work, the "nuclear option" is to put dwc_otg.speed=1 into /boot/cmdline.txt. This will drop the bus speed to 12Mbps - USB1.1 speeds. Ethernet will be extremely slow with this option enabled.
Rockets are loud.

Return to “Troubleshooting”