docs: Update I2C and UART docs to match the new API.

docs/library/pyb.I2C.rst

@@ -27,43 +27,62 @@ when created, or initialised later on.
 
         from pyb import I2C
 
-        i2c = I2C(1)                         # create on bus 1
+        i2c = I2C(0)                         # create on bus 0
-        i2c = I2C(1, I2C.MASTER)             # create and init as a master
+        i2c = I2C(0, I2C.MASTER)             # create and init as a master
         i2c.init(I2C.MASTER, baudrate=20000) # init as a master
         i2c.deinit()                         # turn off the peripheral
 
 Printing the i2c object gives you information about its configuration.
 
-The basic methods are send and recv::
+.. only:: port_pyboard
 
-    i2c.send('abc')      # send 3 bytes
+    The basic methods are send and recv::
-    i2c.send(0x42)       # send a single byte, given by the number
-    data = i2c.recv(3)   # receive 3 bytes
 
-To receive inplace, first create a bytearray::
+        i2c.send('abc')      # send 3 bytes
+        i2c.send(0x42)       # send a single byte, given by the number
+        data = i2c.recv(3)   # receive 3 bytes
     
-    data = bytearray(3)  # create a buffer
+    To receive inplace, first create a bytearray::
-    i2c.recv(data)       # receive 3 bytes, writing them into data
 
-You can specify a timeout (in ms)::
+        data = bytearray(3)  # create a buffer
+        i2c.recv(data)       # receive 3 bytes, writing them into data
 
-    i2c.send(b'123', timeout=2000)   # timout after 2 seconds
+    You can specify a timeout (in ms)::
 
-A master must specify the recipient's address::
+        i2c.send(b'123', timeout=2000)   # timout after 2 seconds
 
-    i2c.init(I2C.MASTER)
+    A master must specify the recipient's address::
-    i2c.send('123', 0x42)        # send 3 bytes to slave with address 0x42
-    i2c.send(b'456', addr=0x42)  # keyword for address
 
-Master also has other methods::
+        i2c.init(I2C.MASTER)
+        i2c.send('123', 0x42)        # send 3 bytes to slave with address 0x42
+        i2c.send(b'456', addr=0x42)  # keyword for address
 
-    i2c.is_ready(0x42)           # check if slave 0x42 is ready
+    Master also has other methods::
-    i2c.scan()                   # scan for slaves on the bus, returning
+
-                                 #   a list of valid addresses
+        i2c.is_ready(0x42)           # check if slave 0x42 is ready
-    i2c.mem_read(3, 0x42, 2)     # read 3 bytes from memory of slave 0x42,
+        i2c.scan()                   # scan for slaves on the bus, returning
-                                 #   starting at address 2 in the slave
+                                     #   a list of valid addresses
-    i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of slave 0x42
+        i2c.mem_read(3, 0x42, 2)     # read 3 bytes from memory of slave 0x42,
-                                                # starting at address 2 in the slave, timeout after 1 second
+                                     #   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
+
+.. only:: port_wipy
+
+    A master must specify the recipient's address::
+
+        i2c.init(I2C.MASTER)
+        i2c.writeto(0x42, '123')        # send 3 bytes to slave with address 0x42
+        i2c.writeto(addr=0x42, b'456')  # keyword for address
+
+    Master also has other methods::
+
+        i2c.scan()                          # scan for slaves on the bus, returning
+                                            #   a list of valid addresses
+        i2c.readfrom_mem(0x42, 2, 3)        # read 3 bytes from memory of slave 0x42,
+                                            #   starting at address 2 in the slave
+        i2c.writeto_mem(0x42, 2, 'abc')     # write 'abc' (3 bytes) to memory of slave 0x42
+                                            # starting at address 2 in the slave, timeout after 1 second
 
 Constructors
 ------------
@@ -87,12 +106,8 @@ Constructors
 
     .. class:: pyb.I2C(bus, ...)
 
-       Construct an I2C object on the given bus.  `bus` can only be 1.
+       Construct an I2C object on the given bus.  `bus` can only be 0.
-       With no additional parameters, the I2C object is created but not
+       If the bus is not given, the default one will be selected (0).
-       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.
-
 
 Methods
 -------
