OK, so you've done a scan and gotten some results. How do those help with troubleshooting. Here we discuss various scenarios and what they imply.

Correct Addresses Show Up

In general, you should be all good. There's nothing more to be done with an I2C scan. Go ahead and start trying to use the device, preferably using an example from the devices library.

If you get additional errors when trying to run the library example, post in the Adafruit forums with details.

Incorrect Addresses Show Up

Weird, but can happen in rare cases. Double check the device and make sure it is what you think it is. Some devices can have more than one I2C address, typically settable somehow by the users. Check if the incorrect address is one of these alternate addresses.

If everything seems correct but you are still getting an incorrect address, post in the Adafruit forums with details.

No Addresses Show Up

Try just scanning again. Some devices can be weird and not show up on first scan. If that still does not work, then: Check your wiring and/or your soldering. This accounts for the vast majority of issues.

Wiring

Wiring issues can be incorrect pins or even just bad wires. Double and triple check you are using the correct pins. If you are using a breadboard, try moving to a different location. Breadboards can wear out with time. Also try totally different wires. The pre-crimped prototype wires commonly used can also wear out over time.

Soldering

This is unfortunately a very common issue for beginners. Soldering is not super tough, but does take a little getting used to. There's a good general guide on soldering as well as a guide specific to the commonly used headers pins.

This photo from the first guide is an excellent summary of common soldering issues:

Common

If you've checked all this and are still not getting the expected results, post in the Adafruit forums with details. Photos are very helpful when doing so.

"No pull up found on SDA or SCL"

This error message is unique to CircuitPython, which performs a check on the SDA and SCL pins to determine if the pull up resistors are present. This is most likely a connection issue, either wiring/soldering or connected to the wrong pins. See info above about checking wiring and soldering.

If wiring and soldering seem good, then it could be that the pins beings used by the code are not the same pins the device is attached to. Some boards have multiple I2C ports and/or the I2C pins can show up in multiple locations. This can lead to general confusion about which specific pins should be used, esp. when using the built ins like board.I2C(). Double check the board's pinout information with special attention on where the SDA and SCL pins are located. For boards with STEMMA QT connectors, check if there is a board.STEMMA_I2C() defined.

"TimeoutError: Clock stretch too long"

This error message is unique to CircuitPython. Clock stretching is discussed elsewhere and CircuitPython has safeguards against overly long stretches. If you're using an I2C device that is known to have long clock stretches, then it may be hitting CircuitPython limits.

However, an electrical short between the SDA and SCL pins can potentially cause this error to show up. In that case, it will typically occur when the I2C bus is created, i.e. on the code line with board.I2C(), or busio.I2C(), or bitbangio.I2C(), etc. Even a tiny solder whisker can create enough of an electrical short to cause this to occur. So check for any obvious shorts, but also carefully examine any soldering as well.

This guide was first published on Sep 16, 2021. It was last updated on Jun 20, 2024.

This page (Troubleshooting) was last updated on Mar 08, 2024.

Text editor powered by tinymce.