From fdd5b18133e9d9f5a4e76be22ece6632d11d7fee Mon Sep 17 00:00:00 2001 From: David P Date: Sat, 12 Jun 2021 14:51:05 +1000 Subject: [PATCH] docs: Replace master/slave with controller/peripheral in I2C and SPI. See https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names --- docs/esp32/quickref.rst | 2 +- docs/esp8266/quickref.rst | 6 ++-- docs/library/machine.I2C.rst | 38 ++++++++++----------- docs/library/machine.I2S.rst | 2 +- docs/library/machine.SPI.rst | 14 ++++---- docs/library/pyb.I2C.rst | 54 +++++++++++++++--------------- docs/library/pyb.SPI.rst | 20 +++++------ docs/pyboard/quickref.rst | 12 +++---- docs/pyboard/tutorial/amp_skin.rst | 2 +- docs/pyboard/tutorial/lcd_skin.rst | 6 ++-- docs/rp2/quickref.rst | 2 +- docs/wipy/quickref.rst | 14 ++++---- 12 files changed, 86 insertions(+), 86 deletions(-) diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst index 0b825d52080a..56c372114820 100644 --- a/docs/esp32/quickref.rst +++ b/docs/esp32/quickref.rst @@ -361,7 +361,7 @@ accessed via the :ref:`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 ---------------- diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index bc648a348a88..72b35966978e 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -270,11 +270,11 @@ alias of :ref:`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) --------------------- diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index f9b951564611..f46d64ef51d4 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -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). diff --git a/docs/library/machine.I2S.rst b/docs/library/machine.I2S.rst index 48f03b419d0b..e1c6af990ca6 100644 --- a/docs/library/machine.I2S.rst +++ b/docs/library/machine.I2S.rst @@ -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. diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index 7565241eb1cd..46ac2ec74ceb 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -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 diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index 56b036e07447..f60b506861c3 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -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 diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index c76b16789ad4..1bdb73a5dd17 100644 --- a/docs/library/pyb.SPI.rst +++ b/docs/library/pyb.SPI.rst @@ -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 diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst index 3ea3190999a0..49b67eee425a 100644 --- a/docs/pyboard/quickref.rst +++ b/docs/pyboard/quickref.rst @@ -191,7 +191,7 @@ See :ref:`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 `. diff --git a/docs/pyboard/tutorial/amp_skin.rst b/docs/pyboard/tutorial/amp_skin.rst index bcb583261381..b6558959ead3 100644 --- a/docs/pyboard/tutorial/amp_skin.rst +++ b/docs/pyboard/tutorial/amp_skin.rst @@ -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:: diff --git a/docs/pyboard/tutorial/lcd_skin.rst b/docs/pyboard/tutorial/lcd_skin.rst index 288ac1bf08be..4df0041607c7 100644 --- a/docs/pyboard/tutorial/lcd_skin.rst +++ b/docs/pyboard/tutorial/lcd_skin.rst @@ -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 `__. diff --git a/docs/rp2/quickref.rst b/docs/rp2/quickref.rst index 4c8c02dc0cc5..c18eb4a0b902 100644 --- a/docs/rp2/quickref.rst +++ b/docs/rp2/quickref.rst @@ -181,7 +181,7 @@ accessed via the :ref:`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 ---------------- diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index a22ea45b5514..f9ea3d501ed4 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -107,8 +107,8 @@ See :ref:`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 `. :: 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) --------------------