Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rm-hull/luma.oled/llms.txt

Use this file to discover all available pages before exploring further.

I2C is the simplest interface for connecting an OLED display. It requires only four connections — power, ground, clock (SCL), and data (SDA) — making it the easiest choice for most projects. Because the two signal lines are shared among all devices on the bus, you can attach multiple I2C devices without using additional GPIO pins.

​
Pin connections

Connect the display to the Raspberry Pi P1 header as follows:
Device PinNameRemarksRPi PinRPi Function
1GNDGroundP01-6GND
2VCC+3.3V PowerP01-13V3
3SCLClockP01-5GPIO 3 (SCL)
4SDADataP01-3GPIO 2 (SDA)
On rev.2 Raspberry Pi boards, there is also a bare P5 header next to the P1 header that exposes I2C channel 0 on GPIO 28 (SDA) and GPIO 29 (SCL). This channel is not enabled by default and may be reserved for the camera module.

​
Enable I2C on Raspberry Pi OS

The I2C kernel driver is not always enabled by default. Follow these steps to enable it:
1

Run raspi-config

sudo raspi-config
2

Navigate to Interface Options

Use the down arrow to select Interface Options.
3

Enable I2C

Arrow down to I2C and select yes when asked to enable it. Also select yes when asked about automatically loading the kernel module.
4

Finish and reboot

Use the right arrow to select Finish, then reboot your Pi.
After rebooting, verify the driver is loaded: 
dmesg | grep i2c
You should see output similar to: 
[    4.925554] bcm2708_i2c 20804000.i2c: BSC1 Controller at 0x20804000 (irq 79) (baudrate 100000)
[    4.929325] i2c /dev entries driver
You can also check with: 
lsmod | grep i2c
Expected output: 
i2c_dev                 5769  0
i2c_bcm2708             4943  0
regmap_i2c              1661  3 snd_soc_pcm512x,snd_soc_wm8804,snd_soc_core
If neither command shows any I2C modules, the kernel driver is not loaded — go back through the raspi-config steps above.

​
Increase baudrate (optional)

By default, I2C runs at 100 KHz. To improve display update performance, increase the baudrate to 400 KHz by editing /boot/config.txt: 
dtparam=i2c_arm=on,i2c_baudrate=400000
Then reboot for the change to take effect.

​
Add user to the i2c group

sudo usermod -a -G i2c pi
sudo apt-get install i2c-tools
Log out and back in for the group membership to take effect.

​
Find the device address

Use i2cdetect to confirm your display is connected and to find its I2C address (use bus 0 on rev.1 boards): 
i2cdetect -y 1
Example output: 
       0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
  00:          -- -- -- -- -- -- -- -- -- -- -- -- --
  10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
  20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
  30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
  40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
  50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
  60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
  70: -- -- -- -- -- -- -- --
In this example, the display is detected at address 0x3c. If multiple addresses appear, check your display’s documentation to identify which one corresponds to it.

​
Initialize the interface in Python

Pass the bus port number and the address detected above to the i2c interface class: 
from luma.core.interface.serial import i2c

serial = i2c(port=1, address=0x3C)

Build docs developers (and LLMs) love

Get started for freeTalk to us