# ESP32 USB GPIO Python Library
A Python library for controlling ESP32 GPIO pins via USB serial communication. This library provides a simple and intuitive interface to interact with ESP32 GPIO pins remotely through USB connection.
**Note**: This library requires compatible ESP32 firmware to be flashed on your ESP32 device. The corresponding ESP-IDF firmware code is available at: https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF
## Features
- **GPIO Pin Control**: Configure, set, reset, and toggle GPIO pins
- **Pin State Reading**: Read individual pin states and port states
- **Multiple GPIO Modes**: Support for input, output, open-drain configurations
- **Pull-up/Pull-down Resistors**: Configure internal pull resistors
- **Interrupt Support**: Configure GPIO interrupts (rising, falling, level-based)
- **Thread-safe Serial Communication**: Asynchronous serial data handling
- **Error Handling**: Comprehensive error reporting and exception handling
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install esp32-usb-gpio
```
### Option 2: Install from Source
Clone this repository and install:
```bash
git clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git
cd ESP32-USB-GPIO-PY
pip install .
```
### Option 3: Development Installation
For development, install in editable mode:
```bash
git clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git
cd ESP32-USB-GPIO-PY
pip install -e .
```
### Dependencies
The package automatically installs its dependencies:
- `pyserial`: For serial communication with ESP32
## Quick Start
```python
from esp32_usb_gpio import ESP32USBGPIO, GPIOPinMode, GPIOPinState
# Initialize connection to ESP32
gpio = ESP32USBGPIO('/dev/ttyUSB0') # Replace with your port
# Setup GPIO pin 2 as output
gpio.setup(pin=2, mode=GPIOPinMode.OUTPUT)
# Set pin high
gpio.set(pin=2)
# Read pin state
state = gpio.pinState(pin=2)
print(f"Pin 2 state: {'HIGH' if state == GPIOPinState.HIGH else 'LOW'}")
# Toggle pin
gpio.toggle(pin=2)
# Reset pin to low
gpio.reset(pin=2)
```
## Package Information
- **Package Name**: esp32-usb-gpio
- **Version**: 0.1.1
- **Author**: Aakash Singh
- **License**: GPL-3.0
- **Python Compatibility**: Python 3.7+
## Core Classes and Enums
### GPIO Pin Modes (`GPIOPinMode`)
- `DISABLE`: Disable the pin
- `INPUT`: Configure as input pin
- `OUTPUT`: Configure as output pin
- `OUTPUT_OD`: Configure as open-drain output
- `INPUT_OUTPUT_OD`: Configure as input/output open-drain
- `INPUT_OUTPUT`: Configure as input/output
### GPIO Pin Pull Resistors
- `GPIOPinPullUp.ENABLE/DISABLE`: Enable/disable internal pull-up resistor
- `GPIOPinPullDown.ENABLE/DISABLE`: Enable/disable internal pull-down resistor
### GPIO Interrupts (`GPIOPinIntr`)
- `DISABLE`: Disable interrupts
- `RISING`: Trigger on rising edge
- `FALLING`: Trigger on falling edge
- `ANY`: Trigger on any edge
- `LOW_LEVEL`: Trigger on low level
- `HIGH_LEVEL`: Trigger on high level
### GPIO Pin States (`GPIOPinState`)
- `LOW`: Logic low (0V)
- `HIGH`: Logic high (3.3V)
## API Reference
### ESP32USBGPIO Class
#### Constructor
```python
ESP32USBGPIO(port)
```
- `port`: Serial port path (e.g., '/dev/ttyUSB0' on Linux, 'COM3' on Windows)
#### Methods
##### `setup(pin, mode, pull_up=DISABLE, pull_down=DISABLE, intr=DISABLE)`
Configure a GPIO pin with specified parameters.
**Parameters:**
- `pin` (int): GPIO pin number
- `mode` (GPIOPinMode): Pin mode configuration
- `pull_up` (GPIOPinPullUp): Pull-up resistor setting (optional)
- `pull_down` (GPIOPinPullDown): Pull-down resistor setting (optional)
- `intr` (GPIOPinIntr): Interrupt configuration (optional)
**Example:**
```python
# Setup pin 4 as input with pull-up resistor
gpio.setup(pin=4, mode=GPIOPinMode.INPUT, pull_up=GPIOPinPullUp.ENABLE)
```
##### `set(pin)`
Set a GPIO pin to HIGH state.
**Parameters:**
- `pin` (int): GPIO pin number
##### `reset(pin)`
Set a GPIO pin to LOW state.
**Parameters:**
- `pin` (int): GPIO pin number
##### `toggle(pin)`
Toggle the current state of a GPIO pin.
**Parameters:**
- `pin` (int): GPIO pin number
##### `pinState(pin)`
Read the current state of a specific GPIO pin.
**Parameters:**
- `pin` (int): GPIO pin number
**Returns:**
- `GPIOPinState`: Current pin state (HIGH or LOW)
##### `portState()`
Get the current state of all GPIO pins.
**Returns:**
- `list[int]`: [count, state] where state contains bit-packed pin states
## Communication Protocol
The library communicates with the ESP32 using a custom serial protocol:
### Commands Sent to ESP32:
- `INIT;pin;mode;pull_up;pull_down;intr` - Initialize pin
- `SET;pin` - Set pin high
- `RESET;pin` - Set pin low
- `TOGGLE;pin` - Toggle pin state
- `GET;pin` - Read pin state
### Responses from ESP32:
- `OK:pin` - Command executed successfully
- `ERROR:pin:error_code` - Command failed with error code
- `STATE:pin:state` - Pin state response
- `IN_GPIO_LEVEL:count:state` - Port state update
## Error Handling
The library includes comprehensive error handling:
```python
try:
gpio.setup(pin=99, mode=GPIOPinMode.OUTPUT) # Invalid pin
except Exception as e:
print(f"Setup failed: {e}")
```
## Thread Safety
The library uses a background thread for serial communication, making it safe to use in multi-threaded applications. Serial data is continuously monitored and processed asynchronously.
## Hardware Requirements
- ESP32 development board with USB connection
- **ESP32 Firmware**: Compatible ESP32 firmware that implements the GPIO command protocol
- **Required**: Flash the ESP-IDF firmware from https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF
- This firmware handles the serial communication protocol and GPIO operations
- USB cable for connection to host computer
## Setup Instructions
1. **Flash ESP32 Firmware**:
```bash
git clone https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF.git
cd ESP32-USB-GPIO-ESPIDF
# Follow the ESP-IDF setup and flashing instructions in that repository
```
2. **Install Python Library**:
```bash
git clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git
cd ESP32-USB-GPIO-PY
pip install .
```
3. **Connect and Test**:
```python
from esp32_usb_gpio import ESP32USBGPIO, GPIOPinMode
gpio = ESP32USBGPIO('/dev/ttyUSB0') # Your ESP32 port
gpio.setup(pin=2, mode=GPIOPinMode.OUTPUT)
gpio.set(pin=2)
```
## Supported Platforms
- Linux
- Windows
- macOS
## Dependencies
- `pyserial`: For serial communication
- `threading`: For asynchronous data handling (built-in)
- `dataclasses`: For data structure definitions (built-in)
- `enum`: For enumeration definitions (built-in)
## License
This project is licensed under the terms specified in the LICENSE file.
## Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
## Troubleshooting
### Common Issues:
1. **Serial Port Access**: Ensure you have proper permissions to access the serial port
```bash
sudo usermod -a -G dialout $USER # Linux
```
2. **Port Not Found**: Verify the correct serial port path for your system
```bash
ls /dev/tty* # Linux/macOS
```
3. **Connection Issues**: Check that the ESP32 is properly connected and running compatible firmware
4. **Timeout Errors**: Ensure the ESP32 firmware is responding to commands correctly
Raw data
{
"_id": null,
"home_page": "https://github.com/aakash4895/ESP32-USB-GPIO-PY",
"name": "esp32-usb-gpio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "esp32, gpio, usb, serial, communication, hardware, control",
"author": "Aakash Singh",
"author_email": "aakash.singh4895@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6e/06/9034ad2b2c55cc00c57f6211889c7b2809b6a980f6340d6efd01a0c8c741/esp32-usb-gpio-0.1.1.tar.gz",
"platform": null,
"description": "# ESP32 USB GPIO Python Library\n\nA Python library for controlling ESP32 GPIO pins via USB serial communication. This library provides a simple and intuitive interface to interact with ESP32 GPIO pins remotely through USB connection.\n\n**Note**: This library requires compatible ESP32 firmware to be flashed on your ESP32 device. The corresponding ESP-IDF firmware code is available at: https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF\n\n## Features\n\n- **GPIO Pin Control**: Configure, set, reset, and toggle GPIO pins\n- **Pin State Reading**: Read individual pin states and port states\n- **Multiple GPIO Modes**: Support for input, output, open-drain configurations\n- **Pull-up/Pull-down Resistors**: Configure internal pull resistors\n- **Interrupt Support**: Configure GPIO interrupts (rising, falling, level-based)\n- **Thread-safe Serial Communication**: Asynchronous serial data handling\n- **Error Handling**: Comprehensive error reporting and exception handling\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n```bash\npip install esp32-usb-gpio\n```\n\n### Option 2: Install from Source\nClone this repository and install:\n```bash\ngit clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git\ncd ESP32-USB-GPIO-PY\npip install .\n```\n\n### Option 3: Development Installation\nFor development, install in editable mode:\n```bash\ngit clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git\ncd ESP32-USB-GPIO-PY\npip install -e .\n```\n\n### Dependencies\nThe package automatically installs its dependencies:\n- `pyserial`: For serial communication with ESP32\n\n## Quick Start\n\n```python\nfrom esp32_usb_gpio import ESP32USBGPIO, GPIOPinMode, GPIOPinState\n\n# Initialize connection to ESP32\ngpio = ESP32USBGPIO('/dev/ttyUSB0') # Replace with your port\n\n# Setup GPIO pin 2 as output\ngpio.setup(pin=2, mode=GPIOPinMode.OUTPUT)\n\n# Set pin high\ngpio.set(pin=2)\n\n# Read pin state\nstate = gpio.pinState(pin=2)\nprint(f\"Pin 2 state: {'HIGH' if state == GPIOPinState.HIGH else 'LOW'}\")\n\n# Toggle pin\ngpio.toggle(pin=2)\n\n# Reset pin to low\ngpio.reset(pin=2)\n```\n\n## Package Information\n\n- **Package Name**: esp32-usb-gpio\n- **Version**: 0.1.1\n- **Author**: Aakash Singh\n- **License**: GPL-3.0\n- **Python Compatibility**: Python 3.7+\n\n## Core Classes and Enums\n\n### GPIO Pin Modes (`GPIOPinMode`)\n- `DISABLE`: Disable the pin\n- `INPUT`: Configure as input pin\n- `OUTPUT`: Configure as output pin\n- `OUTPUT_OD`: Configure as open-drain output\n- `INPUT_OUTPUT_OD`: Configure as input/output open-drain\n- `INPUT_OUTPUT`: Configure as input/output\n\n### GPIO Pin Pull Resistors\n- `GPIOPinPullUp.ENABLE/DISABLE`: Enable/disable internal pull-up resistor\n- `GPIOPinPullDown.ENABLE/DISABLE`: Enable/disable internal pull-down resistor\n\n### GPIO Interrupts (`GPIOPinIntr`)\n- `DISABLE`: Disable interrupts\n- `RISING`: Trigger on rising edge\n- `FALLING`: Trigger on falling edge\n- `ANY`: Trigger on any edge\n- `LOW_LEVEL`: Trigger on low level\n- `HIGH_LEVEL`: Trigger on high level\n\n### GPIO Pin States (`GPIOPinState`)\n- `LOW`: Logic low (0V)\n- `HIGH`: Logic high (3.3V)\n\n## API Reference\n\n### ESP32USBGPIO Class\n\n#### Constructor\n```python\nESP32USBGPIO(port)\n```\n- `port`: Serial port path (e.g., '/dev/ttyUSB0' on Linux, 'COM3' on Windows)\n\n#### Methods\n\n##### `setup(pin, mode, pull_up=DISABLE, pull_down=DISABLE, intr=DISABLE)`\nConfigure a GPIO pin with specified parameters.\n\n**Parameters:**\n- `pin` (int): GPIO pin number\n- `mode` (GPIOPinMode): Pin mode configuration\n- `pull_up` (GPIOPinPullUp): Pull-up resistor setting (optional)\n- `pull_down` (GPIOPinPullDown): Pull-down resistor setting (optional)\n- `intr` (GPIOPinIntr): Interrupt configuration (optional)\n\n**Example:**\n```python\n# Setup pin 4 as input with pull-up resistor\ngpio.setup(pin=4, mode=GPIOPinMode.INPUT, pull_up=GPIOPinPullUp.ENABLE)\n```\n\n##### `set(pin)`\nSet a GPIO pin to HIGH state.\n\n**Parameters:**\n- `pin` (int): GPIO pin number\n\n##### `reset(pin)`\nSet a GPIO pin to LOW state.\n\n**Parameters:**\n- `pin` (int): GPIO pin number\n\n##### `toggle(pin)`\nToggle the current state of a GPIO pin.\n\n**Parameters:**\n- `pin` (int): GPIO pin number\n\n##### `pinState(pin)`\nRead the current state of a specific GPIO pin.\n\n**Parameters:**\n- `pin` (int): GPIO pin number\n\n**Returns:**\n- `GPIOPinState`: Current pin state (HIGH or LOW)\n\n##### `portState()`\nGet the current state of all GPIO pins.\n\n**Returns:**\n- `list[int]`: [count, state] where state contains bit-packed pin states\n\n## Communication Protocol\n\nThe library communicates with the ESP32 using a custom serial protocol:\n\n### Commands Sent to ESP32:\n- `INIT;pin;mode;pull_up;pull_down;intr` - Initialize pin\n- `SET;pin` - Set pin high\n- `RESET;pin` - Set pin low\n- `TOGGLE;pin` - Toggle pin state\n- `GET;pin` - Read pin state\n\n### Responses from ESP32:\n- `OK:pin` - Command executed successfully\n- `ERROR:pin:error_code` - Command failed with error code\n- `STATE:pin:state` - Pin state response\n- `IN_GPIO_LEVEL:count:state` - Port state update\n\n## Error Handling\n\nThe library includes comprehensive error handling:\n\n```python\ntry:\n gpio.setup(pin=99, mode=GPIOPinMode.OUTPUT) # Invalid pin\nexcept Exception as e:\n print(f\"Setup failed: {e}\")\n```\n\n## Thread Safety\n\nThe library uses a background thread for serial communication, making it safe to use in multi-threaded applications. Serial data is continuously monitored and processed asynchronously.\n\n## Hardware Requirements\n\n- ESP32 development board with USB connection\n- **ESP32 Firmware**: Compatible ESP32 firmware that implements the GPIO command protocol\n - **Required**: Flash the ESP-IDF firmware from https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF\n - This firmware handles the serial communication protocol and GPIO operations\n- USB cable for connection to host computer\n\n## Setup Instructions\n\n1. **Flash ESP32 Firmware**:\n ```bash\n git clone https://github.com/aakash4895/ESP32-USB-GPIO-ESPIDF.git\n cd ESP32-USB-GPIO-ESPIDF\n # Follow the ESP-IDF setup and flashing instructions in that repository\n ```\n\n2. **Install Python Library**:\n ```bash\n git clone https://github.com/aakash4895/ESP32-USB-GPIO-PY.git\n cd ESP32-USB-GPIO-PY\n pip install .\n ```\n\n3. **Connect and Test**:\n ```python\n from esp32_usb_gpio import ESP32USBGPIO, GPIOPinMode\n gpio = ESP32USBGPIO('/dev/ttyUSB0') # Your ESP32 port\n gpio.setup(pin=2, mode=GPIOPinMode.OUTPUT)\n gpio.set(pin=2)\n ```\n\n## Supported Platforms\n\n- Linux\n- Windows\n- macOS\n\n## Dependencies\n\n- `pyserial`: For serial communication\n- `threading`: For asynchronous data handling (built-in)\n- `dataclasses`: For data structure definitions (built-in)\n- `enum`: For enumeration definitions (built-in)\n\n## License\n\nThis project is licensed under the terms specified in the LICENSE file.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.\n\n## Troubleshooting\n\n### Common Issues:\n\n1. **Serial Port Access**: Ensure you have proper permissions to access the serial port\n ```bash\n sudo usermod -a -G dialout $USER # Linux\n ```\n\n2. **Port Not Found**: Verify the correct serial port path for your system\n ```bash\n ls /dev/tty* # Linux/macOS\n ```\n\n3. **Connection Issues**: Check that the ESP32 is properly connected and running compatible firmware\n\n4. **Timeout Errors**: Ensure the ESP32 firmware is responding to commands correctly\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A Python library for controlling ESP32 GPIO pins via USB serial communication.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/aakash4895/ESP32-USB-GPIO-PY"
},
"split_keywords": [
"esp32",
" gpio",
" usb",
" serial",
" communication",
" hardware",
" control"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2e4bdd1f55744cbbeffa02ff6e45ed122de7dd4ced2edf34f81f6369b6238694",
"md5": "ce5c952621bb20f7dbe2ccf81461f28a",
"sha256": "35e32024dbae14c41f38e62a69b65d1ab35fc019ab6bfdd7f9f409c7f4d08c25"
},
"downloads": -1,
"filename": "esp32_usb_gpio-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce5c952621bb20f7dbe2ccf81461f28a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5331,
"upload_time": "2025-07-16T12:01:23",
"upload_time_iso_8601": "2025-07-16T12:01:23.781736Z",
"url": "https://files.pythonhosted.org/packages/2e/4b/dd1f55744cbbeffa02ff6e45ed122de7dd4ced2edf34f81f6369b6238694/esp32_usb_gpio-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6e069034ad2b2c55cc00c57f6211889c7b2809b6a980f6340d6efd01a0c8c741",
"md5": "44a1a45a3ffd3b392789462959a7690e",
"sha256": "6d3349867a81b386d5183cc3545129081ee141281ae1f2b0619beaf087b44694"
},
"downloads": -1,
"filename": "esp32-usb-gpio-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "44a1a45a3ffd3b392789462959a7690e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5486,
"upload_time": "2025-07-16T12:01:25",
"upload_time_iso_8601": "2025-07-16T12:01:25.014000Z",
"url": "https://files.pythonhosted.org/packages/6e/06/9034ad2b2c55cc00c57f6211889c7b2809b6a980f6340d6efd01a0c8c741/esp32-usb-gpio-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 12:01:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aakash4895",
"github_project": "ESP32-USB-GPIO-PY",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "esp32-usb-gpio"
}
JSON
