ESP32 using MicroPython: I2C bus

Overview¶ _

This tutorial briefly introduces the I²C bus protocol and teaches you how to use I²C under MicroPython with a simple example.

quick start

from machine import Pin, I2C

# construct a software I2C bus
i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)

# construct a hardware I2C bus
i2c = I2C(0)
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)

i2c.scan()              # scan for slave devices

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

What is I²C

I²C (Inter-integrated Circuit) was first developed and designed by Philips in 1982 as a bus protocol. The I²C bus supports short-distance communication between devices and is used for the interface between the processor and some peripheral devices, and it only requires two signal lines to complete the exchange of information.

Communication principle¶

Physical wiring¶

I²C requires at least two wires, similar to asynchronous serial ports, but can support multiple slave devices. Unlike SPI, I²C can support multi-master (mul-master) systems, allowing multiple masters and each The master can communicate with all slaves (I²C communication is not available between masters, and each master can only use the I²C bus in turn). The master refers to the device that initiates the data transfer and generates a clock signal on the bus to drive the transfer, while the addressed communication devices act as slaves.

I²C communication requires only 2 bidirectional buses:

function number	meaning
SDA (serial data: serial data line)	Data transmission, SDA line transmission data is big-endian transmission, one byte at a time
SCL (serial clock: serial clock line)	Synchronous data sending and receiving

We take the simplest one host corresponding to multiple slaves as an example, and carry out the following principle science.

Data validity¶

The data on the SDA line must remain stable during the high period of the clock, and the high or low state of the data line can only change when the clock signal on the SCL line is low.

In other words, when SCL is high, it means valid data, when SDA is high, it means "1", and when SDA is low, it means "0"; when SCL is low, it means invalid data. At this time, SDA will switch the level for the next time. Data representation to prepare. Figure 13-1 shows the timing diagram of data validity.

Start Condition S and Stop Condition P¶

Start condition S: When SCL is high, SDA is converted from high to low;
Stop condition P: When SCL is high, SDA transitions from low to high.

Start and stop conditions are generally generated by the host. The bus is in a busy state after a start condition, and after a certain period of time in a stop condition, the bus is in an idle state again. The following figure shows the signal generation timing diagram of the start and stop conditions.

Data format¶

The data transmitted by I2C is in bytes, each byte must be 8 bits, and any number of bytes can be transmitted. In the above figure, one byte of data is used as an example for analysis. The data format of I2C has the following characteristics:

Each byte must be followed by a response bit ACK (such as the ACK on SCL in the figure above), so it takes 9 bits of time to actually transmit a byte (8 bits) of data.
On the SDA, the highest bit of the byte is transmitted first. From the above figure, we can see that the sending order of the digit number is from left to right.Bit7-Bit0

Response ACK¶

After the data receiver receives a byte of data transmitted, it needs to give a response. At this time, at the ninth clock, the sender releases the control of the SDA line, pulls the SDA level high, and is controlled by the receiver.

The receiver indicates that it has successfully received 8-bit one-byte data, and pulls SDA low to a low level, that is, the ACK signal, indicating a response

PDU¶

When you understand the sequence diagram, then we will post the I2C PDU (Protocol Data Unit: Protocol Data Unit, that is, the data format) for everyone:

The following pictures are from the Internet

Hardware Resources¶

ESP32 itself has 2 I²C bus interfaces, according to user's configuration, the bus interface can be used as I²C master or slave mode.

Unfortunately, the I²C on the MicroPython ESP32 is simulated by software and does not fully utilize the hardware resources of the ESP32.

In theory, most GPIOs that support both input and output can be configured as I²C pin resources.

I2C API Documentation

kind

class machine.I2C(scl, sda, freq)

scl: I²C device clock pin object
sda: I²C device data line pin object
freq: SCL clock frequency 0 < freq≤ 500000(Hz)

Define I2C

Example:

from machine import I2C, Pin
I2C = I2C(scl=Pin(5), sda=Pin(4), freq=100000)

Common class functions¶

I2C.init(scl, sda, freq)¶

