Installation Guide - ESP32 GPIO Bridge

Prerequisites

ESP32 Board

Any ESP32 development board (ESP32-DevKitC, NodeMCU-32S, etc.)

Arduino IDE

Version 2.0.0 or higher with ESP32 board manager

Python 3.6+

Python 3.6 or higher installed on your system

USB Cable

USB-A to USB-C or micro-USB cable for ESP32

Computer

Windows, macOS, or Linux with USB serial support

Git

Git installed for cloning the repository

Important Notes

• Make sure your ESP32 board has sufficient GPIO pins (most boards have 30+ GPIO pins)
• Some ESP32 boards may require specific drivers (CP2102, CH340, etc.)
• Ensure your Python environment has pip package manager
• For Linux/Mac users, you may need to add your user to the dialout group

ESP32 Firmware Setup

Flash the modular ESP32 firmware to enable GPIO Bridge functionality.

1

Install Arduino IDE & ESP32 Board Package

Download Arduino IDE

Download and install Arduino IDE version 2.0.0 or higher from the official website.

Download Arduino IDE

Add ESP32 Board Package

Board Manager URL

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Add this URL in Arduino IDE → File → Preferences → Additional Board Manager URLs

2

Install ESP32 Board Package

Open Arduino IDE

Go to Tools → Board → Boards Manager

Search for "ESP32"

Install "ESP32 by Espressif Systems"

Wait for installation to complete

3

Download ESP32 GPIO Bridge Firmware

Clone Repository

git clone https://github.com/1999AZZAR/esp32_GPIO_bridge.git
cd esp32_GPIO_bridge

Or Download ZIP

Download the repository as a ZIP file and extract it.

Download ZIP

4

Configure Arduino IDE

Open Firmware File

Navigate to the firmware directory and open firmware.ino

Select Board

Go to Tools → Board → ESP32 Arduino → ESP32 Dev Module

Or select your specific ESP32 board model

Configure Settings

Upload Speed: 921600
CPU Frequency: 240MHz (WiFi/BT)
Flash Frequency: 80MHz
Flash Mode: QIO
Flash Size: 4MB (32Mb)
Partition Scheme: Default 4MB with spiffs

5

Upload Firmware

Connect ESP32

Connect ESP32 to computer via USB cable

Select correct COM port in Arduino IDE

Upload Firmware

Click Upload button (→) in Arduino IDE

Wait for upload to complete (30-60 seconds)

Upload Successful!

You should see "Done uploading" message. Your ESP32 is now running the GPIO Bridge firmware.

Python Library Installation

Install the ESP32 GPIO Bridge Python library to control your ESP32 from Python.

Method 1: Install from Source (Recommended)

Clone and Install

Install from Source

# Clone repository
git clone https://github.com/1999AZZAR/esp32_GPIO_bridge.git esp32-gpio-bridge
cd esp32-gpio-bridge

# Install in development mode (recommended)
pip install -e .

Advantages

• Access to latest features and bug fixes
• Can modify source code if needed
• Includes all examples and documentation
• Editable installation for development

Method 2: Install with Development Dependencies

Development Installation

Install with Dev Dependencies

# Install with development dependencies
pip install -e ".[dev]"

# This includes testing and development tools:
# - pytest (for running tests)
# - black (for code formatting)
# - flake8 (for linting)
# - mypy (for type checking)

Advantages

• Includes development and testing tools
• Ready for contributing to the project
• Access to latest features and bug fixes

Dependencies

Required Dependencies

Core Dependencies

# These are installed automatically
pyserial>=3.5
types-pyserial  # For type hints

Optional Dependencies

# For examples and development
matplotlib
numpy
pytest
black
flake8
mypy

Testing Your Installation

Verify that both firmware and Python library are working correctly.

Test Python Library

Quick Connection Test

test_connection.py

from esp32_gpio_bridge import ESP32GPIO, find_esp32_port

# Auto-detect ESP32
port = find_esp32_port()
if port:
    print(f"Found ESP32 on: {port}")
    
    # Test connection
    with ESP32GPIO(port) as esp:
        version = esp.get_version()
        print(f"Firmware version: {version}")
        print("✅ Connection successful!")
else:
    print("❌ ESP32 not found")

Expected Output

Found ESP32 on: /dev/ttyUSB0
Firmware version: ESP32_GPIO_BRIDGE_v0.1.6-beta
✅ Connection successful!

Run Example

Basic I/O Example

Run Example

# Navigate to examples directory
cd examples

# Run basic I/O example
python basic_io_example.py

# Run LED patterns example
python led_patterns_example.py

Hardware Setup

• Connect LED to GPIO 2 with 220Ω resistor
• Connect button to GPIO 0 (optional)
• Connect potentiometer to GPIO 34 (optional)

Troubleshooting

Common issues and their solutions.

Common Issues

ESP32 Not Detected

Problem: find_esp32_port() returns None

Solutions:

Check USB cable connection
Install ESP32 USB drivers (CP2102, CH340, etc.)
Try different USB port
Reset ESP32 board
Check if another program is using the serial port

Permission Denied (Linux/Mac)

Problem: Permission denied when accessing serial port

Solution:

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Logout and login again, or run:
newgrp dialout

Upload Failed

Problem: Firmware upload fails in Arduino IDE

Solutions:

Hold BOOT button while clicking Upload
Try lower upload speed (115200 or 57600)
Check USB cable (use data cable, not charging cable)
Try different USB port
Disconnect other USB devices temporarily

No Response from ESP32

Problem: Python can connect but gets no response

Solutions:

Verify correct baud rate (115200)
Check if firmware was uploaded correctly
Reset ESP32 board
Try different serial port

Getting Help

Documentation

Community Support

Ready to Start Building?

Your ESP32 GPIO Bridge is now ready! Check out the examples and start building amazing projects.

View Examples API Reference