8000 docs: Update I2C and SPI docs to add reference to SoftI2C and SoftSPI. · codemee/micropython@98182a9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 98182a9

Browse files
dpgeorgedpgeorge
committed
docs: Update I2C and SPI docs to add reference to SoftI2C and SoftSPI.
Signed-off-by: Damien George <damien@micropython.org>
1 parent 71f3ade commit 98182a9

File tree

4 files changed

+89
-40
lines changed

4 files changed

+89
-40
lines changed

‎docs/esp32/quickref.rst

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -249,16 +249,15 @@ ESP32 specific ADC class method reference:
249249
Software SPI bus
250250
----------------
251251

252-
There are two SPI drivers. One is implemented in software (bit-banging)
253-
and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
254-
class::
252+
Software SPI (using bit-banging) works on all pins, and is accessed via the
253+
:ref:`machine.SoftSPI <machine.SoftSPI>` class::
255254

256-
from machine import Pin, SPI
255+
from machine import Pin, SoftSPI
257256

258-
# construct an SPI bus on the given pins
257+
# construct a SoftSPI bus on the given pins
259258
# polarity is the idle state of SCK
260259
# phase=0 means sample on the first edge of SCK, phase=1 means the second
261-
spi = SPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
260+
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
262261

263262
spi.init(baudrate=200000) # set the baudrate
264263

@@ -298,39 +297,54 @@ mosi 13 23
298297
miso 12 19
299298
===== =========== ============
300299

301-
Hardware SPI has the same methods as Software SPI above::
300+
Hardware SPI is accessed via the :ref:`machine.SPI <machine.SPI>` class and
301+
has the same methods as software SPI above::
302302

303303
from machine import Pin, SPI
304304

305305
hspi = SPI(1, 10000000, sck=Pin(14), mosi=Pin(13), miso=Pin(12))
306306
vspi = SPI(2, baudrate=80000000, polarity=0, phase=0, bits=8, firstbit=0, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
307307

308+
Software I2C bus
309+
----------------
308310

309-
I2C bus
310-
-------
311-
312-
The I2C driver has both software and hardware implementations, and the two
313-
hardware peripherals have identifiers 0 and 1. Any available output-capable
314-
pins can be used for SCL and SDA. The driver is accessed via the
315-
:ref:`machine.I2C <machine.I2C>` class::
316-
317-
from machine import Pin, I2C
311+
Software I2C (using bit-banging) works on all output-capable pins, and is
312+
accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
318313

319-
# construct a software I2C bus
320-
i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
314+
from machine import Pin, SoftI2C
321315

322-
# construct a hardware I2C bus
323-
i2c = I2C(0)
324-
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
316+
i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
325317

326-
i2c.scan() # scan for slave devices
318+
i2c.scan() # scan for devices
327319

328-
i2c.readfrom(0x3a, 4) # read 4 bytes from slave device with address 0x3a
329-
i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a
320+
i2c.readfrom(0x3a, 4) # read 4 bytes from device with address 0x3a
321+
i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
330322

331323
buf = bytearray(10) # create a buffer with 10 bytes
332324
i2c.writeto(0x3a, buf) # write the given buffer to the slave
333325

326+
Hardware I2C bus
327+
----------------
328+
329+
There are two hardware I2C peripherals with identifiers 0 and 1. Any available
330+
output-capable pins can be used for SCL and SDA but the defaults are given
331+
below.
332+
333+
===== =========== ============
334+
\ I2C(0) I2C(1)
335+
===== =========== ============
336+
scl 18 25
337+
sda 19 26
338+
===== =========== ============
339+
340+
The driver is accessed via the :ref:`machine.I2C <machine.I2C>` class and
341+
has the same methods as software I2C above::
342+
343+
from machine import Pin, I2C
344+
345+
i2c = I2C(0)
346+
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
347+
334348
Real time clock (RTC)
335349
---------------------
336350

‎docs/esp8266/quickref.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -214,15 +214,15 @@ Software SPI bus
214214
----------------
215215

216216
There are two SPI drivers. One is implemented in software (bit-banging)
217-
and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
217+
and works on all pins, and is accessed via the :ref:`machine.SoftSPI <machine.SoftSPI>`
218218
class::
219219

220-
from machine import Pin, SPI
220+
from machine import Pin, SoftSPI
221221

222222
# construct an SPI bus on the given pins
223223
# polarity is the idle state of SCK
224224
# phase=0 means sample on the first edge of SCK, phase=1 means the second
225-
spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
225+
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
226226

227227
spi.init(baudrate=200000) # set the baudrate
228228

@@ -258,7 +258,8 @@ I2C bus
258258
-------
259259

260260
The I2C driver is implemented in software and works on all pins,
261-
and is accessed via the :ref:`machine.I2C <machine.I2C>` class::
261+
and is accessed via the :ref:`machine.I2C <machine.I2C>` class (which is an
262+
alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
262263

263264
from machine import Pin, I2C
264265

‎docs/library/machine.I2C.rst

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,14 @@ when created, or initialised later on.
1212

1313
Printing the I2C object gives you information about its configuration.
1414

15+
Both hardware and software I2C implementations exist via the
16+
:ref:`machine.I2C <machine.I2C>` and `machine.SoftI2C` classes. Hardware I2C uses
17+
underlying hardware support of the system to perform the reads/writes and is
18+
usually efficient and fast but may have restrictions on which pins can be used.
19+
Software I2C is implemented by bit-banging and can be used on any pin but is not
20+
as efficient. These classes have the same methods available and differ primarily
21+
in the way they are constructed.
22+
1523
Example usage::
1624

1725
from machine import I2C
@@ -33,21 +41,33 @@ Example usage::
3341
Constructors
3442
------------
3543

36-
.. class:: I2C(id=-1, *, scl, sda, freq=400000)
44+
.. class:: I2C(id, *, scl, sda, freq=400000)
3745

3846
Construct and return a new I2C object using the following parameters:
3947

40-
- *id* identifies a particular I2C peripheral. The default
41-
value of -1 selects a software implementation of I2C which can
42-
work (in most cases) with arbitrary pins for SCL and SDA.
43-
If *id* is -1 then *scl* and *sda* must be specified. Other
44-
allowed values for *id* depend on the particular port/board,
45-
and specifying *scl* and *sda* may or may not be required or
46-
allowed in this case.
48+
- *id* identifies a particular I2C peripheral. Allowed values for
49+
depend on the particular port/board
50+
- *scl* should be a pin object specifying the pin to use for SCL.
51+
- *sda* should be a pin object specifying the pin to use for SDA.
52+
- *freq* should be an integer which sets the maximum frequency
53+
for SCL.
54+
55+
Note that some ports/boards will have default values of *scl* and *sda*
56+
that can be changed in this constructor. Others will have fixed values
57+
of *scl* and *sda* that cannot be changed.
58+
59+
.. _machine.SoftI2C:
60+
.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=255)
61+
62+
Construct a new software I2C object. The parameters are:
63+
4764
- *scl* should be a pin object specifying the pin to use for SCL.
4865
- *sda* should be a pin object specifying the pin to use for SDA.
4966
- *freq* should be an integer which sets the maximum frequency
5067
for SCL.
68+
- *timeout* is the maximum time in microseconds to wait for clock
69+
stretching (SCL held low by another device on the bus), after
70+
which an ``OSError(ETIMEDOUT)`` exception is raised.
5171

5272
General Methods
5373
---------------
@@ -79,7 +99,7 @@ The following methods implement the primitive I2C master bus operations and can
7999
be combined to make any I2C transaction. They are provided if you need more
80100
control over the bus, otherwise the standard methods (see below) can be used.
81101

82-
These methods are available on software I2C only.
102+
These methods are only available on the `machine.SoftI2C` class.
83103

84104
.. method:: I2C.start()
85105

‎docs/library/machine.SPI.rst

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,35 @@ SS (Slave Select), to select a particular device on a bus with which
1111
communication takes place. Management of an SS signal should happen in
1212
user code (via machine.Pin class).
1313

14+
Both hardware and software SPI implementations exist via the
15+
:ref:`machine.SPI <machine.SPI>` and `machine.SoftSPI` classes. Hardware SPI uses underlying
16+
hardware support of the system to perform the reads/writes and is usually
17+
efficient and fast but may have restrictions on which pins can be used.
18+
Software SPI is implemented by bit-banging and can be used on any pin but
19+
is not as efficient. These classes have the same methods available and
20+
differ primarily in the way they are constructed.
21+
1422
Constructors
1523
------------
1624

1725
.. class:: SPI(id, ...)
1826

19-
Construct an SPI object on the given bus, ``id``. Values of ``id`` depend
27+
Construct an SPI object on the given bus, *id*. Values of *id* depend
2028
on a particular port and its hardware. Values 0, 1, etc. are commonly used
21-
to select hardware SPI block #0, #1, etc. Value -1 can be used for
22-
bitbanging (software) implementation of SPI (if supported by a port).
29+
to select hardware SPI block #0, #1, etc.
2330

2431
With no additional parameters, the SPI object is created but not
2532
initialised (it has the settings from the last initialisation of
2633
the bus, if any). If extra arguments are given, the bus is initialised.
2734
See ``init`` for parameters of initialisation.
2835

36+
.. _machine.SoftSPI:
37+
.. class:: SoftSPI(baudrate=500000, *, polarity=0, phase=0, bits=8, firstbit=MSB, sck=None, mosi=None, miso=None)
38+
39+
Construct a new software SPI object. Additional parameters must be
40+
given, usually at least *sck*, *mosi* and *miso*, and these are used
41+
to initialise the bus. See `SPI.init` for a description of the parameters.
42+
2943
Methods
3044
-------
3145

0 commit comments

Comments
 (0)
0