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

david-poirier · dpgeorge · commit fdd5b18133e9 · 2021-07-18T11:19:44.000+10:00
See https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -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
 ----------------
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
@@ -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)
 ---------------------
diff --git 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,34 +126,34 @@ 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.
 
    The method returns ``None``.
 
 .. 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.
    The function returns the number of ACKs that were received.
 
 .. 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
@@ -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
@@ -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
@@ -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,17 +88,17 @@ 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
        errors properly)
 
 .. 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,15 +124,15 @@ 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)
 
    Receive data on the bus:
 
      - ``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,23 +143,23 @@ 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``.
 
 .. 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
@@ -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
@@ -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>`.
 
diff --git 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
diff --git a/docs/rp2/quickref.rst b/docs/rp2/quickref.rst
diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst
