Qwiic SHIM Kit for Raspberry Pi Hookup Guide

Contributors: bboyho
Favorited Favorite 0


The Qwiic SHIM Kit for Raspberry Pi gets you started with some of the basics surrounding I2C and Python on your Raspberry Pi. This tutorial will go over connecting Qwiic-enabled devices, installing their Python packages, and running the example code.

SparkFun Qwiic SHIM Kit for Raspberry Pi

SparkFun Qwiic SHIM Kit for Raspberry Pi


Required Materials

To follow along with this tutorial, you will also need a few pieces of hardware. Single board computers with the Raspberry Pi 40-pin GPIO standard header will work. We'll be using a Raspberry Pi throughout this tutorial. If you have not worked with a Raspberry Pi, we recommend pairing the Qwiic SHIM Kit with a Raspberry Pi 4 kit. At a minimum, you'll need a basic kit. However, if you need keyboard and mouse combination, we recommend getting the desktop kit.

SparkFun Raspberry Pi 4 Basic Kit - 4GB

SparkFun Raspberry Pi 4 Basic Kit - 4GB


SparkFun Raspberry Pi 4 Desktop Kit - 4GB


Optional Materials

You have several options when it comes to working with the Raspberry Pi. Most commonly, the Pi is used as a standalone computer, which requires a monitor. The following parts can be used with the Pi 4 if you opt for a small display. To save on costs, the Pi can also be used as a headless computer (without a monitor, keyboard, and mouse). This setup has a slightly more difficult learning curve, as you will need to use the command-line interface (CLI) from another computer.

Raspberry Pi LCD - 7" Touchscreen

Raspberry Pi LCD - 7" Touchscreen

SmartiPi Touch 2

SmartiPi Touch 2


Suggested Reading

If you aren't familiar with Qwiic, we recommend reading here for an overview.

Qwiic Connect System
Qwiic Connect System

We also recommend taking a look at some of our other tutorials and familiarizing yourself with some of these topics and parts. We will end up working with the Raspberry Pi and Python programming language.

Raspberry Pi 4 Kit Hookup Guide

March 14, 2020

Guide for hooking up your Raspberry Pi 4 Model B basic, desktop, or hardware starter kit together.

Python Programming Tutorial: Getting Started with the Raspberry Pi

June 27, 2018

This guide will show you how to write programs on your Raspberry Pi using Python to control hardware.


An introduction to I2C, one of the main embedded communications protocols in use today.

Serial Terminal Basics

This tutorial will show you how to communicate with your serial devices using a variety of terminal emulator applications.

AVR-Based Serial Enabled LCDs Hookup Guide

The AVR-based Qwiic Serial Enabled LCDs are a simple and cost effective solution to include in your project. These screens are based on the HD44780 controller, and include ATmega328P with an Arduino compatible bootloader. They accept control commands via Serial, SPI and I2C (via PTH headers or Qwiic connector). In this tutorial, we will show examples of a simple setup and go through each communication option.

SparkFun 9DoF IMU (ICM-20948) Breakout Hookup Guide

How to use the SparkFun 9DoF ICM-20948 breakout board for your motion sensing projects. This breakout is ideal for wearable sensors and IoT applications.

Qwiic SHIM for Raspberry Pi Hookup Guide

Ever wanted to prototype I2C components on a Pi? Now you can!

Hardware Assembly

The hardware that is included in this kit is a 16x2 SerLCD with RGB backlight, 9DoF IMU (ICM-20948), Qwiic SHIM, and Qwiic cables. The Qwiic connector color may vary. This should not affect the overall functionality of the boards.

Qwiic SHIM Kit

Connecting Qwiic devices to the Raspberry Pi makes it even easier than ever with the Qwiic SHIM. Slide the Qwiic SHIM into the Raspberry Pi's header so that the square PTH pad is aligned with pin 1.

Pi 4 with SHIM

