ESP32 I2C Scanner

Universal I2C bus scanner for the entire ESP32 family. Automatically detects I2C devices and identifies them using a comprehensive device database.

Supported Chips

Chip	I2C Ports	Default SDA	Default SCL
ESP32	2	GPIO 21	GPIO 22
ESP32-S2	2	GPIO 8	GPIO 9
ESP32-S3	2	GPIO 8	GPIO 9
ESP32-C3	1	GPIO 8	GPIO 9
ESP32-C6	2	GPIO 6	GPIO 7
ESP32-H2	2	GPIO 12	GPIO 22

Features

• Universal Compatibility: Works with all ESP32 variants
• Automatic Device Identification: Includes database of 100+ common I2C devices
• Multiple Scan Modes:
  • Quick scan on default pins
  • Full GPIO combination scan (finds devices on non-standard pins)
• Pretty Console Output: Colored, formatted output with device address map
• Configurable via menuconfig: Customize pins, frequency, and behavior
• Periodic Rescan: Optional automatic rescanning at configurable intervals

Project Structure

esp32-i2c-scanner/
├── CMakeLists.txt              # Main project CMake file
├── sdkconfig.defaults          # Default SDK configuration
├── README.md                   # This file
└── main/
    ├── CMakeLists.txt          # Component CMake file
    ├── Kconfig.projbuild       # Menuconfig options
    ├── main.c                  # Application entry point
    ├── i2c_scanner.c           # Scanner implementation
    └── include/
        ├── parameters.h        # Hardware parameters and defines
        ├── i2c_scanner.h       # Scanner interface
        └── i2c_devices.h       # Known device database

Building

Prerequisites

• ESP-IDF v5.0 or later
• Python 3.8+

Build Commands

# Set target chip (choose one)
idf.py set-target esp32
idf.py set-target esp32s2
idf.py set-target esp32s3
idf.py set-target esp32c3
idf.py set-target esp32c6
idf.py set-target esp32h2

# Configure (optional)
idf.py menuconfig

# Build
idf.py build

# Flash and monitor
idf.py flash monitor

Configuration

Via menuconfig

Run idf.py menuconfig and navigate to I2C Scanner Configuration:

Option	Description	Default
I2C SDA GPIO Pin	SDA line GPIO number	Chip-dependent
I2C SCL GPIO Pin	SCL line GPIO number	Chip-dependent
I2C Master Frequency	Clock frequency (Hz)	100000
Enable internal pull-ups	Use internal pull-ups	Yes
Scan all GPIO combinations	Test all valid GPIO pairs	No
Verbose output	Detailed scan progress	Yes
Use colored console output	ANSI color codes	Yes
Rescan interval	Auto-rescan period (0=off)	0

Via parameters.h

Edit main/include/parameters.h to modify:

• I2C timing parameters
• Address scan range
• Default pin configurations
• Scan behavior options

Usage

Quick Scan (Default)

Connect your I2C devices to the default pins and reset the ESP32. The scanner will:

1. Display chip information
2. Show configured I2C pins
3. Scan all addresses (0x03-0x77)
4. Print results with device identification
5. Display an address map

Full GPIO Scan

To find devices connected to non-standard pins:

1. Set SCAN_ALL_GPIO_COMBINATIONS to true in parameters.h
2. Or enable via menuconfig
3. Rebuild and flash

Note: Full scan tests hundreds of GPIO combinations and takes several minutes.

Sample Output

╔════════════════════════════════════════════════════════════════╗
║ I2C Scan Results                                               ║
╚════════════════════════════════════════════════════════════════╝

  Found 3 I2C device(s)!

  Address  │ Port   │ SDA   │ SCL   │ Possible Device(s)
────────────────────────────────────────────────────────────────────
  0x3C     │ 0      │ 21    │ 22    │ SSD1306 OLED Display
  0x68     │ 0      │ 21    │ 22    │ DS3231 / MPU6050
  0x76     │ 0      │ 21    │ 22    │ BME280 / BMP280

  I2C Address Map (0x03-0x77):

       0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  0x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 
  1x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 
  2x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 
  3x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 3C ·· ·· ·· 
  4x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 
  5x ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· ·· 
  6x ·· ·· ·· ·· ·· ·· ·· ·· 68 ·· ·· ·· ·· ·· ·· ·· 
  7x ·· ·· ·· ·· ·· ·· 76 ·· 

Troubleshooting

No devices found

1. Check wiring: Verify SDA and SCL connections
2. Check power: Ensure I2C device has proper power supply
3. Add pull-ups: External 4.7kΩ pull-up resistors are recommended
4. Check address: Some devices have configurable addresses
5. Try full scan: Device may be on non-standard pins

Multiple possible devices

Many I2C addresses are shared by different devices. The scanner shows all known devices that could be at that address. Identify your actual device by its physical characteristics or datasheet.

Scan fails on certain pins

Some GPIOs are reserved for:

• Flash memory interface
• Strapping pins
• Input-only pins (ESP32 GPIO 34-39)

The scanner automatically excludes these pins.

Adding New Devices

Edit main/include/i2c_devices.h to add new devices:

{0xAA, "Device Name", "Brief Description"},

License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to share and adapt this material for any purpose, even commercially, as long as you give appropriate credit.

Contributing

Contributions welcome! Please submit pull requests for:

• New device entries in the database
• Support for new ESP32 variants
• Bug fixes and improvements