Function description: Initialize and construct the I²C bus.

scl: I/O port of SCL signal line: I/O port
sdaof SDA signal line
freq: SCL clock frequency

Example:

I2C.init(scl=Pin(5), sda=Pin(4), freq=100000)

I2C.scan()¶

Function description: Scan I²C addresses between 0x08 and 0x77 and return a list of devices.
Example:

I2C.scan()

I2C.start()¶

Function description: Trigger the START state on the bus (when SCL is high, SDA turns to low).
Example:

I2C.start()

I2C.stop()¶

Function description: Trigger the STOP state on the bus (when SCL is high, SDA turns to high).
Example:

I2C.stop()

I2C.write(buf)¶

Function description: The data in buf is written to the bus, and the number of bytes written is returned.

buf: buffer to store data

Note :
Use the write() function together with the start function, otherwise the number of bytes written cannot be returned.
Example:

buf = b'123'
I2C.start()
I2C.write(buf)

I2C.readinto(buf, nack=True)¶

Function description: read data from the bus and store it in buf, no return value.

buf : buffer to store data

Note:
The number of bytes read is the length of buf. Before the last byte is received, the bus will send an ACK signal. After the last byte is received, if nack is True, then a NACK signal will be sent, otherwise an ACK signal will be sent. Example:

buf=bytearray(3)
I2C.readinto(buf)

Standard bus operations¶

The functions described below are standard I²C master mode read and write operations.

I2C.readfrom(addr, nbytes)¶

Function description: Read data from the specified address device and return the read object, which is related to the I²C device.

addr: I²C device address (can be read by the scan function)
nbytes: The size of the data to be read

Example:

>>> print(I2C.scan())
[24]
>>> data = I2C.readfrom(24, 8)
>>> print(data)
b'\x00\x02\x00\x00\xe8\x03\xe8\x03'

I2C.readfrom_into(addr, buf)¶

Function description: Read buf.len() data from the specified address device to buf.

addr: I²C device address (can be read by scan function)
buf: Buffer for storing data

Example:

>>> buf = bytearray(8)
>>> I2C.readfrom_into(24, buf)
>>> print(buf)
bytearray(b'\x00\x02\x00\x00\xe8\x03\xe8\x03')

I2C.writeto(addr, buf)¶

Function description: Write the data in buf to the device and return the size of the written data.

addr: I²C device address (can be read by scan function)
buf: Buffer for storing data

Example:

>>> b = bytearray(3)
>>> b[0] = 24
>>> b[1] = 111
>>> b[2] = 107
>>> i = I2C.writeto(24,b)
3

Memory operations¶

Some I²C devices act as storage devices (or a set of registers) that can be read or written to. In this case, there are two addresses associated with the I²C transaction: the slave address and the memory address. The following methods are used to communicate with these devices.

I2C.readfrom_mem(addr, memaddr, nbytes, addrsize=8)¶

Function description: Read and return data from the register of the I²C device.

addr: I²C device address (can be read by scan function)
memaddr: Register address
nbytes: Byte size to be read
addrsize: Specify the address size, the default is 8 bits (this parameter is invalid on ESP8266, the address size is always 8 bits)

Example:

b = I2C. readfrom_mem(24,  0x58, 3)
print(b)

operation result:

b'\x00\x02\x01'

I2C.readfrom_mem_into(addr, memaddr, buf, addrsize=8)¶

Function description: Read buf.len() data from the register of the I²C device to buf, with no return value.

addr: I²C device address (can be read out by the scan function)
memaddr: Register address
buf: Buffer for storing data
addrsize: specify the address size, the default is 8 bits (this parameter is invalid on ESP8266, the address size is always 8 bits), the number of data to read is the length of buf.

Example:

buf=bytearray(8)
I2C.readfrom_mem_into(24, 0x58, buf)

I2C.writeto_mem(addr, memaddr, buf, addrsize=8)¶

Function description: Write all the data in buf to the memory memaddr of the slave device addr.

Example:

buf = b'123'
I2C.writeto_mem(24, 0x58, buf)