Chip Control

The Chip Control component provides 7 tools for detecting ESP devices, managing connections, resetting chips, and capturing serial output. These tools form the foundation for all device interactions in mcesptool.

Port parameters accept physical serial ports (/dev/ttyUSB0, COM3) and QEMU virtual serial ports (socket://localhost:5555). When port is optional and omitted, auto-detection probes common serial ports.

esp_detect_chip

Detect the chip type and gather device information by running esptool chip-id (and optionally flash-id) as a subprocess.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or socket URI. Auto-detects if omitted.
`baud_rate`	`int \| None`	`None`	Baud rate. Uses server default (460800) if omitted.
`detailed`	`bool`	`False`	Include flash size, crystal frequency, and feature list.

Example

# Basic detection
result = await client.call_tool("esp_detect_chip", {
    "port": "/dev/ttyUSB0"
})

# Detailed detection with custom baud rate
result = await client.call_tool("esp_detect_chip", {
    "port": "socket://localhost:5555",
    "baud_rate": 115200,
    "detailed": True
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "baud_rate": 460800,
  "connection_time_seconds": 1.23,
  "chip_info": {
    "chip_type": "ESP32-S3",
    "mac_address": "aa:bb:cc:dd:ee:ff",
    "flash_size": "4MB",
    "crystal_frequency": "40MHz",
    "features": ["WiFi", "BLE", "Embedded PSRAM 8MB"]
  }
}

When detailed is False, the chip_info object contains only chip_type and mac_address.

esp_connect_advanced

Verify device connectivity with configurable retries, timeout, and stub loader settings. Internally runs esptool chip-id up to retry_count times with a delay between attempts.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or socket URI. Auto-detects if omitted.
`baud_rate`	`int \| None`	`None`	Baud rate. Uses server default if omitted.
`timeout`	`int \| None`	`None`	Connection timeout in seconds. Uses config default (30) if omitted.
`use_stub`	`bool`	`True`	Load ROM bootloader stub for faster operations.
`retry_count`	`int`	`3`	Number of connection attempts before giving up.

Example

result = await client.call_tool("esp_connect_advanced", {
    "port": "/dev/ttyUSB0",
    "timeout": 10,
    "retry_count": 5
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "baud_rate": 460800,
  "attempt": 2,
  "stub_loaded": true,
  "chip_type": "ESP32",
  "mac_address": "aa:bb:cc:dd:ee:ff"
}

On failure after all retries:

{
  "success": false,
  "error": "Timeout (30.0s)",
  "attempts": 5,
  "port": "/dev/ttyUSB0"
}

esp_reset_chip

Reset the ESP chip using different reset methods. Internally runs esptool chip-id with the --after flag set according to the reset type.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or socket URI. Auto-detects if omitted.
`reset_type`	`str`	`"hard"`	Reset method: `hard`, `soft`, or `bootloader`.

Reset Types

Value	esptool `--after`	Behavior
`hard`	`hard_reset`	Full hardware reset via DTR/RTS toggle. Device reboots and runs application.
`soft`	`soft_reset`	Soft reset. Device restarts without full power cycle.
`bootloader`	`no_reset`	Leaves the chip in bootloader mode after the command completes.

Example

result = await client.call_tool("esp_reset_chip", {
    "port": "/dev/ttyUSB0",
    "reset_type": "hard"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "reset_type": "hard",
  "timestamp": 1708732800.0
}

esp_scan_ports

Scan all common serial ports for connected ESP devices. Also includes any running QEMU virtual devices in the results.

Scans /dev/ttyUSB0-3 and /dev/ttyACM0-3 on Linux, COM1-COM20 on Windows, and /dev/cu.usbserial-* on macOS.

Parameters

Name	Type	Default	Description
`detailed`	`bool`	`False`	Include flash ID and extended info for each detected device.

Example

result = await client.call_tool("esp_scan_ports", {
    "detailed": True
})

Return Value

{
  "success": true,
  "detected_devices": [
    {
      "port": "/dev/ttyUSB0",
      "available": true,
      "chip_type": "ESP32",
      "mac_address": "aa:bb:cc:dd:ee:ff",
      "flash_size": "4MB"
    },
    {
      "port": "socket://localhost:5555",
      "chip_type": "esp32c3",
      "instance_id": "qemu-1",
      "source": "qemu",
      "available": true
    }
  ],
  "total_scanned": 9,
  "checked_ports": ["/dev/ttyUSB0", "/dev/ttyUSB1", "..."],
  "available_ports": ["/dev/ttyUSB0"],
  "qemu_devices": [{"..."}],
  "timestamp": 1708732800.0
}

esp_load_test_firmware

Load a pre-built test firmware for quick chip validation. Currently returns firmware metadata; actual flashing requires ESP-IDF integration.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or socket URI. Auto-detects if omitted.
`firmware_type`	`str`	`"blink"`	Test firmware type: `blink`, `hello_world`, or `wifi_scan`.

Firmware Types

Value	Description
`blink`	Simple LED blink test
`hello_world`	Serial output hello world
`wifi_scan`	WiFi network scanner

Example

result = await client.call_tool("esp_load_test_firmware", {
    "port": "/dev/ttyUSB0",
    "firmware_type": "hello_world"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "firmware_type": "hello_world",
  "description": "Serial output hello world",
  "note": "Test firmware loading requires ESP-IDF integration (coming soon)",
  "timestamp": 1708732800.0
}

esp_load_ram

Load and execute a binary in device RAM without touching flash. Uses esptool load-ram to transfer the binary. The program runs until the device is physically reset.

This is ideal for rapid development iteration — test changes without wearing out flash or waiting for a full flash cycle.

Parameters

Name	Type	Default	Description
`binary_path`	`str`	(required)	Path to the RAM-executable binary. Must be compiled for RAM execution.
`port`	`str \| None`	`None`	Serial port or socket URI. Auto-detects if omitted.

Example

result = await client.call_tool("esp_load_ram", {
    "binary_path": "/path/to/firmware-ram.bin",
    "port": "/dev/ttyUSB0"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "binary_path": "/path/to/firmware-ram.bin",
  "file_size": 32768,
  "elapsed_seconds": 2.15,
  "note": "Binary loaded to RAM and executing. Reset device to stop."
}

esp_serial_monitor

Open the serial port and capture device output for a specified duration. Useful for reading boot messages, debug output, or application logs without switching to a separate terminal monitor.

Parameters

Name	Type	Default	Description
`port`	`str`	(required)	Serial port. No auto-detect for monitor operations.
`baud_rate`	`int`	`115200`	Serial baud rate.
`duration_seconds`	`float`	`5.0`	Capture duration. Clamped to 0.1—30 seconds.
`reset_on_connect`	`bool`	`True`	Reset device before capturing to get boot messages.

Example

result = await client.call_tool("esp_serial_monitor", {
    "port": "/dev/ttyUSB0",
    "baud_rate": 115200,
    "duration_seconds": 10.0,
    "reset_on_connect": True
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "baud_rate": 115200,
  "duration_seconds": 10.04,
  "reset_performed": true,
  "line_count": 42,
  "output": "rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)\nI (0) cpu_start: Starting scheduler...\n..."
}

The output field contains the raw serial text with lines joined by \n. The line_count reflects the number of complete lines captured during the duration window.