mirrors
/
micropython
mirror of https://github.com/micropython/micropython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Replace master/slave with controller/peripheral in I2C and SPI. 

See https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names
This commit is contained in:
David P 2021-06-12 14:51:05 +10:00 committed by Damien George
parent cbc8d5b61f
commit fdd5b18133
12 changed files with 86 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/esp32/quickref.rst
View File

@ -361,7 +361,7 @@ accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
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
i2c.writeto(0x3a, buf) # write the given buffer to the peripheral
Hardware I2C bus
----------------

6
docs/esp8266/quickref.rst
View File

@ -270,11 +270,11 @@ alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
# construct an I2C bus
i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
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 peripheral device with address 0x3a
i2c.writeto(0x3a, '12') # write '12' to peripheral device with address 0x3a
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 peripheral
Real time clock (RTC)
---------------------

38
docs/library/machine.I2C.rst
View File

@ -28,15 +28,15 @@ Example usage::
# depending on the port, extra parameters may be required
# to select the peripheral and/or pins to use
i2c.scan() # scan for slaves, returning a list of 7-bit addresses
i2c.scan() # scan for peripherals, returning a list of 7-bit addresses
i2c.writeto(42, b'123') # write 3 bytes to slave with 7-bit address 42
i2c.readfrom(42, 4) # read 4 bytes from slave with 7-bit address 42
i2c.writeto(42, b'123') # write 3 bytes to peripheral with 7-bit address 42
i2c.readfrom(42, 4) # read 4 bytes from peripheral with 7-bit address 42
i2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of slave 42,
# starting at memory-address 8 in the slave
i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42
# starting at address 2 in the slave
i2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of peripheral 42,
# starting at memory-address 8 in the peripheral
i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of peripheral 42
# starting at address 2 in the peripheral
Constructors
------------
@ -95,7 +95,7 @@ General Methods
Primitive I2C operations
------------------------
The following methods implement the primitive I2C master bus operations and can
The following methods implement the primitive I2C controller 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.
@ -115,7 +115,7 @@ These methods are only available on the `machine.SoftI2C` class.
read is the length of *buf*. An ACK will be sent on the bus after
receiving all but the last byte. After the last byte is received, if *nack*
is true then a NACK will be sent, otherwise an ACK will be sent (and in this
case the slave assumes more bytes are going to be read in a later call).
case the peripheral assumes more bytes are going to be read in a later call).
.. method:: I2C.write(buf)
@ -126,18 +126,18 @@ These methods are only available on the `machine.SoftI2C` class.
Standard bus operations
-----------------------
The following methods implement the standard I2C master read and write
operations that target a given slave device.
The following methods implement the standard I2C controller read and write
operations that target a given peripheral device.
.. method:: I2C.readfrom(addr, nbytes, stop=True, /)
Read *nbytes* from the slave specified by *addr*.
Read *nbytes* from the peripheral specified by *addr*.
If *stop* is true then a STOP condition is generated at the end of the transfer.
Returns a `bytes` object with the data read.
.. method:: I2C.readfrom_into(addr, buf, stop=True, /)
Read into *buf* from the slave specified by *addr*.
Read into *buf* from the peripheral specified by *addr*.
The number of bytes read will be the length of *buf*.
If *stop* is true then a STOP condition is generated at the end of the transfer.
@ -145,7 +145,7 @@ operations that target a given slave device.
.. method:: I2C.writeto(addr, buf, stop=True, /)
Write the bytes from *buf* to the slave specified by *addr*. If a
Write the bytes from *buf* to the peripheral specified by *addr*. If a
NACK is received following the write of a byte from *buf* then the
remaining bytes are not sent. If *stop* is true then a STOP condition is
generated at the end of the transfer, even if a NACK is received.
@ -153,7 +153,7 @@ operations that target a given slave device.
.. method:: I2C.writevto(addr, vector, stop=True, /)
Write the bytes contained in *vector* to the slave specified by *addr*.
Write the bytes contained in *vector* to the peripheral specified by *addr*.
*vector* should be a tuple or list of objects with the buffer protocol.
The *addr* is sent once and then the bytes from each object in *vector*
are written out sequentially. The objects in *vector* may be zero bytes
@ -170,19 +170,19 @@ Memory operations
Some I2C devices act as a memory device (or set of registers) that can be read
from and written to. In this case there are two addresses associated with an
I2C transaction: the slave address and the memory address. The following
I2C transaction: the peripheral address and the memory address. The following
methods are convenience functions to communicate with such devices.
.. method:: I2C.readfrom_mem(addr, memaddr, nbytes, *, addrsize=8)
Read *nbytes* from the slave specified by *addr* starting from the memory
Read *nbytes* from the peripheral specified by *addr* starting from the memory
address specified by *memaddr*.
The argument *addrsize* specifies the address size in bits.
Returns a `bytes` object with the data read.
.. method:: I2C.readfrom_mem_into(addr, memaddr, buf, *, addrsize=8)
Read into *buf* from the slave specified by *addr* starting from the
Read into *buf* from the peripheral specified by *addr* starting from the
memory address specified by *memaddr*. The number of bytes read is the
length of *buf*.
The argument *addrsize* specifies the address size in bits (on ESP8266
@ -192,7 +192,7 @@ methods are convenience functions to communicate with such devices.
.. method:: I2C.writeto_mem(addr, memaddr, buf, *, addrsize=8)
Write *buf* to the slave specified by *addr* starting from the
Write *buf* to the peripheral specified by *addr* starting from the
memory address specified by *memaddr*.
The argument *addrsize* specifies the address size in bits (on ESP8266
this argument is not recognised and the address size is always 8 bits).

2
docs/library/machine.I2S.rst
View File

@ -6,7 +6,7 @@ class I2S -- Inter-IC Sound bus protocol
I2S is a synchronous serial protocol used to connect digital audio devices.
At the physical level, a bus consists of 3 lines: SCK, WS, SD.
The I2S class supports Master operation. Slave operation is not supported.
The I2S class supports controller operation. Peripheral operation is not supported.
The I2S class is currently available as a Technical Preview. During the preview period, feedback from
users is encouraged. Based on this feedback, the I2S class API and implementation may be changed.

14
docs/library/machine.SPI.rst
View File

@ -1,14 +1,14 @@
.. currentmodule:: machine
.. _machine.SPI:
class SPI -- a Serial Peripheral Interface bus protocol (master side)
=====================================================================
class SPI -- a Serial Peripheral Interface bus protocol (controller side)
=========================================================================
SPI is a synchronous serial protocol that is driven by a master. At the
SPI is a synchronous serial protocol that is driven by a controller. At the
physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices
can share the same bus. Each device should have a separate, 4th signal,
SS (Slave Select), to select a particular device on a bus with which
communication takes place. Management of an SS signal should happen in
CS (Chip Select), to select a particular device on a bus with which
communication takes place. Management of a CS signal should happen in
user code (via machine.Pin class).
Both hardware and software SPI implementations exist via the
@ -102,9 +102,9 @@ Methods
Constants
---------
.. data:: SPI.MASTER
.. data:: SPI.CONTROLLER
for initialising the SPI bus to master; this is only used for the WiPy
for initialising the SPI bus to controller; this is only used for the WiPy
.. data:: SPI.MSB

54
docs/library/pyb.I2C.rst
View File

@ -14,11 +14,11 @@ Example::
from pyb import I2C
i2c = I2C(1) # create on bus 1
i2c = I2C(1, I2C.MASTER) # create and init as a master
i2c.init(I2C.MASTER, baudrate=20000) # init as a master
i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address
i2c.deinit() # turn off the peripheral
i2c = I2C(1) # create on bus 1
i2c = I2C(1, I2C.CONTROLLER) # create and init as a controller
i2c.init(I2C.CONTROLLER, baudrate=20000) # init as a controller
i2c.init(I2C.PERIPHERAL, addr=0x42) # init as a peripheral with given address
i2c.deinit() # turn off the I2C unit
Printing the i2c object gives you information about its configuration.
@ -37,21 +37,21 @@ You can specify a timeout (in ms)::
i2c.send(b'123', timeout=2000) # timeout after 2 seconds
A master must specify the recipient's address::
A controller must specify the recipient's address::
i2c.init(I2C.MASTER)
i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42
i2c.init(I2C.CONTROLLER)
i2c.send('123', 0x42) # send 3 bytes to peripheral with address 0x42
i2c.send(b'456', addr=0x42) # keyword for address
Master also has other methods::
i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning
i2c.is_ready(0x42) # check if peripheral 0x42 is ready
i2c.scan() # scan for peripherals on the bus, returning
# a list of valid addresses
i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42,
# starting at address 2 in the slave
i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of slave 0x42
# starting at address 2 in the slave, timeout after 1 second
i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of peripheral 0x42,
# starting at address 2 in the peripheral
i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of peripheral 0x42
# starting at address 2 in the peripheral, timeout after 1 second
Constructors
------------
@ -88,9 +88,9 @@ Methods
Initialise the I2C bus with the given parameters:
- ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE``
- ``addr`` is the 7-bit address (only sensible for a slave)
- ``baudrate`` is the SCL clock rate (only sensible for a master)
- ``mode`` must be either ``I2C.CONTROLLER`` or ``I2C.PERIPHERAL``
- ``addr`` is the 7-bit address (only sensible for a peripheral)
- ``baudrate`` is the SCL clock rate (only sensible for a controller)
- ``gencall`` is whether to support general call mode
- ``dma`` is whether to allow the use of DMA for the I2C transfers (note
that DMA transfers have more precise timing but currently do not handle bus
@ -98,7 +98,7 @@ Methods
.. method:: I2C.is_ready(addr)
Check if an I2C device responds to the given address. Only valid when in master mode.
Check if an I2C device responds to the given address. Only valid when in controller mode.
.. method:: I2C.mem_read(data, addr, memaddr, *, timeout=5000, addr_size=8)
@ -111,7 +111,7 @@ Methods
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns the read data.
This is only valid in master mode.
This is only valid in controller mode.
.. method:: I2C.mem_write(data, addr, memaddr, *, timeout=5000, addr_size=8)
@ -124,7 +124,7 @@ Methods
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns ``None``.
This is only valid in master mode.
This is only valid in controller mode.
.. method:: I2C.recv(recv, addr=0x00, *, timeout=5000)
@ -132,7 +132,7 @@ Methods
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes
- ``addr`` is the address to receive from (only required in master mode)
- ``addr`` is the address to receive from (only required in controller mode)
- ``timeout`` is the timeout in milliseconds to wait for the receive
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
@ -143,7 +143,7 @@ Methods
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object)
- ``addr`` is the address to send to (only required in master mode)
- ``addr`` is the address to send to (only required in controller mode)
- ``timeout`` is the timeout in milliseconds to wait for the send
Return value: ``None``.
@ -151,15 +151,15 @@ Methods
.. method:: I2C.scan()
Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
Only valid when in master mode.
Only valid when in controller mode.
Constants
---------
.. data:: I2C.MASTER
.. data:: I2C.CONTROLLER
for initialising the bus to master mode
for initialising the bus to controller mode
.. data:: I2C.SLAVE
.. data:: I2C.PERIPHERAL
for initialising the bus to slave mode
for initialising the bus to peripheral mode

20
docs/library/pyb.SPI.rst
View File

@ -1,19 +1,19 @@
.. currentmodule:: pyb
.. _pyb.SPI:
class SPI -- a master-driven serial protocol
============================================
class SPI -- a controller-driven serial protocol
================================================
SPI is a serial protocol that is driven by a master. At the physical level
SPI is a serial protocol that is driven by a controller. At the physical level
there are 3 lines: SCK, MOSI, MISO.
See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
spi = SPI(1, SPI.CONTROLLER, baudrate=600000, polarity=1, phase=0, crc=0x7)
Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be
Only required parameter is mode, SPI.CONTROLLER or SPI.PERIPHERAL. Polarity can be
0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1
to sample data on the first or second clock edge respectively. Crc can be
None for no CRC, or a polynomial specifier.
@ -55,8 +55,8 @@ Methods
Initialise the SPI bus with the given parameters:
- ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
- ``baudrate`` is the SCK clock rate (only sensible for a master).
- ``mode`` must be either ``SPI.CONTROLLER`` or ``SPI.PERIPHERAL``.
- ``baudrate`` is the SCK clock rate (only sensible for a controller).
- ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
use of ``prescaler`` overrides ``baudrate``.
- ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
@ -112,10 +112,10 @@ Methods
Constants
---------
.. data:: SPI.MASTER
.. data:: SPI.SLAVE
.. data:: SPI.CONTROLLER
.. data:: SPI.PERIPHERAL
for initialising the SPI bus to master or slave mode
for initialising the SPI bus to controller or peripheral mode
.. data:: SPI.LSB
.. data:: SPI.MSB

12
docs/pyboard/quickref.rst
View File

@ -191,7 +191,7 @@ See :ref:`pyb.SPI <pyb.SPI>`. ::
from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=1, phase=0)
spi = SPI(1, SPI.CONTROLLER, baudrate=200000, polarity=1, phase=0)
spi.send('hello')
spi.recv(5) # receive 5 bytes on the bus
spi.send_recv('hello') # send and receive 5 bytes
@ -210,12 +210,12 @@ eg ``I2C(1)``. Software I2C is also available by explicitly specifying the
i2c = I2C('X', freq=400000) # create hardware I2c object
i2c = I2C(scl='X1', sda='X2', freq=100000) # create software I2C object
i2c.scan() # returns list of slave addresses
i2c.writeto(0x42, 'hello') # write 5 bytes to slave with address 0x42
i2c.readfrom(0x42, 5) # read 5 bytes from slave
i2c.scan() # returns list of peripheral addresses
i2c.writeto(0x42, 'hello') # write 5 bytes to peripheral with address 0x42
i2c.readfrom(0x42, 5) # read 5 bytes from peripheral
i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from slave 0x42, slave memory 0x10
i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to slave 0x42, slave memory 0x10
i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from peripheral 0x42, peripheral memory 0x10
i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to peripheral 0x42, peripheral memory 0x10
Note: for legacy I2C support see :ref:`pyb.I2C <pyb.I2C>`.

2
docs/pyboard/tutorial/amp_skin.rst
View File

@ -30,7 +30,7 @@ To set the volume, define the following function::
import pyb
def volume(val):
pyb.I2C(1, pyb.I2C.MASTER).mem_write(val, 46, 0)
pyb.I2C(1, pyb.I2C.CONTROLLER).mem_write(val, 46, 0)
Then you can do::

6
docs/pyboard/tutorial/lcd_skin.rst
View File

@ -51,7 +51,7 @@ MPR121 capacitive touch sensor has address 90.
To get started, try::
>>> import pyb
>>> i2c = pyb.I2C(1, pyb.I2C.MASTER)
>>> i2c = pyb.I2C(1, pyb.I2C.CONTROLLER)
>>> i2c.mem_write(4, 90, 0x5e)
>>> touch = i2c.mem_read(1, 90, 0)[0]
@ -68,7 +68,7 @@ directory or ``lib/`` directory) and then try::
>>> import pyb
>>> import mpr121
>>> m = mpr121.MPR121(pyb.I2C(1, pyb.I2C.MASTER))
>>> m = mpr121.MPR121(pyb.I2C(1, pyb.I2C.CONTROLLER))
>>> for i in range(100):
... print(m.touch_status())
... pyb.delay(100)
@ -80,7 +80,7 @@ Try touching each one in turn.
Note that if you put the LCD skin in the Y-position, then you need to
initialise the I2C bus using::
>>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER))
>>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.CONTROLLER))
There is also a demo which uses the LCD and the touch sensors together,
and can be found `here <http://micropython.org/resources/examples/lcddemo.py>`__.