At this point, connect the Qwiic cable between the boards. Insert the shorter Qwiic cable between the Qwiic SHIM and 9DoF's Qwiic connectors. Then insert the longer Qwiic cable between the 9DoF and Qwiic SHIM. The length of the cable between the boards does not really matter so you could insert the cables any way that you would like as well.

Qwiic Cable between Qwiic Shim and SerLCD 16x2

Then connect all the necessary peripherals to your Raspberry Pi. In this case, we connected a keyboard, mouse, HDMI monitor, and a power supply.

Power and Monitor Cable Connected Full Setup

Configure Your Pi

We are going to assume that you already have a Raspberry Pi up and running with Raspbian. We'll also assume that it is connected to the Internet. If not, check out our starter kits and tutorials on setting up a Raspberry Pi.

Raspberry Pi 4 Kit Hookup Guide

March 14, 2020

Guide for hooking up your Raspberry Pi 4 Model B basic, desktop, or hardware starter kit together.

Make sure to update the image so that we have the latest distribution. Enter the following commands in the command line individually to update your image.

sudo apt-get update
sudo apt-get dist-upgrade
Note: sudo stands for "Super User Do", it is a way to give you superuser powers from the command line. Be careful whenever using sudo.

User Configuration Settings

Once you are set up, I highly recommend changing your password. At this point, we don't want unsavory characters sneaking into your system using the default login: (username: pi, password: raspberry).

Raspberry Pi Configuration via Desktop GUI

To change the password using the Desktop GUI, head to the Raspberry Pi Start Menu > Preferences > Raspberry Pi Configuration > System > Change Password...

Raspberry Pi Configuration

At this point, you can also head to the Interfaces tab and set I2C to Enabled. Once the settings have been changed, click OK.

Enable I2C Raspberry Pi Configuration

You will need to restart your Pi before the settings can take effect. Head to Raspberry Pi Start Menu > Logout > Reboot

Raspberry Pi Logout

raspi-config Tool via Terminal

The raspi-config tool is a quick way to change your password as well as setup the network, language, keyboard, etc. Type the following command using the command line and then go through the menus to update your information.

sudo raspi-config

You'll want to enable the I2C pins using the tool to read the sensors on the I2C bus.

Enabling I2C on a Pi

Raspi-config for I2C

You will need to restart your Pi before the settings can take effect. After exiting raspi-config, let's reboot your Pi with the following command.

sudo reboot


Notice: This tutorial was written with the following software versions.

  • Raspbian Pi OS Full (32-bit) version 10, Kernel version 5.4 (Released 12/2/2020)
  • Python version 3.7.3
  • pip 20.3.3 for Python 3.7

Other versions may affect how some of the steps in this guide are performed.


In many programming languages, we indent things to make things easier to read. In Python, those indents are part of the code. Instead of putting brackets around your loop or if() statements, you just indent that entire chunk with a leading whitespace. In other words, you have to make sure your indents are correct. I also recommend not using your keyboard's TAB button to indent as various programs will read it differently (and usually incorrectly).


Another thing to keep in mind is comments. In Python, the symbol "#" is used to denote that the line is a comment. Unlike many other languages there is no official multi-line comment available. So you'll just have to get use to typing # for each line when writing large comments.

Python Versions and Installing PIP

There are also 2 commonly used Python versions. Even after Python 3 came out many people continued to use 2.7 for many years. Part of the reason is that Python 3 improved on some things and in the process made it not backwards compatible. As of January 1st, 2020, Python 2 is no longer supported. For our example we will be using Python 3.7. To see what version of Python your Pi is using, open a command line and type each of the following commands individually to check.

python --version
python -m pip --version

If you are not using Python 3, then we'll need to open the */.bashrc file and add an alias.

First, you will need to update the python installation package by running the following command to install pip for Python 3. Execute the following commands.

sudo apt-get install python3-pip

Type the following command to open the file.

nano ~/.bashrc

Then add the following lines at the end. That should tell the computer whenever you want to run python to look for the file located at /usr/bin/python3.

alias python='/usr/bin/python3'
alias pip=pip3

Alias Python 3 and pip3

To exit nano type CTRL + X and then hit Y when it asks you if you want to save and then ENTER. You can now either reboot or type the following to force the Pi to run the *.bashrc file again.

source ~/.bashrc

Once adjusted, type the following command to ensure that pip is up to date.

python -m pip install --upgrade pip

Python Library

We will also need to install the Qwiic Python libraries. This will automatically download a folder containing all the Qwiic_Py files and dependencies to your Raspberry Pi. Run the following command to automatically install the modules for the Qwiic sensors and SerLCD. To ensure that you are installing to the correct path for Python 3, make sure that you use pip3.

sudo pip3 install sparkfun_qwiic

Example: ICM-20948 Readings

To start, there are basic examples written in Python for the ICM-20948 and SerLCD. We'll go over one for each to see if the Qwiic-enabled devices are working as expected.

Reading the Data with the ICM-20948

In your terminal window, type the following to download the basic example code from the GitHub repository. Otherwise, you can manually download the example code.

git clone https://github.com/sparkfun/Qwiic_9DoF_IMU_ICM20948_Py

Then navigate to examples folder by entering the following command.

cd Qwiic_9DoF_IMU_ICM20948_Py/examples

Using the ls command will list the examples in the folder. As of the writing from this tutorial, there's only one so we will enter the following command to run the example.

python ex1_qwiic_ICM20948.py

You should see an output similar to image below. Depending on how the sensor is oriented, the values might be different. Moving the sensor around will change the raw values in the terminal window. The window will probably be too small and wrap around to the next row. To slow the output down, stop the code by typing CTRL + C and adjust the value for the delay after the print() function where it says time.sleep(0.03) to a larger number. Once the code has been adjusted, try running the code again.

9DoF Readings Through Terminal

You could also navigate to the example folder, open the example in Thonny, and hit the Run button. The readings will show up in the shell.

Thonny IDE 9DoF ICM20948 Readings

Example: SerLCD - Hello World!

SerLCD: Hello World!

In your terminal window, type the following to download the basic example code from the GitHub repository.

git clone https://github.com/sparkfun/Qwiic_SerLCD_Py

Then navigate to the examples folder by entering the following command.

cd Qwiic_SerLCD_Py/examples

Using the ls command will list the examples in the folder. There are few examples in the folder but we're interested in only viewing the "Hello World!" example. Enter the following command to run the example.

python ex1_qwiic_serlcd_hello_world.py

You should see the familiar phrase "Hello World!" displayed in the terminal window with a counter increasing.

Output Terminal Window

If you are using Thonny, you should see the same output in the Shell.

Output Thonny

You should see the same message on the SerLCD with a counter increasing on the next row as well.

RGB Character Serial LCD Displaying Hello World with Counter

Sweet! There are several other examples available in the Qwiic_SerLCD_Py library. Try running the other examples listed in the examples folder to test by using the python command followed by the name of the python file.

Example: Combined SerLCD and ICM-20948

Combined Example

This code combines a few of the examples together. The orientation of the 9DoF will control the RGB backlight. For simplicity, we will only display the name of the color. Try scaling the readings down before printing the accelerometer readings on the screen.

In your terminal window, type the following to download the combined example code from the GitHub repository.

git clone https://github.com/sparkfun/Qwiic_SHIM_Kit

Then navigate to the examples folder by entering the following command.

cd Qwiic_SHIM_Kit/examples

Enter the following command to run the combined example.

python combined1_RGB_SerLCD_ICM20948.py

You can also copy the example below.

