i2c
===
Probes the I2C device.

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

   * - Name
     - Type
     - Description

   * - bus_number
     - str, None
     - (optional; default: ``None``) The I2C bus number. Every bus will be scanned if it is not assigned. If the bus is behind EC, then it should have "EC-" prefix. For example: "EC-0"

   * - bus_path
     - str, None
     - (optional; default: ``None``) The realpath of the I2C bus sysfs node. Ignored if `bus_number` argument is given.

   * - bus_name
     - str, None
     - (optional; default: ``None``) The name of the I2C bus sysfs node. Ignored if `bus_number` argument is given.

   * - addr
     - str, None
     - (optional; default: ``None``) The address of the device. Every address between 0x03 and 0x77 will be scanned if it is not assigned.

   * - use_r_flag
     - bool
     - (optional; default: ``False``) Use SMBus "read byte" commands for probing.

Description
-----------
This function probes a specific bus/address to check whether an I2C device
is connected there or not.

The probed result for a single I2C device is a dictionary which contains
at least two entries, one is ``bus_number`` and the other one is ``addr``.

Examples
--------
Let's say we've already known that the address of I2C camera X is 0x24 but
we don't know which bus that camera is connected.  A not 100% reliable way
to verify whether camera X is installed or not on the device is to write
the probe statement ::

  {
    "eval": {
      "i2c": {
        "addr": "0x24"
      }
    }
  }

The function will try to probe ``address 0x24`` on all I2C buses.  If camera
X is found at bus 2, we will have below probed results::

  [
    {
      "addr": "0x24",
      "bus_number": "2"
    }
  ]

Otherwise the probed results might be just an empty list.  Howerver, it's
possible that another I2C device has the address number ``0x24`` on another
bus too.  In this case, the probe statement above will lead to a false
positive result.