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:
parent
71f3ade770
commit
98182a97c5
docs
|
@ -249,16 +249,15 @@ ESP32 specific ADC class method reference:
|
||||||
Software SPI bus
|
Software SPI bus
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
There are two SPI drivers. One is implemented in software (bit-banging)
|
Software SPI (using bit-banging) works on all pins, and is accessed via the
|
||||||
and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
|
:ref:`machine.SoftSPI <machine.SoftSPI>` class::
|
||||||
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
|
# polarity is the idle state of SCK
|
||||||
# phase=0 means sample on the first edge of SCK, phase=1 means the second
|
# 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
|
spi.init(baudrate=200000) # set the baudrate
|
||||||
|
|
||||||
|
@ -298,39 +297,54 @@ mosi 13 23
|
||||||
miso 12 19
|
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
|
from machine import Pin, SPI
|
||||||
|
|
||||||
hspi = SPI(1, 10000000, sck=Pin(14), mosi=Pin(13), miso=Pin(12))
|
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))
|
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
|
from machine import Pin, SoftI2C
|
||||||
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, I2C
|
i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
|
||||||
|
|
||||||
# construct a software I2C bus
|
i2c.scan() # scan for devices
|
||||||
i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
|
|
||||||
|
|
||||||
# construct a hardware I2C bus
|
i2c.readfrom(0x3a, 4) # read 4 bytes from device with address 0x3a
|
||||||
i2c = I2C(0)
|
i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
|
||||||
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
|
|
||||||
|
|
||||||
buf = bytearray(10) # create a buffer with 10 bytes
|
buf = bytearray(10) # create a buffer with 10 bytes
|
||||||
i2c.writeto(0x3a, buf) # write the given buffer to the slave
|
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)
|
Real time clock (RTC)
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
|
|
@ -214,15 +214,15 @@ Software SPI bus
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
There are two SPI drivers. One is implemented in software (bit-banging)
|
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::
|
class::
|
||||||
|
|
||||||
from machine import Pin, SPI
|
from machine import Pin, SoftSPI
|
||||||
|
|
||||||
# construct an SPI bus on the given pins
|
# construct an SPI bus on the given pins
|
||||||
# polarity is the idle state of SCK
|
# polarity is the idle state of SCK
|
||||||
# phase=0 means sample on the first edge of SCK, phase=1 means the second
|
# 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
|
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,
|
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
|
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.
|
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::
|
Example usage::
|
||||||
|
|
||||||
from machine import I2C
|
from machine import I2C
|
||||||
|
@ -33,22 +41,34 @@ Example usage::
|
||||||
Constructors
|
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:
|
Construct and return a new I2C object using the following parameters:
|
||||||
|
|
||||||
- *id* identifies a particular I2C peripheral. The default
|
- *id* identifies a particular I2C peripheral. Allowed values for
|
||||||
value of -1 selects a software implementation of I2C which can
|
depend on the particular port/board
|
||||||
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.
|
|
||||||
- *scl* should be a pin object specifying the pin to use for SCL.
|
- *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.
|
- *sda* should be a pin object specifying the pin to use for SDA.
|
||||||
- *freq* should be an integer which sets the maximum frequency
|
- *freq* should be an integer which sets the maximum frequency
|
||||||
for SCL.
|
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
|
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
|
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.
|
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()
|
.. 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
|
communication takes place. Management of an SS signal should happen in
|
||||||
user code (via machine.Pin class).
|
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
|
Constructors
|
||||||
------------
|
------------
|
||||||
|
|
||||||
.. class:: SPI(id, ...)
|
.. 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
|
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
|
to select hardware SPI block #0, #1, etc.
|
||||||
bitbanging (software) implementation of SPI (if supported by a port).
|
|
||||||
|
|
||||||
With no additional parameters, the SPI object is created but not
|
With no additional parameters, the SPI object is created but not
|
||||||
initialised (it has the settings from the last initialisation of
|
initialised (it has the settings from the last initialisation of
|
||||||
the bus, if any). If extra arguments are given, the bus is initialised.
|
the bus, if any). If extra arguments are given, the bus is initialised.
|
||||||
See ``init`` for parameters of initialisation.
|
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
|
Methods
|
||||||
-------
|
-------
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue