class I2C – 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 initialized when created, or initialized later on.
from machine import I2C i2c = I2C(0) # create on bus 0 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.
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
Quick Usage Example
from machine import I2C # configure the I2C bus i2c = I2C(0, I2C.MASTER, 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
Construct an I2C object on the given bus. bus can only be 0, 1 or 2. If the bus is not given, the default one will be selected (0). Buses 0 and 1 use the ESP32 I2C hardware peripheral while bus 2 is implemented with a bit-banged software driver.
Initialise the I2C bus with the given parameters:
baudrateis the SCL clock rate
- pins is an optional tuple with the pins to assign to the I2C bus. The default I2C pins are P9 (SDA) and P10 (SCL)
Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond. A device responds if it pulls the SDA line low after its address (including a read bit) is sent on the bus.
Standard Bus Operations
The following methods implement the standard I2C master read and write operations that target a given slave device.
Read nbytes from the slave specified by addr. Returns a bytes object with the data read.
Read into buf from the slave specified by addr. The number of bytes read will be the length of buf.
Return value is the number of bytes read.
Write the bytes from buf to the slave specified by addr. The argument buf can also be an integer which will be treated as a single byte. If stop is set to False then the stop condition won’t be sent and the I2C operation may be continued (typically with a read transaction).
Return value is the number of bytes written.
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 methods are convenience functions to communicate with such devices.
Read nbytes from the slave specified by addr starting from the memory address specified by memaddr.
Read into buf from the slave specified by addr starting from the memory address specified by memaddr. The number of bytes read is the length of buf.
The return value is the number of bytes read.
Write buf to the slave specified by addr starting from the memory address specified by memaddr. The argument buf can also be an integer which will be treated as a single byte.
The return value is the number of bytes written.
Used to initialise the bus to master mode.