Welcome to the ESP GPIO Tool! This repository is a Python-based, open-source package that is used for developing applications with Espressif's SoCs.
It provides a few developer-facing tools around GPIO pin planning and validation:
- CLI (
espins-cli): validate a YAML pin assignment, and inspect chip GPIO/peripheral capabilities. - GUI (
espins): a simple desktop UI for the checker. - GPIO MCP server: a MCP server that can be used by models to access the core functions.
ESP GPIO Tool is meant to help you get started faster and catch common configuration mistakes. It is not a replacement for the chip's datasheet and TRM.
- The datasheet and TRM are authoritative. Always verify pin capabilities, electrical characteristics, and peripheral signal routing against the official documentation.
- Do not build production hardware solely based on information from this tool.
- If you spot a mismatch vs datasheet/TRM, please report it so we can fix it.
When reporting a mismatch, include:
- Chip and tool version (
espins-cli --versionif applicable) - What you expected vs what the tool reports (copy/paste output if possible)
- Datasheet/TRM reference (document name + section/page)
- A minimal config snippet (YAML) or CLI command that reproduces the issue
Clone the repository and install the Python package
pip install .ESP GPIO tool supports checking of pin assignment using a CLI and a simple GUI.
To print chip target names supported by the tool (and their SoC/package variants):
espins-cli targetsESP GPIO tool has also experimental implementation of interactive AI Agent that should help better understand user requirements and suggest a pin assignment. We also support MCP server for easier integration of tool into any agent. For more details see agent README.md
Getting a list of all possible functions might help with writing the function names correctly. Since there are some differences in names across the chips and also between datasheets and ESP-IDF. The following command will provide all functions available for the selected chip, split by peripherals.
espins-cli list-pins esp32The tool will check your pin assignment for completeness, correctness and potential collisions with pre-defined peripherals for debugging etc.
Example:
python -m esp_gpio_tool_cli check myconfig.yamlor
espins-cli check myconfig.yamlFor details regarding the format of the input file please refer to the Input file section.
The GUI version of a user input for the GPIO Assignment Checker can be used.
Note
If you want to use GUI for checker, install Python Tkinter.
Debian-based Linux (Ubuntu, Debian, etc.)
sudo apt-get install python3-tkmacOS
brew install python-tkWindows - if not installed use the Python installer to modify the installation and check the tcl/tk and IDLE (or similar) option to be included in the installation.
To invoke the GUI following command can be used:
python -m esp_gpio_toolor
espinsThe input file is expected to be in the YAML format. The file is expected to have a chip keyword in the header of the file. Without this header, the tool will assume the configuration file is for ESP32.
The body of the file should contain your assignment of the GPIOs. A pin number is used as a key and a function as a value. Duplicated keys are not allowed by the YAML format but the value can be a single function or an array. However, it is not recommended to use the pin for multiple functions.
There is also an optional key soc to specify which SoC is going to be used. This parameter can help to better define limitations of selected SoC, like not connected pins, in-package Flash/PSRAM that occupies some pins etc. The value is MPN (Manufacturer Part Number) which can be found on the package itself or in the Product Selector.
Example:
chip: esp32
soc: ESP32-PICO-V3
0: TOUCH0
3: [LEDC_HS_SIG_OUT0, LEDC_HS_SIG_OUT1, RMT_SIG_IN0]Some peripherals support changing modes of operation. The mode you select may require a different subset of the peripheral's pins. This helps the tool understand your needs and adjust its checks accordingly.
To see a list of supported modes, check the datasheet of your selected chip. Alternatively, you can check the definition in the esp_gpio_tool/targets/ folder. Here, you'll find your selected chip and can get a list of supported modes based on the peripheral.
If you select a mode that the peripheral does not support, the checker will not consider the mode change. Instead, it will continue in its default state and provide a list of supported modes.
Here's an example of a config file where the Quad mode of HSPI is selected:
chip: esp32
peripheral:
SPI:
HSPI: Quad SPI
2: HSPIWP
4: HSPIHD
12: HSPIQ
13: HSPID
14: HSPICLK
15: HSPICS0This is a high level look at the public API, meaning this section will focus more on providing examples for common functionality. For more details on all available methods and properties, please refer to docstrings in the code itself.
Please note that only functions listed below are part of the public API and all other functions are subject to change with any release.
# Get list of supported chips
from esp_gpio_tool_cli.chip import SUPPORTED_CHIPS
print(SUPPORTED_CHIPS) # This includes a list of names of chips without dash (e.g. esp32s3)
from esp_gpio_tool_cli.chip import ESP
# Create ESP class
esp = ESP("esp32")
# Optionally set MPN of chip - some have missing pins or even some extra were added between revisions
esp.set_soc("ESP32-PICO-D4")
# To get all possible MPN run
print(esp.soc_list)
# This will return dictionary of `Pin` classes with GPIO number as key.
print(esp.gpios)
# Get list of all GPIO pins
gpio_list = esp.get_gpio_list()
# To get list with power-domain, unwrap the dict of GPIO pins, e.g. "GPIO1 - VDD3P3_RTC"
gpio_list = [str(g) for g in esp.gpios.values()]
# Get list of peripherals
print(esp.peripherals)
# Get all pins for e.g. ADC (the key here is class name in peripheral.py)
print(esp.get_peripheral("ADC").all_pins)You can either run checker on already existing YAML filename or pass config as dictionary. For more details how to create a config please refer to Input File section.
from esp_gpio_tool_cli.checker import run_check
config = {
"chip": "esp32",
0: "TOUCH1",
3: ["LEDC_HS_SIG_OUT0", "LEDC_HS_SIG_OUT1", "RMT_SIG_IN0"],
}
out = run_check(config)
# Output is provided as a list of messages
print(out)- The
CHANGELOG.mdfile.
This document and the attached source code are released as Free Software under Apache License Version 2 or later. See the accompanying LICENSE file for a copy.
📘 If you are interested in contributing to this project, see the Project Contributing Guide.