usb
===
Probes all usb devices listed in the sysfs ``/sys/bus/usb/devices/``.

Function Arguments
------------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - dir_path
     - str, None
     - (optional; default: ``None``) The path used to search for device sysfs data. First all symlinks are resolved, to the the "real" path. Then iteratively search toward parent folder until the remaining path contains the relevent data fields.

Description
-----------
This function goes through ``/sys/bus/usb/devices/`` to read attributes of
each usb device (also includes usb root hub) listed there.  Each result
should contain these fields:

- ``device_path``: Pathname of the sysfs directory.
- ``idVendor``
- ``idProduct``

The result might also contain these optional fields if they are exported in
the sysfs entry:

- ``manufacturer``
- ``product``
- ``bcdDevice``

Examples
--------
Let's say the Chromebook has two usb devices.  One of which
(at ``/sys/bus/usb/devices/1-1``) has the attributes:

- ``idVendor=0x0123``
- ``idProduct=0x4567``
- ``manufacturer=Google``
- ``product=Google Fancy Camera``
- ``bcdDevice=0x8901``

And the other one (at ``/sys/bus/usb/devices/1-2``) has the attributes:

- ``idVendor=0x0246``
- ``idProduct=0x1357``
- ``product=Goofy Bluetooth``

Then the probe statement::

  {
    "eval": "usb"
  }

will have the corresponding probed result::

  [
    {
      "bus_type": "usb",
      "idVendor": "0123",
      "idProduct": "4567",
      "manufacturer": "Google",
      "product": "Google Fancy Camera",
      "bcdDevice": "8901"
    },
    {
      "bus_type": "usb",
      "idVendor": "0246",
      "idProduct": "1357",
      "product": "Goofy Bluetooth"
    }
  ]

To verify if the Chromebook has Google Fancy Camera or not, you can write
a probe statement like::

  {
    "eval": "usb",
    "expect": {
      "idVendor": "0123",
      "idProduct": "4567"
    }
  }

and verify if the ``camera`` field of the probed result dict contains
elements or not.

You can also specify ``dir_path`` argument directly to ask the function
to probe that sysfs USB entry.  For example, the probe statement ::

  {
    "eval": "usb:/sys/bus/usb/devices/1-1"
  }

will have the corresponding probed results::

  [
    {
      "bus_type": "usb",
      "idVendor": "0123",
      ...
    }
  ]