Expand description
Interface for the I2C peripheral.
The Broadcom Serial Controller (BSC) peripheral controls a proprietary bus
compliant with the I2C bus/interface. RPPAL communicates with the BSC
using the i2cdev device interface.
I2C buses
The Raspberry Pi 3 B+ and earlier models support three hardware I2C buses, however only the I2C bus on physical pins 3 and 5 should be used to communicate with slave devices. The other two buses are used internally as an HDMI interface, and for HAT identification.
On the Raspberry Pi 4 B, 400 and 5, three additional I2C buses are available, depending on your configuration, as explained below.
I2C0 / I2C1
On the Raspberry Pi B Rev 1, physical pins 3 (SDA) and 5 (SCL) are tied to I2C0. On every other Raspberry Pi model, they’re connected to I2C1.
The I2C bus connected to these pins is disabled by
default. You can enable it through sudo raspi-config, or by manually
adding dtparam=i2c_arm=on to /boot/config.txt. Remember to reboot
the Raspberry Pi afterwards.
- SDA: BCM GPIO 2 (physical pin 3)
- SCL: BCM GPIO 3 (physical pin 5)
I2C3
I2C3 can be enabled by adding dtoverlay=i2c3 to /boot/config.txt.
- SDA: BCM GPIO 4 (physical pin 7)
- SCL: BCM GPIO 5 (physical pin 29)
I2C4
I2C4 can be enabled by adding dtoverlay=i2c4 to /boot/config.txt.
- SDA: BCM GPIO 8 (physical pin 24)
- SCL: BCM GPIO 9 (physical pin 21)
I2C5
I2C5 can be enabled by adding dtoverlay=i2c5 to /boot/config.txt.
- SDA: BCM GPIO 12 (physical pin 32)
- SCL: BCM GPIO 13 (physical pin 33)
I2C6
I2C6 can be enabled by adding dtoverlay=i2c6 to /boot/config.txt.
- SDA: BCM GPIO 22 (physical pin 15)
- SCL: BCM GPIO 23 (physical pin 16)
Alternative pins
The GPIO pin numbers mentioned above are part of the default configuration.
Some of their functionality can be moved to different pins. Read
/boot/overlays/README for more information.
Software I2C
In addition to the hardware I2C buses, it’s possible to configure a
bit-banged software I2C bus on any available GPIO pins through the i2c-gpio
device tree overlay. More details on enabling and configuring i2c-gpio
can be found in /boot/overlays/README.
Transmission speed
The BSC supports I2C data transfer rates up to 400 kbit/s (Fast-mode).
By default, the I2C bus clock speed is set to 100 kHz. Transferring
1 bit takes 1 clock cycle. You can change the
transfer rate by adding dtparam=i2c_arm_baudrate=X to
/boot/config.txt, where X should be replaced with the
clock frequency in hertz (Hz). Remember to reboot
the Raspberry Pi afterwards.
Not supported
Some I2C and SMBus features aren’t fully supported by the i2cdev interface, the underlying driver or
the BCM283x SoC: 10-bit slave addresses, SMBus Block Read, SMBus Block Process Call, SMBus Host Notify,
SMBus Read/Write 32/64, and the SMBus Address Resolution Protocol.
While clock stretching is supported, a bug exists in the implementation on the BCM283x SoC that will result in corrupted data when a slave device uses clock stretching at arbitrary points during the transfer. Clock stretching only works properly during read operations, directly after the ACK phase, when the additional delay is longer than half of a clock period. More information can be found here.
A possible workaround for slave devices that require clock stretching at other points during the transfer is
to use a bit-banged software I2C bus by configuring the i2c-gpio device tree overlay as described in /boot/overlays/README.
Troubleshooting
Permission denied
If new or with_bus returns an io::ErrorKind::PermissionDenied
error, make sure the file permissions for /dev/i2c-1 or /dev/i2c-0
are correct, and the current user is a member of the i2c group.
Timed out
Transactions return an io::ErrorKind::TimedOut error when their duration
exceeds the timeout value. You can change the timeout using set_timeout.
Structs
- Lists the features supported by the underlying drivers.
- Provides access to the Raspberry Pi’s I2C peripheral.
Enums
- Errors that can occur when accessing the I2C peripheral.
Type Definitions
- Result type returned from methods that can have
i2c::Errors.