1.. _i2c_api:
2
3Inter-Integrated Circuit (I2C) Bus
4##################################
5
6Overview
7********
8
9.. note::
10
11   The terminology used in Zephyr I2C APIs follows that of the
12   `NXP I2C Bus Specification Rev 7.0 <i2c-specification_>`_. These changed
13   from previous revisions as of its release October 1, 2021.
14
15`I2C`_ (Inter-Integrated Circuit, pronounced "eye
16squared see") is a commonly-used two-signal shared peripheral interface
17bus.  Many system-on-chip solutions provide controllers that communicate
18on an I2C bus.  Devices on the bus can operate in two roles: as a
19"controller" that initiates transactions and controls the clock, or as a
20"target" that responds to transaction commands.  A I2C controller on a
21given SoC will generally support the controller role, and some will also
22support the target mode.  Zephyr has API for both roles.
23
24.. _i2c-controller-api:
25
26I2C Controller API
27==================
28
29Zephyr's I2C controller API is used when an I2C peripheral controls the bus,
30in particularly the start and stop conditions and the clock.  This is
31the most common mode, used to interact with I2C devices like sensors and
32serial memory.
33
34This API is supported in all in-tree I2C peripheral drivers and is
35considered stable.
36
37.. _i2c-target-api:
38
39I2C Target API
40==============
41
42Zephyr's I2C target API is used when an I2C peripheral responds to
43transactions initiated by a different controller on the bus.  It might
44be used for a Zephyr application with transducer roles that are
45controlled by another device such as a host processor.
46
47This API is supported in very few in-tree I2C peripheral drivers.  The
48API is considered experimental, as it is not compatible with the
49capabilities of all I2C peripherals supported in controller mode.
50
51
52Configuration Options
53*********************
54
55Related configuration options:
56
57* :kconfig:option:`CONFIG_I2C`
58
59API Reference
60*************
61
62.. doxygengroup:: i2c_interface
63
64.. _i2c-specification:
65   https://www.nxp.com/docs/en/user-guide/UM10204.pdf
66
67.. _I2C: i2c-specification_
68