docs/library/machine.I2C: Add a note about I2C pull-up resistors.

robert-hh · dpgeorge · commit 53ebbf10e56d · 2022-08-31T00:07:23.000+10:00
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.
diff --git 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 <https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors>`_
+   by Adafruit about I2C wiring.
+
 Example usage::
 
     from machine import I2C
