Complete documentation for all classes, methods, and functions in the ESP32 GPIO Bridge Python library.
Main controller class providing all ESP32 GPIO operations. This is the primary interface for communicating with your ESP32.
ESP32GPIO(port, baudrate=115200, timeout=1.0, auto_connect=True)
| Parameter | Type | Default | Description |
|---|---|---|---|
| port | str | — | Serial port device path (e.g., '/dev/ttyUSB0', 'COM5') |
| baudrate | int | 115200 | Serial communication speed |
| timeout | float | 1.0 | Serial timeout in seconds |
| auto_connect | bool | True | Whether to automatically connect on initialization |
from esp32_gpio_bridge import ESP32GPIO, find_esp32_port
# Auto-detect ESP32 port
port = find_esp32_port()
# Create ESP32GPIO instance
esp = ESP32GPIO(port)
# Or use context manager (recommended)
with ESP32GPIO(port) as esp:
# Your code here
passconnect() → None
Establish connection to the ESP32 GPIO Bridge.
esp = ESP32GPIO(port, auto_connect=False)
esp.connect()close() → None
Close connection to ESP32 and cleanup resources.
esp.close()get_version() → str
Get ESP32 firmware version.
version = esp.get_version()
print(f"Firmware version: {version}")get_status() → Dict[str, Any]
Get ESP32 status including failsafe state.
status = esp.get_status()
print(f"State: {status['state']}")
print(f"Failsafe: {status['failsafe_engaged']}")set_pin_mode(pin: int, mode: str) → None
Set GPIO pin mode.
esp.set_pin_mode(2, "OUT") # LED pin
esp.set_pin_mode(0, "IN_PULLUP") # Button pindigital_write(pin: int, value: Union[int, bool]) → None
Write digital value to GPIO pin.
esp.digital_write(2, 1) # Turn LED on
esp.digital_write(2, True) # Same as above
esp.digital_write(2, 0) # Turn LED offdigital_read(pin: int) → int
Read digital value from GPIO pin.
button_state = esp.digital_read(0)
if button_state == 0:
print("Button pressed")batch_digital_write(pin_values: Dict[int, Union[int, bool]]) → None
Write multiple digital pins in a single command for efficiency.
esp.batch_digital_write({
2: 1, # Pin 2 HIGH
4: 0, # Pin 4 LOW
5: 1 # Pin 5 HIGH
})pwm_init(pin: int, frequency: int = 5000, resolution: int = 8) → int
Initialize PWM on a pin.
channel = esp.pwm_init(2, frequency=1000, resolution=8)
print(f"PWM channel: {channel}")pwm_write(pin: int, duty_cycle: int) → None
Set PWM duty cycle on a pin.
esp.pwm_write(2, 128) # 50% duty cycle (8-bit)pwm_set_duty_percent(pin: int, percent: float) → None
Set PWM duty cycle as a percentage.
esp.pwm_set_duty_percent(2, 75.0) # 75% duty cyclepwm_stop(pin: int) → None
Stop PWM on a pin and release the channel.
esp.pwm_stop(2)analog_read(pin: int) → int
Read analog value from ADC pin.
raw_value = esp.analog_read(34)
voltage = (raw_value / 4095.0) * 3.3
print(f"Voltage: {voltage:.2f}V")analog_write(pin: int, value: int) → None
Write analog value to DAC pin.
esp.analog_write(25, 128) # 1.65V on GPIO 25
esp.analog_write(26, 255) # 3.3V on GPIO 26i2c_init(sda: int = 21, scl: int = 22, frequency: int = 100000) → None
Initialize I2C bus.
esp.i2c_init(sda=21, scl=22, frequency=100000)i2c_scan() → List[int]
Scan I2C bus for devices.
devices = esp.i2c_scan()
print(f"Found devices: {[hex(addr) for addr in devices]}")i2c_write(address: int, data: Union[int, List[int], bytes]) → None
Write data to I2C device.
# Write single byte
esp.i2c_write(0x3C, 0x00)
# Write multiple bytes
esp.i2c_write(0x3C, [0x00, 0xFF, 0x80])i2c_read(address: int, num_bytes: int) → List[int]
Read data from I2C device.
data = esp.i2c_read(0x48, 4)
print(f"Read data: {data}")eeprom_read(address: int) → int
Read a single byte from EEPROM.
value = esp.eeprom_read(0)
print(f"Byte at address 0: {value}")eeprom_write(address: int, value: int) → None
Write a single byte to EEPROM (requires commit).
esp.eeprom_write(0, 42)
esp.eeprom_commit() # Save to flasheeprom_read_block(address: int, length: int) → List[int]
Read a block of bytes from EEPROM.
data = esp.eeprom_read_block(0, 16)
print(f"Read 16 bytes: {data}")eeprom_write_block(address: int, data: List[int]) → None
Write a block of bytes to EEPROM (requires commit).
data = [10, 20, 30, 40, 50]
esp.eeprom_write_block(0, data)
esp.eeprom_commit()eeprom_write_string(address: int, text: str) → None
Write a string to EEPROM.
esp.eeprom_write_string(100, "Hello ESP32!")
esp.eeprom_commit()eeprom_read_string(address: int, length: int) → str
Read a string from EEPROM.
text = esp.eeprom_read_string(100, 12)
print(f"Stored text: {text}")eeprom_commit() → None
Commit EEPROM changes to flash memory.
Must be called after write operations to persist changes.
eeprom_clear() → None
Clear all EEPROM data (set all bytes to 0) and commit.
esp.eeprom_clear() # Sets all bytes to 0 and commitsfind_esp32_port(timeout: float = 2.0) → Optional[str]
Auto-detect ESP32 GPIO Bridge by actively probing serial ports.
from esp32_gpio_bridge import find_esp32_port
port = find_esp32_port()
if port:
print(f"Found ESP32 on: {port}")
else:
print("ESP32 not found")list_serial_ports() → List[Tuple[str, str]]
List all available serial ports.
from esp32_gpio_bridge import list_serial_ports
ports = list_serial_ports()
for device, description in ports:
print(f"{device}: {description}")select_port() → Optional[str]
Interactive port selection menu.
from esp32_gpio_bridge import select_port
port = select_port()
if port:
print(f"Selected: {port}")
else:
print("No port selected")reset_failsafe() → bool
Manually reset/disable failsafe mode.
success = esp.reset_failsafe()
if success:
print("Failsafe was engaged and reset")
else:
print("Failsafe was not engaged")Raised for invalid parameters (pin numbers, modes, etc.)
try:
esp.analog_read(99) # Invalid pin
except ValueError as e:
print(f"Invalid pin: {e}")Raised for connection issues and communication errors
try:
esp.digital_write(2, 1)
except IOError as e:
print(f"Connection error: {e}")Raised when no response is received from ESP32
try:
version = esp.get_version()
except TimeoutError as e:
print(f"Timeout: {e}")