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

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

This commit is contained in:
Daniel Campora 2015-09-11 14:57:48 +02:00
parent e77abc261b
commit f38d16483a
3 changed files with 145 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -12,9 +12,9 @@ when created, or initialised later on.
.. only:: port_pyboard .. only:: port_pyboard
Example:: Example::
from pyb import I2C from pyb import I2C
i2c = I2C(1) # create on bus 1 i2c = I2C(1) # create on bus 1
i2c = I2C(1, I2C.MASTER) # create and init as a master i2c = I2C(1, I2C.MASTER) # create and init as a master
i2c.init(I2C.MASTER, baudrate=20000) # init as a master i2c.init(I2C.MASTER, baudrate=20000) # init as a master
@ -24,46 +24,65 @@ when created, or initialised later on.
.. only:: port_wipy .. only:: port_wipy
Example:: Example::
from pyb import I2C 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.init(I2C.MASTER, baudrate=20000) # init as a master
i2c.deinit() # turn off the peripheral i2c.deinit() # turn off the peripheral
Printing the i2c object gives you information about its configuration. 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
To receive inplace, first create a bytearray::
data = bytearray(3) # create a buffer data = bytearray(3) # create a buffer
i2c.recv(data) # receive 3 bytes, writing them into data i2c.recv(data) # receive 3 bytes, writing them into data
You can specify a timeout (in ms):: You can specify a timeout (in ms)::
i2c.send(b'123', timeout=2000) # timout after 2 seconds i2c.send(b'123', timeout=2000) # timout after 2 seconds
A master must specify the recipient's address:: A master must specify the recipient's address::
i2c.init(I2C.MASTER) i2c.init(I2C.MASTER)
i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42 i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42
i2c.send(b'456', addr=0x42) # keyword for address i2c.send(b'456', addr=0x42) # keyword for address
Master also has other methods:: Master also has other methods::
i2c.is_ready(0x42) # check if slave 0x42 is ready i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning i2c.scan() # scan for slaves on the bus, returning
# a list of valid addresses # a list of valid addresses
i2c.mem_read(3, 0x42, 2) # read 3 bytes from 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 # starting at address 2 in the slave
i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of slave 0x42 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 # 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 Constructors
------------ ------------
@ -71,15 +90,15 @@ Constructors
.. only:: port_pyboard .. only:: port_pyboard
.. class:: pyb.I2C(bus, ...) .. class:: pyb.I2C(bus, ...)
Construct an I2C object on the given bus. ``bus`` can be 1 or 2. Construct an I2C object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the I2C object is created but not With no additional parameters, the I2C object is created but not
initialised (it has the settings from the last initialisation of initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised. the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation. See ``init`` for parameters of initialisation.
The physical pins of the I2C busses are: The physical pins of the I2C busses are:
- ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)`` - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
- ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)`` - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)``
@ -87,12 +106,8 @@ Constructors
.. class:: pyb.I2C(bus, ...) .. 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 Methods
------- -------
@ -103,7 +118,7 @@ Methods
.. only:: port_pyboard .. 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: Initialise the I2C bus with the given parameters:
@ -112,72 +127,110 @@ Methods
- ``baudrate`` is the SCL clock rate (only sensible for a master) - ``baudrate`` is the SCL clock rate (only sensible for a master)
- ``gencall`` is whether to support general call mode - ``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 .. only:: port_wipy
.. method:: i2c.init(mode, \*, baudrate=100000) .. method:: i2c.init(mode, \*, baudrate=100000)
Initialise the I2C bus with the given parameters: Initialise the I2C bus with the given parameters:
- ``mode`` must be ``I2C.MASTER`` - ``mode`` must be ``I2C.MASTER``
- ``baudrate`` is the SCL clock rate - ``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() .. method:: i2c.scan()
Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond. 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 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 Constants
--------- ---------

18
docs/library/pyb.UART.rst
View File

@ -82,10 +82,8 @@ Constructors
.. class:: pyb.UART(bus, ...) .. class:: pyb.UART(bus, ...)
Construct a UART object on the given bus. ``bus`` can be 0 or 1. 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 Methods
------- -------
@ -118,7 +116,7 @@ Methods
.. only:: port_wipy .. 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: Initialise the UART bus with the given parameters:
@ -142,6 +140,11 @@ Methods
Return ``True`` if any characters waiting, else ``False``. 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 .. only:: port_wipy
.. method:: uart.any() .. method:: uart.any()
@ -201,11 +204,6 @@ Methods
Return value: number of bytes written. 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 .. only:: port_wipy
Write the buffer of bytes to the bus. Write the buffer of bytes to the bus.

22
docs/wipy/quickref.rst
View File

@ -87,12 +87,7 @@ UART (serial bus)
See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.UART <pyb.UART>`. :: See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.UART <pyb.UART>`. ::
from pyb import Pin, 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.write('hello')
uart.read(5) # read up to 5 bytes 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>`. :: See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.I2C <pyb.I2C>`. ::
from pyb import Pin, 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 # 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.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) Watchdog timer (WDT)
-------------------- --------------------