2
docs/rp2/quickref.rst
View File

@ -181,7 +181,7 @@ accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
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
i2c.writeto(0x3a, buf) # write the given buffer to the peripheral
Hardware I2C bus
----------------

14
docs/wipy/quickref.rst
View File

@ -107,8 +107,8 @@ See :ref:`machine.SPI <machine.SPI>`. ::
from machine import SPI
# configure the SPI master @ 2MHz
spi = SPI(0, SPI.MASTER, baudrate=200000, polarity=0, phase=0)
# configure the SPI controller @ 2MHz
spi = SPI(0, SPI.CONTROLLER, baudrate=2_000_000, polarity=0, phase=0)
spi.write('hello')
spi.read(5) # receive 5 bytes on the bus
rbuf = bytearray(5)
@ -122,11 +122,11 @@ See :ref:`machine.I2C <machine.I2C>`. ::
from machine import I2C
# configure the I2C bus
i2c = I2C(baudrate=100000)
i2c.scan() # returns list of slave addresses
i2c.writeto(0x42, 'hello') # send 5 bytes to slave with address 0x42
i2c.readfrom(0x42, 5) # receive 5 bytes from slave
i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from slave 0x42, slave memory 0x10
i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to slave 0x42, slave memory 0x10
i2c.scan() # returns list of peripheral addresses
i2c.writeto(0x42, 'hello') # send 5 bytes to peripheral with address 0x42
i2c.readfrom(0x42, 5) # receive 5 bytes from peripheral
i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from peripheral 0x42, peripheral memory 0x10
i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to peripheral 0x42, peripheral memory 0x10
Watchdog timer (WDT)
--------------------