@@ -103,7 +118,7 @@ Methods
 
 .. only:: port_pyboard
 
-   .. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False)
+    .. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False)
 
       Initialise the I2C bus with the given parameters:
 
@@ -112,72 +127,110 @@ Methods
          - ``baudrate`` is the SCL clock rate (only sensible for a master)
          - ``gencall`` is whether to support general call mode
 
+    .. method:: i2c.is_ready(addr)
+
+       Check if an I2C device responds to the given address.  Only valid when in master mode.
+
+    .. method:: i2c.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+
+       Read from the memory of an I2C device:
+
+         - ``data`` can be an integer (number of bytes to read) or a buffer to read into
+         - ``addr`` is the I2C device address
+         - ``memaddr`` is the memory location within the I2C device
+         - ``timeout`` is the timeout in milliseconds to wait for the read
+         - ``addr_size`` selects width of memaddr: 8 or 16 bits
+
+       Returns the read data.
+       This is only valid in master mode.
+
+    .. method:: i2c.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+
+       Write to the memory of an I2C device:
+
+         - ``data`` can be an integer or a buffer to write from
+         - ``addr`` is the I2C device address
+         - ``memaddr`` is the memory location within the I2C device
+         - ``timeout`` is the timeout in milliseconds to wait for the write
+         - ``addr_size`` selects width of memaddr: 8 or 16 bits
+
+       Returns ``None``.
+       This is only valid in master 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)
+         - ``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,
+       otherwise the same buffer that was passed in to ``recv``.
+
+    .. method:: i2c.send(send, addr=0x00, \*, timeout=5000)
+
+       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)
+         - ``timeout`` is the timeout in milliseconds to wait for the send
+
+       Return value: ``None``.
+
 .. only:: port_wipy
 
-   .. method:: i2c.init(mode, \*, baudrate=100000)
+    .. method:: i2c.init(mode, \*, baudrate=100000)
 
       Initialise the I2C bus with the given parameters:
 
          - ``mode`` must be ``I2C.MASTER``
          - ``baudrate`` is the SCL clock rate
 
-.. method:: i2c.is_ready(addr)
+    .. method:: i2c.readfrom(addr, nbytes)
 
-   Check if an I2C device responds to the given address.  Only valid when in master mode.
+        Read ``nbytes`` from the slave specified by ``addr``.
+        Returns a ``bytes`` object with the data read.
 
-.. method:: i2c.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+    .. method:: i2c.readfrom_into(addr, buf)
 
-   Read from the memory of an I2C device:
+        Read into ``buf`` from the slave specified by ``addr``.
+        Returns the number of bytes read.
 
-     - ``data`` can be an integer (number of bytes to read) or a buffer to read into
+    .. method:: i2c.writeto(addr, buf, \*, stop=True)
-     - ``addr`` is the I2C device address
-     - ``memaddr`` is the memory location within the I2C device
-     - ``timeout`` is the timeout in milliseconds to wait for the read
-     - ``addr_size`` selects width of memaddr: 8 or 16 bits
 
-   Returns the read data.
+        Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
-   This is only valid in master mode.
+        if the transfer should be continued.
+        Returns the number of bytes written.
 
-.. method:: i2c.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+    .. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
 
-   Write to the memory of an I2C device:
+        Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
+        address specified by ``memaddr``.
+        Param ``addrsize`` specifies the address size in bits.
+        Returns a ``bytes`` object with the data read.
 
-     - ``data`` can be an integer or a buffer to write from
+    .. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
-     - ``addr`` is the I2C device address
-     - ``memaddr`` is the memory location within the I2C device
-     - ``timeout`` is the timeout in milliseconds to wait for the write
-     - ``addr_size`` selects width of memaddr: 8 or 16 bits
 
-   Returns ``None``.
+        Read into ``buf`` from the slave specified by ``addr`` starting from the memory
-   This is only valid in master mode.
+        address specified by ``memaddr``.
+        Param ``addrsize`` specifies the address size in bits.
+        Returns the number of bytes read.
 
-.. method:: i2c.recv(recv, addr=0x00, \*, timeout=5000)
+    .. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
 
-   Receive data on the bus:
+        Write ``buf`` to the slave specified by ``addr`` starting from the
-
+        memory address specified by ``memaddr``. Param ``addrsize`` specifies the 
-     - ``recv`` can be an integer, which is the number of bytes to receive,
+        address size in bits.
-       or a mutable buffer, which will be filled with received bytes
+        Set ``stop`` to ``False`` if the transfer should be continued.
-     - ``addr`` is the address to receive from (only required in master mode)
+        Returns the number of bytes written.
-     - ``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,
-   otherwise the same buffer that was passed in to ``recv``.
 
 .. 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.
 
-.. method:: i2c.send(send, addr=0x00, \*, timeout=5000)
-
-   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)
-     - ``timeout`` is the timeout in milliseconds to wait for the send
-
-   Return value: ``None``.
-
 Constants
 ---------
 

docs/library/pyb.UART.rst

@@ -82,10 +82,8 @@ Constructors
     .. class:: pyb.UART(bus, ...)
     
        Construct a UART object on the given bus.  ``bus`` can be 0 or 1.
-       With no additional parameters, the UART object is created but not
+       If the bus is not given, the default one will be selected (0) or the selection
-       initialised (it has the settings from the last initialisation of
+       will be made based on the given pins.
-       the bus, if any).  If extra arguments are given, the bus is initialised.
-       See ``init`` for parameters of initialisation.
 
 Methods
 -------
@@ -118,7 +116,7 @@ Methods
 
 .. only:: port_wipy
 
-    .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS))
+    .. method:: uart.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS))
     
        Initialise the UART bus with the given parameters:
     
@@ -142,6 +140,11 @@ Methods
 
        Return ``True`` if any characters waiting, else ``False``.
 
+    .. method:: uart.writechar(char)
+
+      Write a single character on the bus.  ``char`` is an integer to write.
+      Return value: ``None``.
+
 .. only:: port_wipy
 
     .. method:: uart.any()
@@ -201,11 +204,6 @@ Methods
 
       Return value: number of bytes written.
 
-    .. method:: uart.writechar(char)
-
-      Write a single character on the bus.  ``char`` is an integer to write.
-      Return value: ``None``.
-
    .. only:: port_wipy
 
       Write the buffer of bytes to the bus.

docs/wipy/quickref.rst

@@ -87,12 +87,7 @@ UART (serial bus)
 See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.UART <pyb.UART>`. ::
 
     from pyb import Pin, UART
-
+    uart = UART(0, 9600)
-    # first assign TX and RX to the correct pins
-    Pin('GP1', af=3, mode=Pin.STD_PU)    # TX
-    Pin('GP2', af=3, mode=Pin.STD_PU)    # RX
-
-    uart = UART(1, 9600)
     uart.write('hello')
     uart.read(5) # read up to 5 bytes
 
@@ -121,18 +116,13 @@ I2C bus
 See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.I2C <pyb.I2C>`. ::
 
     from pyb import Pin, I2C
-
-    # first assign SCL and SDA to the correct pins
-    Pin('GP23', af=9, mode=Pin.STD_PU)  # SCL
-    Pin('GP24', af=9, mode=Pin.STD_PU)  # SDA
-
     # configure the I2C bus
-    i2c = I2C(1, I2C.MASTER, baudrate=100000)
+    i2c = I2C(0, I2C.MASTER, baudrate=100000)
     i2c.scan() # returns list of slave addresses
-    i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42
+    i2c.writeto(0x42, 'hello') # send 5 bytes to slave with address 0x42
-    i2c.recv(5, 0x42) # receive 5 bytes from slave
+    i2c.readfrom(0x42, 5) # receive 5 bytes from slave
-    i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10
+    i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from slave 0x42, slave memory 0x10
-    i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10
+    i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to slave 0x42, slave memory 0x10
 
 Watchdog timer (WDT)
 --------------------