====== Scan for USB devices ======

===== Synopsis =====

    usbscan <setting>

===== Examples =====

=== Scan for all USB devices ===

    #!ipxe
    :scan usbscan addr || goto scan_done
      echo Found USB device ${addr:hex}
      goto scan
    :scan_done

===== Description =====

Scan the USB bus, starting from the USB bus:dev address in the specified setting, and store the USB bus:dev address of the next device in the specified setting.  If the specified setting is empty, then the scan will start from the first USB device.

If no further USB devices exist, the command will fail silently with an error status.

===== Command status =====

^ Success   | A USB device was found, and the bus:dev address was stored in the setting     |
^ Failure   | No further USB devices were found                                             |

===== See also =====

  * ''[[:cmd:ifstat]]''
  * ''[[:cmd:goto]]''
  * [[:cfg|List of all iPXE settings]]
  * [[:cmd|List of all iPXE commands]]

===== Build options =====

This command is available only when the build option ''[[:buildcfg:USB_CMD]]'' is enabled.

===== Notes =====

You can use the USB bus:dev address to extract information from the USB device and string descriptors.  For example, to list the vendor and device IDs and the product name of all USB devices:

    #!ipxe
    :scan usbscan addr || goto scan_done
      echo ${addr:hex}: ${usb/${addr}.8.2}:${usb/${addr}.10.2} ${usb/${addr}.15.0}
      goto scan
    :scan_done

The ''usbscan'' command requires the use of iPXE's native USB host controller drivers.  It is will not work if you have explicitly enabled the (obscure) build option ''[[:buildcfg:USB_HCD_USBIO]]''.