ESP32 MCP IO Extender

ESP32-C3 firmware + Python library for GPIO/UART control over serial JSONL.

This repo is the source of truth for:

• firmware protocol and safety policy,
• Python transport abstraction (EspGpioBridge),
• optional MCP server entrypoint,
• higher-level workbench abstraction (HaloBoardWorkbench).

Repository layout

• firmware/ PlatformIO Arduino firmware
• src/esp32_mcp_io_extender/ installable Python package
• host/ compatibility wrappers for legacy script paths
• docs/serial_protocol.md protocol contract
• docs/abstraction_mapping.md high-level abstraction model
• docs/agent_runbook.md deterministic validation flow

Install the Python library

From git (recommended for cross-repo integration):

pip install 'esp32-mcp-io-extender @ git+https://github.com/jbp-sy/esp32-mcp-io-extender.git@main'

With MCP support:

pip install 'esp32-mcp-io-extender[mcp] @ git+https://github.com/jbp-sy/esp32-mcp-io-extender.git@main'

Local dev install:

pip install -e .
# optional test/dev deps
pip install -e '.[dev,mcp]'

Python usage

Low-level bridge API

from esp32_mcp_io_extender import EspGpioBridge, SerialConfig

bridge = EspGpioBridge(SerialConfig(port="/dev/tty.usbmodem1101", auto_port=False))
bridge.call("set_mode", pin=4, mode="output")
bridge.call("write", pin=4, value=1)

High-level workbench API

from esp32_mcp_io_extender import (
    BoardSignal,
    EspGpioBridge,
    HaloBoardWorkbench,
    HaloWorkbenchConfig,
    SerialConfig,
)

bridge = EspGpioBridge(SerialConfig(port="/dev/tty.usbmodem1101", auto_port=False))
config = HaloWorkbenchConfig(
    signals={
        "power": BoardSignal(name="power", pin=4),
        "reset": BoardSignal(name="reset", pin=5),
    },
    gp_aliases={"GP45": 4},
)

workbench = HaloBoardWorkbench(bridge, config)
workbench.power_on()
workbench.reset()
workbench.gp("GP45").set(1)

See docs/abstraction_mapping.md for mapping guidance.

CLI usage

After install:

esp32-mcp-io-extender --help
esp32-mcp-io-extender --port /dev/tty.usbmodem1101 ping

Legacy compatibility script still works:

cd host
python gpio_cli.py --port /dev/tty.usbmodem1101 ping

MCP server usage

ESP_GPIO_PORT=/dev/tty.usbmodem1101 python -m esp32_mcp_io_extender.mcp_server

Legacy compatibility script:

cd host
ESP_GPIO_PORT=/dev/tty.usbmodem1101 python mcp_gpio_server.py

Firmware setup

Build:

cd firmware
pio run

Flash:

cd firmware
pio run -t upload --upload-port /dev/tty.usbmodem1101

Protocol and safety

• Protocol contract: docs/serial_protocol.md
• Validation checklist: docs/validation.md
• Deterministic runbook: docs/agent_runbook.md

Important defaults for current board profile:

• allowed GPIOs: 0,1,3,4,5,7
• blocked/reserved include 2,6,8,9,10,18,19,20,21
• UART bridge pins are fixed: RX=20, TX=21