Getting started with Qwiic and Raspberry Pi: A Seamless integration

If you're already familiar with the Raspberry Pi and want a simpler, cleaner way to connect sensors and modules, the Qwiic ecosystem is the upgrade you've been looking for.
Qwiic eliminates breadboards, messy wiring and incorrect pin mapping. With just a single 4-pin cable, you can connect sensors, displays, inputs and more, which makes it perfect for beginners, students and hobbyists building their first Raspberry Pi I2C projects.

What is the Qwiic Connect System?

The Qwiic Connect System is a standardized 4-pin connector used for I2C communication. It was designed to make electronics more accessible by eliminating the need for soldering or wiring.

A Qwiic connector includes:

• GND
• 3.3V power
• SCL
• SDA

Because the connector is polarized, you can't plug it in backwards, which makes it ideal for beginners.

Why use Qwiic with Raspberry Pi?

Reasons Qwiic shines on Raspberry Pi:

• No wiring mistakes, which makes it perfect for classrooms and rapid prototyping
• Chain multiple I2C devices together
• 3.3 V safe by default
• Compact connectors save space in enclosures
• Works with many plug-and-play modules

If you want your Raspberry Pi projects to be clean, fast and reliable, Qwiic is the way to go.

What You'll Need for This Tutorial

To follow along this tutorial you will need:

• 1x Raspberry Pi with Raspberry Pi OS
• 2x Qwiic cable
• 1x Soldered BME680 environmental sensor
• 1x Soldered SSD1306 OLED display
• 1x Soldered Raspberry Pi Qwiic adapter

• Raspberry Pi 5 (4GB)
• Qwiic / easyC cable
• BME680 environmental sensor
• SSD1306 OLED display (0.96")
• Raspberry Pi Qwiic / easyC adapter

Step 1: Enabling I2C on your Raspberry Pi

1. Open a terminal on your Raspberry Pi

sudo raspi-config

2. Navigate to: Interface Options → I2C → Enable
3. Reboot the Raspberry Pi

To confirm I2C is working:

sudo apt install i2c-tools
i2cdetect -y 1

Step 2: Connecting Your Qwiic Devices

Connect your BME680 sensor and OLED display to the Raspberry Pi using Qwiic cables. Both devices are I2C, so you can chain them together or connect them separately on the Qwiic Raspberry Pi adapter.

Step 3: Installing the Necessary Libraries

First, install the pigpio daemon, which is required to communicate with the BME680 in this project:

sudo apt update
sudo apt install pigpio python3-pigpio python3-smbus

Enable and start the pigpio daemon:

sudo systemctl enable pigpiod
sudo systemctl start pigpiod

Install supporting Python packages for the SSD1306 OLED display:

pip3 install adafruit-circuitpython-ssd1306
pip3 install Pillow

Confirm that the I2C devices are visible:

i2cdetect -y 1

You should see the BME680 at 0x76 and the OLED display at 0x3C.

Step 4: A Simple Project: Reading from a Qwiic Sensor

One of the easiest ways to see the potential of the Qwiic system is to connect a BME680 environmental sensor and show live data on a small OLED display. This project shows two common ways to communicate with modules: higher-level display output via Adafruit’s SSD1306 library and lower-level BME680 access using the pigpio daemon.

import os
import pigpio
import time
import board
import busio
from PIL import Image, ImageDraw, ImageFont
import adafruit_ssd1306

# Check if pigpiod is running, start if it's not
os.system("pgrep pigpiod >/dev/null || sudo pigpiod")

# I2C parameters for the BME680 sensor
I2C_ADDR = 0x76  # Default I2C address of the BME680
I2C_BUS = 1      # Use I2C bus 1 (standard on most Raspberry Pi models)

# Helper function that checks if measurement is done
def wait_measurement_done(pi, handle, timeout_s=0.5):
    start = time.time()
    while True:
        count, status = pi.i2c_read_i2c_block_data(handle, 0x1D, 1)
        if count == 1:
            # Bit 5 clears when measurement is done
            if (status[0] & 0x20) == 0:
                return True
        if time.time() - start > timeout_s:
            return False
        time.sleep(0.005)  # 5 ms

# Function to perform a single temperature reading from the BME680 sensor
def BME680Temperature():
    pi = pigpio.pi()
    if not pi.connected:
        print("Cannot connect to pigpio daemon")
        exit(1)

    h = pi.i2c_open(I2C_BUS, I2C_ADDR)

    # Trigger a forced temperature measurement
    pi.i2c_write_byte_data(h, 0x74, 0xA1)

    if not wait_measurement_done(pi, h, timeout_s=0.5):
        print("Measurement timeout")

    # Read raw ADC temperature data
    count, tbytes = pi.i2c_read_i2c_block_data(h, 0x22, 3)
    temp_msb, temp_lsb, temp_xlsb = tbytes
    temp_adc = (temp_msb << 12) | (temp_lsb << 4) | (temp_xlsb >> 4)

    # Read calibration parameters
    count, data = pi.i2c_read_i2c_block_data(h, 0xE9, 2)
    par_t1 = data[0] | (data[1] << 8)

    count, data = pi.i2c_read_i2c_block_data(h, 0x8A, 2)
    par_t2 = data[0] | (data[1] << 8)
    if par_t2 & 0x8000:
        par_t2 -= 1 << 16

    count, data = pi.i2c_read_i2c_block_data(h, 0x8C, 1)
    par_t3 = data[0]
    if par_t3 & 0x80:
        par_t3 -= 1 << 8

    # Compensation formula (Bosch datasheet)
    var1 = ((temp_adc / 16384.0) - (par_t1 / 1024.0)) * par_t2
    var2 = (((temp_adc / 131072.0) - (par_t1 / 8192.0)) ** 2) * (par_t3 * 16.0)
    t_fine = var1 + var2
    temp_comp = t_fine / 5120.0

    pi.i2c_close(h)
    pi.stop()
    return temp_comp

# Initialize I2C communication for OLED (128x64)
i2c = busio.I2C(board.SCL, board.SDA)
oled = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c)

oled.fill(0)
oled.show()

image = Image.new("1", (oled.width, oled.height))
draw = ImageDraw.Draw(image)
font = ImageFont.load_default()

while True:
    oled.fill(0)

    temp_comp = BME680Temperature()

    draw.rectangle((0, 0, oled.width - 1, oled.height - 1), outline=255, fill=0)
    draw.text((10, 25), f"{temp_comp:.2f} C", font=font, fill=255)

    oled.image(image)
    oled.show()
    time.sleep(5)

Troubleshooting Common Issues

1. i2cdetect doesn't show the BME680 or the OLED

This usually means that:

• The Qwiic cable isn't fully connected
• The cable is plugged into the wrong port
• You forgot to enable I2C on the Raspberry Pi
• The BME680 might be on a different address (0x76 or 0x77)

2. Pigpio error: "Cannot connect to the pigpio daemon"

The pigpio daemon must be running before the script starts. Run:

sudo systemctl start pigpiod

If you want it to always run on boot:

sudo systemctl enable pigpiod

3. OLED screen stays black or shows nothing

This most often means that:

• The OLED wasn't cleared before writing
• Wrong display resolution
• The I2C address is different
• The script is still drawing to an old image buffer

A simple fix is to call:

oled.fill(0)
oled.show()

before drawing.

Take Your Projects to the Next Level with More Qwiic Devices

Once you've seen how simple it is to connect a Qwiic device to your Raspberry Pi and get it all to work together, then the fun really starts. Check out our always growing collection of Qwiic sensor/actuator modules at soldered.com/categories/easyc-2/.