#!/usr/bin/env python3
# combined1_RGB_SerLCD_ICM20948.py
# Combined example to control the RGB LED on the SerLCD
# based on the accelerometer readings on the ICM20948.
# Written by  SparkFun Electronics, March 2020
# This python library supports the SparkFun Electroncis qwiic 
# qwiic sensor/board ecosystem on a Raspberry Pi (and compatible) single
# board computers. 
# More information on qwiic is at https://www.sparkfun.com/qwiic
# Do you like this library? Help support SparkFun. Buy a board!
# Copyright (c) 2019 SparkFun Electronics
# Permission is hereby granted, free of charge, to any person obtaining a copy 
# of this software and associated documentation files (the "Software"), to deal 
# in the Software without restriction, including without limitation the rights 
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
# copies of the Software, and to permit persons to whom the Software is 
# furnished to do so, subject to the following conditions:
# The above copyright notice and this permission notice shall be included in all 
# copies or substantial portions of the Software.

from __future__ import print_function
import qwiic_serlcd
import qwiic_icm20948
import time
import sys

#create global variable to keep track of color when debugging
ledColor = 1

def runExample():

    print("\nSparkFun SerLCD and 9DoF ICM-20948 Sensor Example\n")
    myLCD = qwiic_serlcd.QwiicSerlcd()
    IMU = qwiic_icm20948.QwiicIcm20948()

    if myLCD.connected == False:
        print("The Qwiic SerLCD device isn't connected to the system. Please check your connection", \

    if IMU.connected == False:
        print("The Qwiic ICM20948 device isn't connected to the system. Please check your connection", \

    myLCD.setBacklight(255, 255, 255) # Set backlight to bright white
    myLCD.setContrast(5)  # Set contrast. Lower to 0 for higher contrast.
    myLCD.clearScreen()   # Clear Screen - this moves the cursor to the home position as well
    myLCD.print("white")  # Write to color name to SerLCD

    time.sleep(0.5) # give a sec for system messages to complete


    while True:
        #declare ledColor a global variable inside here to access it 
        global ledColor

        if IMU.dataReady():
            IMU.getAgmt() # read all axis and temp from sensor, note this also updates all instance variables

            #the following are the threshold values for each axis is pointing right-side up

            # anything above IMU.azRaw > 16000 is red
            # ledColor = 1
            aZPos = 16000

            # anything below IMU.azRaw < -16000 is blue
            # ledColor = 2
            aZNeg = -16000

            # anything above IMU.ayRaw > 16100 is green
            # ledColor = 3
            ayPos = 16100

            # anything below IMU.ayRaw < -16000 is green
            # ledColor = 4
            ayNeg = -16000

            # anything above IMU.axRaw > 16000 is magenta
            # ledColor = 5
            axPos = 16000

            # anything below IMU.axRaw < -16400 is cyan
            # ledColor = 6
            axNeg = -16400

            #adjust color of the LED based on the accelerometer's reading
            if IMU.azRaw > aZPos:
                # Set LED red
                myLCD.setBacklight(255, 0, 0) # Set backlight to bright white
                ledColor = 1

            elif IMU.azRaw < aZNeg:
                # Set LED blue
                myLCD.setBacklight(0, 0, 255) # Set backlight to bright white
                ledColor = 2

            elif IMU.ayRaw > ayPos:
                # Set LED yellow
                myLCD.setBacklight(255, 255, 0) # Set backlight to bright white
                ledColor = 3

            elif IMU.ayRaw < ayNeg:
                # Set LED green
                myLCD.setBacklight(0, 255, 0) # Set backlight to bright white
                ledColor = 4

            elif IMU.axRaw > axPos:
                # Set LED magenta
                myLCD.setBacklight(255, 0, 255) # Set backlight to bright white
                ledColor = 5

            elif IMU.axRaw < axNeg:
                # Set LED cyan
                myLCD.setBacklight(0, 255, 255) # Set backlight to bright white
                ledColor = 6

            if ledColor == 1:
                print("ledColor = red" ,'\n', '\n')
            elif ledColor == 2:
                print("ledColor = blue" ,'\n', '\n')
            elif ledColor == 3:
                print("ledColor = yellow" ,'\n', '\n')
            elif ledColor == 4:
                print("ledColor = green" ,'\n', '\n')
            elif ledColor == 5:
                print("ledColor = magenta" ,'\n', '\n')
            elif ledColor == 6:
                print("ledColor = cyan" ,'\n', '\n')

            aX = IMU.axRaw
            aY = IMU.ayRaw
            aZ = IMU.azRaw
            gX = IMU.gxRaw
            gY = IMU.gyRaw
            gZ = IMU.gzRaw
            mX = IMU.mxRaw
            mY = IMU.myRaw
            mZ = IMU.mzRaw

            # Remove the `#` for the following lines to 
            # display accelerometer readings on SerLCD




             ' aX:', '{: 4.1f}'.format(aX)\
            , ' \t, aY:', '{: 4.1f}'.format(aY)\
            , '\t, aZ:', '{: 4.1f}'.format(aZ)\
            , '\n gX:', '{: 4.1f}'.format(gX)\
            , '\t, gY:', '{: 4.1f}'.format(gY)\
            , '\t, gZ:', '{: 4.1f}'.format(gZ)\
            , '\n mX:', '{: 4.1f}'.format(mX)\
            , '\t, mY:', '{: 4.1f}'.format(mY)\
            , '\t, mZ:', '{: 4.1f}'.format(mZ)\
            , '\n'\

            time.sleep(1) # small delay so that the screen doesn't flicker
            print("Waiting for data")

if __name__ == '__main__':
    except (KeyboardInterrupt, SystemExit) as exErr:
        print("\nEnding Combined Example")

The terminal will begin displaying the current color and sensor readings.

Terminal Output of Combined Example

If you are using Thonny, you will see the same output in the Shell.

Thonny Output of Combined Example

If you check out the SerLCD with RGB backlight, the screen will display the color name and color backlight based on the accelerometer readings. The color will change depending on what axis is pointing up. Your setup may look slightly different depending on how you connected the Qwiic cables so be sure to reference the silkscreen for the accelerometer.

RGB Character Serial LCD Display Controlled by the ICM-20948's accelerometer readings

Resources and Going Further

For more information, check out the resources below:

Python Logo

Looking for more inspiration? Check out these other Raspberry Pi projects and Python tutorials.:

Graph Sensor Data with Python and Matplotlib

Use matplotlib to create a real-time plot of temperature data collected from a TMP102 sensor connected to a Raspberry Pi.

Python GUI Guide: Introduction to Tkinter

Tkinter is the standard graphical user interface package that comes with Python. This tutorial will show you how to create basic windowed applications as well as complete full-screen dashboard examples complete with live graph updates from matplotlib.

How to Run a Raspberry Pi Program on Startup

In this tutorial, we look at various methods for running a script or program automatically whenever your Raspberry Pi (or other Linux computer) boots up.

Qwiic Kit for Raspberry Pi Hookup Guide

Get started with the CCS811, BME280, VCNL4040, and microOLED via I2C using the Qwiic system and Python on a Raspberry Pi! Take sensor readings from the environment and display them on the microOLED, serial terminal, or the cloud with Cayenne!

SparkFun Pro nRF52840 Mini Hookup Guide

A hardware overview and hookup guide for the SparkFun Pro nRF52840 Mini -- a breakout for Nordic's impossibly cool Bluetooth/ARM Cortex M4 SoC.

Jetson Nano + Sphero RVR Mash-up (PART 1)

We took two of our biggest robotics partnerships from the previous year and shazamed them together into one robot to rule them all!

SparkFun Qwiic Dual Solid State Relay Hookup Guide

A Hookup Guide to get you started with the SparkFun Qwiic Dual Solid State Relay.

Triple Axis Accelerometer Breakout - KX13x (Qwiic) Hookup Guide

Get started measuring acceleration and vibration using the Triple Axis Accelerometer Breakout - KX134 (Qwiic) & KX132 (Qwiic) following this Hookup Guide.

Or check out some of these blog posts for ideas: