I2C commands allow you to configure an I2C interface on arbitrary pins, scan the I2C bus for devices, and perform read/write operations on selected devices. This simplifies working with new I2C devices, checking whether a device is responsive, and developing libraries: you can send test sequences to a device without recompiling the entire sketch.
The ESP32 has two hardware I2C interfaces. Default pin assignments vary by model: for example, the ESP32-WROOM-32D chip uses pins 21 (SDA) and 22 (SCL) for I2C0.
To configure or access an I2C interface, use the "iic I2C_NUM" command, where I2C_NUM is the number of the I2C interface to configure. After executing the command, the ESPShell prompt changes to "esp32-i2c0>", indicating that you're now in I2C configuration mode. Use the "exit" command or press Ctrl+Z to leave this mode.
There are 6 commands available in I2C configuration mode: (You can also use commands from the main tree for example, the "pin" command is available inside the "esp32-i2c>" tree.)
esp32#>iic 0 esp32-i2c>? % Enter "? command" to get details about the command. % List of available commands: % % "?" : Show the list of available commands % "up" : Initialize interface (pins and speed) % "clock" : Set clock speed % "read" : Read data from a device % "down" : Shut down I2C interface % "scan" : Scan I2C bus % "write" : Send bytes to the device % "exit" : Exit esp32-i2c>
All of these commands (except "up") require the I2C interface to be initialized first. To do this, use the "up" command. It takes three arguments: the SDA pin, the SCL pin, and the clock rate (in Hz).
For example, to initialize I2C0 with a 100 kHz clock on pins 21 (SDA) and 22 (SCL):
esp32#>iic 0 esp32-i2c>up 21 22 100000
Once the bus is initialized, you can perform read, write, and scan operations. It's a good idea to suspend the main sketch to avoid interference with your I2C access (see the global "suspend" and "resume" commands). To shut down the bus, use the "down" command.
Let's scan the I2C bus. In this example, two devices are connected to I2C0:
esp32#>iic 0 esp32-i2c>up 21 22 100000 esp32-i2c>scan % Scanning I2C bus 0... % Device found at address 57 % Device found at address 68 % 2 devices found esp32-i2c>
These two devices are a DS3231 real-time clock and a 64K EEPROM, both located on the same breakout board connected to pins 21 and 22.
Now let's communicate with the clock chip to read the current time. We'll use the "write" command to request the time and "read" to get the response:
esp32-i2c>write 0x68 0 % Sending 1 byte over I2C0 esp32-i2c>read 0x68 7 % I2C0 received 7 bytes: 24 25 22 03 18 09 24 < -- hexadecimal values
The received bytes represent the current time: 22:25:24, third day of the week, 18th of September 2024. With the device's datasheet, you can interpret and communicate directly with it helpful when developing a new I2C library.
For convenience, hexadecimal input does not require the "0x" prefix: you can enter "98" instead of "0x98", and it will be interpreted as hexadecimal.
esp32-i2c>write 0x68 0x11 0x12 0x13
is the same as:
esp32-i2c>write 0x68 11 12 13
esp32#>iic 0
esp32-i2c>up 21 22 100000
esp32-i2c>scan
% Scanning I2C bus 0...
% Device found at address 57
% Device found at address 68
% 2 devices found
esp32-i2c>write 0x57 0 0
% Sending 2 bytes over I2C0
esp32-i2c>read 57 56
% I2C0 received 56 bytes:
0 1 2 3 4 5 6 7 8 9 A B C D E F |0123456789ABCDEF
----------------------------------------------------------+----------------
0000: de ad be ef 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |...............
0010: 10 22 33 44 55 66 77 88 99 aa bb cc 1c 1d 1e 1f |."3DUfw.........
0020: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f | !"#$%&'()*+,-./
0030: 30 31 32 33 34 35 36 37 |01234567
esp32-i2c0>
NOTE: If the requested data size exceeds 16 bytes, the output is formatted as shown above.
Use the "clock" command to change the I2C clock speed. For example, "clock 150000" sets the speed to 150 kHz. The maximum supported value is 1 MHz.
The "down" command shuts down the I2C interface.
Use the "exit" command or press Ctrl+Z to leave I2C configuration mode.