The I2C, or inter-integrated circuit, is a 2-wire protocol for communicating with simple sensors and devices, which means it uses two connections, or wires, for transmitting and receiving data. One connection is a clock, called SCL. The other is the data line, called SDA. Each pair of clock and data pins are referred to as a bus.
Typically, there is a device that acts as a controller and sends requests to the target devices on each bus. In this case, your microcontroller board acts as the controller, and the sensor breakout acts as the target. Historically, the controller is referred to as the master, and the target is referred to as the slave, so you may run into that terminology elsewhere. The official terminology is controller and target.
Multiple I2C devices can be connected to the same clock and data lines. Each I2C device has an address, and as long as the addresses are different, you can connect them at the same time. This means you can have many different sensors and devices all connected to the same two pins.
Both I2C connections require pull-up resistors, and most Adafruit I2C sensors and breakouts have pull-up resistors built in. If you're using one that does not, you'll need to add your own 2.2-10kΩ pull-up resistors from SCL and SDA to 3.3V.
I2C and CircuitPython
CircuitPython supports many I2C devices, and makes it super simple to interact with them. There are libraries available for many I2C devices in the CircuitPython Library Bundle. (If you don't see the sensor you're looking for, keep checking back, more are being written all the time!)
In this section, you'll learn how to scan the I2C bus for all connected devices. Then you'll learn how to interact with an I2C device.
Necessary Hardware
You'll need the following additional hardware to complete the examples on this page.
While the examples here will be using the Adafruit MCP9808, a high accuracy temperature sensor, the overall process is the same for just about any I2C sensor or device.
The first thing you'll want to do is get the sensor connected so your board has I2C to talk to.
Wiring the MCP9808
The MCP9808 comes with a STEMMA QT connector, which makes wiring it up quite simple and solder-free.
Simply connect the STEMMA QT cable from the STEMMA QT port on your board to the STEMMA QT port on the MCP9808.
Find Your Sensor
The first thing you'll want to do after getting the sensor wired up, is make sure it's wired correctly. You're going to do an I2C scan to see if the board is detected, and if it is, print out its I2C address.
Save the following to your CIRCUITPY drive as code.py.
Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, find your CircuitPython version, and copy the matching code.py file to your CIRCUITPY drive.
CIRCUITPY
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
"""CircuitPython I2C Device Address Scan"""
import time
import board
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
# To create I2C bus on specific pins
# import busio
# i2c = busio.I2C(board.GP1, board.GP0) # Pi Pico RP2040
while not i2c.try_lock():
pass
try:
while True:
print(
"I2C addresses found:",
[hex(device_address) for device_address in i2c.scan()],
)
time.sleep(2)
finally: # unlock the i2c bus when ctrl-c'ing out of the loop
i2c.unlock()
If you run this and it seems to hang, try manually unlocking your I2C bus by running the following two commands from the REPL.
import board board.I2C().unlock()
First you create the i2c object, using board.I2C(). This convenience routine creates and saves a busio.I2C object using the default pins board.SCL and board.SDA. If the object has already been created, then the existing object is returned. No matter how many times you call board.I2C(), it will return the same object. This is called a singleton.
To be able to scan it, you need to lock the I2C down so the only thing accessing it is the code. So next you include a loop that waits until I2C is locked and then continues on to the scan function.
Last, you have the loop that runs the actual scan, i2c_scan(). Because I2C typically refers to addresses in hex form, the example includes this bit of code that formats the results into hex format: [hex(device_address) for device_address in i2c.scan()].
Open the serial console to see the results! The code prints out an array of addresses. You've connected the MCP9808 which has a 7-bit I2C address of 0x18. The result for this sensor is I2C addresses found: ['0x18']. If no addresses are returned, refer back to the wiring diagrams to make sure you've wired up your sensor correctly.
I2C Sensor Data
Now you know for certain that your sensor is connected and ready to go. Time to find out how to get the data from the sensor!
Save the following to your CIRCUITPY drive as code.py.
Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, find your CircuitPython version, and copy the matching entire lib folder and code.py file to your CIRCUITPY drive.
CIRCUITPY
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
"""CircuitPython I2C MCP9808 Temperature Sensor Example"""
import time
import board
import adafruit_mcp9808
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
# import busio
# i2c = busio.I2C(board.SCL1, board.SDA1) # For QT Py RP2040, QT Py ESP32-S2
mcp9808 = adafruit_mcp9808.MCP9808(i2c)
while True:
temperature_celsius = mcp9808.temperature
temperature_fahrenheit = temperature_celsius * 9 / 5 + 32
print("Temperature: {:.2f} C {:.2f} F ".format(temperature_celsius, temperature_fahrenheit))
time.sleep(2)
The Trinkey QT2040 STEMMA QT connector is available on board.STEMMA_I2C(). Comment out the current i2c setup line, and uncomment the the i2c = board.STEMMA_I2C() line to use with your board's STEMMA QT connector.
This code begins the same way as the scan code, except this time, you create your sensor object using the sensor library. You call it mcp9808 and provide it the i2c object.
Then you have a simple loop that prints out the temperature reading using the sensor object you created. Finally, there's a time.sleep(2), so it only prints once every two seconds. Connect to the serial console to see the results. Try touching the MCP9808 with your finger to see the values change!
Where's my I2C?
On many microcontrollers, you have the flexibility of using a wide range of pins for I2C. On some types of microcontrollers, any pin can be used for I2C! Other chips require using bitbangio, but can also use any pins for I2C. There are further microcontrollers that may have fixed I2C pins.
Given the many different types of microcontroller boards available, it's impossible to guarantee anything other than the labeled 'SDA' and 'SCL' pins. So, if you want some other setup, or multiple I2C interfaces, how will you find those pins? Easy! Below is a handy script.
Save the following to your CIRCUITPY drive as code.py.
Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, find your CircuitPython version, and copy the matching code.py file to your CIRCUITPY drive.
CIRCUITPY
# SPDX-FileCopyrightText: 2021-2023 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
"""CircuitPython I2C possible pin-pair identifying script"""
import board
import busio
from microcontroller import Pin
def is_hardware_i2c(scl, sda):
try:
p = busio.I2C(scl, sda)
p.deinit()
return True
except ValueError:
return False
except RuntimeError:
return True
def get_unique_pins():
exclude = [
getattr(board, p)
for p in [
# This is not an exhaustive list of unexposed pins. Your results
# may include other pins that you cannot easily connect to.
"NEOPIXEL",
"DOTSTAR_CLOCK",
"DOTSTAR_DATA",
"APA102_SCK",
"APA102_MOSI",
"LED",
"SWITCH",
"BUTTON",
"ACCELEROMETER_INTERRUPT",
"VOLTAGE_MONITOR",
"MICROPHONE_CLOCK",
"MICROPHONE_DATA",
"RFM_RST",
"RFM_CS",
"RFM_IO0",
"RFM_IO1",
"RFM_IO2",
"RFM_IO3",
"RFM_IO4",
"RFM_IO5",
"TFT_I2C_POWER",
"NEOPIXEL_POWER",
]
if p in dir(board)
]
pins = [
pin
for pin in [getattr(board, p) for p in dir(board)]
if isinstance(pin, Pin) and pin not in exclude
]
unique = []
for p in pins:
if p not in unique:
unique.append(p)
return unique
for scl_pin in get_unique_pins():
for sda_pin in get_unique_pins():
if scl_pin is sda_pin:
continue
if is_hardware_i2c(scl_pin, sda_pin):
print("SCL pin:", scl_pin, "\t SDA pin:", sda_pin)
Now, connect to the serial console and check out the output! The results print out a nice handy list of SCL and SDA pin pairs that support I2C.
Page last edited March 08, 2024
Text editor powered by tinymce.
