170 lines
6.1 KiB
ReStructuredText
170 lines
6.1 KiB
ReStructuredText
.. currentmodule:: pyb
|
|
.. _pyb.I2C:
|
|
|
|
class I2C -- a two-wire serial protocol
|
|
=======================================
|
|
|
|
I2C is a two-wire protocol for communicating between devices. At the physical
|
|
level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
|
|
|
|
I2C objects are created attached to a specific bus. They can be initialised
|
|
when created, or initialised later on.
|
|
|
|
Example::
|
|
|
|
from pyb import I2C
|
|
|
|
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.
|
|
|
|
The basic methods are send and recv::
|
|
|
|
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
|
|
i2c.recv(data) # receive 3 bytes, writing them into data
|
|
|
|
You can specify a timeout (in ms)::
|
|
|
|
i2c.send(b'123', timeout=2000) # timeout after 2 seconds
|
|
|
|
A controller must specify the recipient's address::
|
|
|
|
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 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 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
|
|
------------
|
|
|
|
.. class:: I2C(bus, ...)
|
|
|
|
Construct an I2C object on the given bus. ``bus`` can be 1 or 2, 'X' or
|
|
'Y'. With no additional parameters, the I2C object is created but not
|
|
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.
|
|
|
|
The physical pins of the I2C buses on Pyboards V1.0 and V1.1 are:
|
|
|
|
- ``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)``
|
|
|
|
On the Pyboard Lite:
|
|
|
|
- ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
|
|
- ``I2C(3)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PA8, PB8)``
|
|
|
|
Calling the constructor with 'X' or 'Y' enables portability between Pyboard
|
|
types.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: I2C.deinit()
|
|
|
|
Turn off the I2C bus.
|
|
|
|
.. method:: I2C.init(mode, *, addr=0x12, baudrate=400000, gencall=False, dma=False)
|
|
|
|
Initialise the I2C bus with the given parameters:
|
|
|
|
- ``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)
|
|
|
|
The actual clock frequency may be lower than the requested frequency.
|
|
This is dependant on the platform hardware. The actual rate may be determined
|
|
by printing the I2C object.
|
|
|
|
.. method:: I2C.is_ready(addr)
|
|
|
|
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)
|
|
|
|
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 controller 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 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 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,
|
|
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 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 controller mode.
|
|
|
|
Constants
|
|
---------
|
|
|
|
.. data:: I2C.CONTROLLER
|
|
|
|
for initialising the bus to controller mode
|
|
|
|
.. data:: I2C.PERIPHERAL
|
|
|
|
for initialising the bus to peripheral mode
|