Module rppal::i2c

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/firmware/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/firmware/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/firmware/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/firmware/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/firmware/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/firmware/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

• Capabilities
  Lists the features supported by the underlying drivers.
• I2c
  Provides access to the Raspberry Pi’s I2C peripheral.

Enums

• Error
  Errors that can occur when accessing the I2C peripheral.

Type Aliases

• Result
  Result type returned from methods that can have i2c::Errors.