From 98182a97c5a9229938406beb722966eacceeb823 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 29 Sep 2020 16:50:23 +1000 Subject: [PATCH] docs: Update I2C and SPI docs to add reference to SoftI2C and SoftSPI. Signed-off-by: Damien George --- docs/esp32/quickref.rst | 62 ++++++++++++++++++++++-------------- docs/esp8266/quickref.rst | 9 +++--- docs/library/machine.I2C.rst | 38 ++++++++++++++++------ docs/library/machine.SPI.rst | 20 ++++++++++-- 4 files changed, 89 insertions(+), 40 deletions(-) diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst index d5c222f3a1..79e61a10b6 100644 --- a/docs/esp32/quickref.rst +++ b/docs/esp32/quickref.rst @@ -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 ` -class:: +Software SPI (using bit-banging) works on all pins, and is accessed via the +:ref:`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 ` 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 ` 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 ` 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 ` 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) --------------------- diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index c884d93fc9..1a22bd50a5 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -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 ` +and works on all pins, and is accessed via the :ref:`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 ` class:: +and is accessed via the :ref:`machine.I2C ` class (which is an +alias of :ref:`machine.SoftI2C `):: from machine import Pin, I2C diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 743554bc76..f9b9515646 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -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 ` 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() diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index ea460a7b81..7565241eb1 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -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 ` 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 -------