docs: Update I2C and SPI docs to add reference to SoftI2C and SoftSPI.
Signed-off-by: Damien George <damien@micropython.org>
This commit is contained in:
Damien George
parent
71f3ade770
commit
98182a97c5
@ -249,16 +249,15 @@ ESP32 specific ADC class method reference:
|
||||
Software SPI bus
|
||||
----------------
|
||||
|
||||
There are two SPI drivers. One is implemented in software (bit-banging)
|
||||
and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
|
||||
class::
|
||||
Software SPI (using bit-banging) works on all pins, and is accessed via the
|
||||
:ref:`machine.SoftSPI <machine.SoftSPI>` class::
|
||||
|
||||
from machine import Pin, SPI
|
||||
from machine import Pin, SoftSPI
|
||||
|
||||
# construct an SPI bus on the given pins
|
||||
# construct a SoftSPI bus on the given pins
|
||||
# polarity is the idle state of SCK
|
||||
# phase=0 means sample on the first edge of SCK, phase=1 means the second
|
||||
spi = SPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
|
||||
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
|
||||
|
||||
spi.init(baudrate=200000) # set the baudrate
|
||||
|
||||
@ -298,39 +297,54 @@ mosi 13 23
|
||||
miso 12 19
|
||||
===== =========== ============
|
||||
|
||||
Hardware SPI has the same methods as Software SPI above::
|
||||
Hardware SPI is accessed via the :ref:`machine.SPI <machine.SPI>` class and
|
||||
has the same methods as software SPI above::
|
||||
|
||||
from machine import Pin, SPI
|
||||
|
||||
hspi = SPI(1, 10000000, sck=Pin(14), mosi=Pin(13), miso=Pin(12))
|
||||
vspi = SPI(2, baudrate=80000000, polarity=0, phase=0, bits=8, firstbit=0, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
|
||||
|
||||
Software I2C bus
|
||||
----------------
|
||||
|
||||
I2C bus
|
||||
-------
|
||||
Software I2C (using bit-banging) works on all output-capable pins, and is
|
||||
accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
|
||||
|
||||
The I2C driver has both software and hardware implementations, and the two
|
||||
hardware peripherals have identifiers 0 and 1. Any available output-capable
|
||||
pins can be used for SCL and SDA. The driver is accessed via the
|
||||
:ref:`machine.I2C <machine.I2C>` class::
|
||||
from machine import Pin, SoftI2C
|
||||
|
||||
from machine import Pin, I2C
|
||||
i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
|
||||
|
||||
# construct a software I2C bus
|
||||
i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
|
||||
i2c.scan() # scan for devices
|
||||
|
||||
# construct a hardware I2C bus
|
||||
i2c = I2C(0)
|
||||
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
|
||||
|
||||
i2c.scan() # scan for slave devices
|
||||
|
||||
i2c.readfrom(0x3a, 4) # read 4 bytes from slave device with address 0x3a
|
||||
i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a
|
||||
i2c.readfrom(0x3a, 4) # read 4 bytes from device with address 0x3a
|
||||
i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
|
||||
|
||||
buf = bytearray(10) # create a buffer with 10 bytes
|
||||
i2c.writeto(0x3a, buf) # write the given buffer to the slave
|
||||
|
||||
Hardware I2C bus
|
||||
----------------
|
||||
|
||||
There are two hardware I2C peripherals with identifiers 0 and 1. Any available
|
||||
output-capable pins can be used for SCL and SDA but the defaults are given
|
||||
below.
|
||||
|
||||
===== =========== ============
|
||||
\ I2C(0) I2C(1)
|
||||
===== =========== ============
|
||||
scl 18 25
|
||||
sda 19 26
|
||||
===== =========== ============
|
||||
|
||||
The driver is accessed via the :ref:`machine.I2C <machine.I2C>` class and
|
||||
has the same methods as software I2C above::
|
||||
|
||||
from machine import Pin, I2C
|
||||
|
||||
i2c = I2C(0)
|
||||
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
|
||||
|
||||
Real time clock (RTC)
|
||||
---------------------
|
||||
|
||||
|
||||
@ -214,15 +214,15 @@ Software SPI bus
|
||||
----------------
|
||||
|
||||
There are two SPI drivers. One is implemented in software (bit-banging)
|
||||
and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
|
||||
and works on all pins, and is accessed via the :ref:`machine.SoftSPI <machine.SoftSPI>`
|
||||
class::
|
||||
|
||||
from machine import Pin, SPI
|
||||
from machine import Pin, SoftSPI
|
||||
|
||||
# construct an SPI bus on the given pins
|
||||
# polarity is the idle state of SCK
|
||||
# phase=0 means sample on the first edge of SCK, phase=1 means the second
|
||||
spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
|
||||
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
|
||||
|
||||
spi.init(baudrate=200000) # set the baudrate
|
||||
|
||||
@ -258,7 +258,8 @@ I2C bus
|
||||
-------
|
||||
|
||||
The I2C driver is implemented in software and works on all pins,
|
||||
and is accessed via the :ref:`machine.I2C <machine.I2C>` class::
|
||||
and is accessed via the :ref:`machine.I2C <machine.I2C>` class (which is an
|
||||
alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
|
||||
|
||||
from machine import Pin, I2C
|
||||
|
||||
|
||||
@ -12,6 +12,14 @@ when created, or initialised later on.
|
||||
|
||||
Printing the I2C object gives you information about its configuration.
|
||||
|
||||
Both hardware and software I2C implementations exist via the
|
||||
:ref:`machine.I2C <machine.I2C>` and `machine.SoftI2C` classes. Hardware I2C uses
|
||||
underlying hardware support of the system to perform the reads/writes and is
|
||||
usually efficient and fast but may have restrictions on which pins can be used.
|
||||
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.
|
||||
|
||||
Example usage::
|
||||
|
||||
from machine import I2C
|
||||
@ -33,22 +41,34 @@ Example usage::
|
||||
Constructors
|
||||
------------
|
||||
|
||||
.. class:: I2C(id=-1, *, scl, sda, freq=400000)
|
||||
.. class:: I2C(id, *, scl, sda, freq=400000)
|
||||
|
||||
Construct and return a new I2C object using the following parameters:
|
||||
|
||||
- *id* identifies a particular I2C peripheral. The default
|
||||
value of -1 selects a software implementation of I2C which can
|
||||
work (in most cases) with arbitrary pins for SCL and SDA.
|
||||
If *id* is -1 then *scl* and *sda* must be specified. Other
|
||||
allowed values for *id* depend on the particular port/board,
|
||||
and specifying *scl* and *sda* may or may not be required or
|
||||
allowed in this case.
|
||||
- *id* identifies a particular I2C peripheral. Allowed values for
|
||||
depend on the particular port/board
|
||||
- *scl* should be a pin object specifying the pin to use for SCL.
|
||||
- *sda* should be a pin object specifying the pin to use for SDA.
|
||||
- *freq* should be an integer which sets the maximum frequency
|
||||
for SCL.
|
||||
|
||||
Note that some ports/boards will have default values of *scl* and *sda*
|
||||
that can be changed in this constructor. Others will have fixed values
|
||||
of *scl* and *sda* that cannot be changed.
|
||||
|
||||
.. _machine.SoftI2C:
|
||||
.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=255)
|
||||
|
||||
Construct a new software I2C object. The parameters are:
|
||||
|
||||
- *scl* should be a pin object specifying the pin to use for SCL.
|
||||
- *sda* should be a pin object specifying the pin to use for SDA.
|
||||
- *freq* should be an integer which sets the maximum frequency
|
||||
for SCL.
|
||||
- *timeout* is the maximum time in microseconds to wait for clock
|
||||
stretching (SCL held low by another device on the bus), after
|
||||
which an ``OSError(ETIMEDOUT)`` exception is raised.
|
||||
|
||||
General Methods
|
||||
---------------
|
||||
|
||||
@ -79,7 +99,7 @@ The following methods implement the primitive I2C master bus operations and can
|
||||
be combined to make any I2C transaction. They are provided if you need more
|
||||
control over the bus, otherwise the standard methods (see below) can be used.
|
||||
|
||||
These methods are available on software I2C only.
|
||||
These methods are only available on the `machine.SoftI2C` class.
|
||||
|
||||
.. method:: I2C.start()
|
||||
|
||||
|
||||
@ -11,21 +11,35 @@ SS (Slave Select), to select a particular device on a bus with which
|
||||
communication takes place. Management of an SS signal should happen in
|
||||
user code (via machine.Pin class).
|
||||
|
||||
Both hardware and software SPI implementations exist via the
|
||||
:ref:`machine.SPI <machine.SPI>` and `machine.SoftSPI` classes. Hardware SPI uses underlying
|
||||
hardware support of the system to perform the reads/writes and is usually
|
||||
efficient and fast but may have restrictions on which pins can be used.
|
||||
Software SPI 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.
|
||||
|
||||
Constructors
|
||||
------------
|
||||
|
||||
.. class:: SPI(id, ...)
|
||||
|
||||
Construct an SPI object on the given bus, ``id``. Values of ``id`` depend
|
||||
Construct an SPI object on the given bus, *id*. Values of *id* depend
|
||||
on a particular port and its hardware. Values 0, 1, etc. are commonly used
|
||||
to select hardware SPI block #0, #1, etc. Value -1 can be used for
|
||||
bitbanging (software) implementation of SPI (if supported by a port).
|
||||
to select hardware SPI block #0, #1, etc.
|
||||
|
||||
With no additional parameters, the SPI object is created but not
|
||||
initialised (it has the settings from the last initialisation of
|
||||
the bus, if any). If extra arguments are given, the bus is initialised.
|
||||
See ``init`` for parameters of initialisation.
|
||||
|
||||
.. _machine.SoftSPI:
|
||||
.. class:: SoftSPI(baudrate=500000, *, polarity=0, phase=0, bits=8, firstbit=MSB, sck=None, mosi=None, miso=None)
|
||||
|
||||
Construct a new software SPI object. Additional parameters must be
|
||||
given, usually at least *sck*, *mosi* and *miso*, and these are used
|
||||
to initialise the bus. See `SPI.init` for a description of the parameters.
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user