From 53ebbf10e56dd4cc33aec6cc6d0590c66fd1948e Mon Sep 17 00:00:00 2001 From: robert-hh Date: Sat, 27 Aug 2022 10:42:15 +0200 Subject: [PATCH] docs/library/machine.I2C: Add a note about I2C pull-up resistors. Quite regularly users complain about unexpected behavior of I2C, calling it a bug, when in fact the trouble is caused by missing pull-up resistors. So this commit adds a note to the documentation, in the slim hope that people will find and read it. --- docs/library/machine.I2C.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 82a88390c3..2a33b1da47 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -20,6 +20,17 @@ Software I2C is implemented by bit-banging and can be used on any pin but is not as efficient. These classes have the same methods available and differ primarily in the way they are constructed. +.. Note:: + + The I2C bus requires pull-up circuitry on both SDA and SCL for it's operation. + Usually these are resistors in the range of 1 - 10 kOhm, connected from each SDA/SCL + to Vcc. Without these, the behaviour is undefined and may range from blocking, + unexpected watchdog reset to just wrong values. Often, this pull-up circuitry + is built-in already to the MCU board or sensor breakout boards, but there is + no rule for that. So please check in case of trouble. See also this excellent + `learning guide `_ + by Adafruit about I2C wiring. + Example usage:: from machine import I2C