Diagnostics

The Diagnostics component provides 3 tools for inspecting device memory, profiling serial communication performance, and generating comprehensive device reports. All operations use esptool subprocess commands and work with both physical devices and QEMU virtual devices.

esp_memory_dump

Read raw bytes from an arbitrary memory address on the device using esptool dump-mem. The output is formatted as a hex dump with ASCII representation.

For flash memory reads, use esp_flash_read instead — it supports larger ranges and is faster for flash-specific operations.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.
`start_address`	`str`	`"0x0"`	Memory address to start reading (hex string).
`size`	`str`	`"1KB"`	Number of bytes to read. Accepts `"256B"`, `"1KB"`, `"4KB"`, hex, or decimal. Maximum 1MB.

Size Format

Format	Example	Bytes
Bytes	`"256B"`	256
Kilobytes	`"1KB"`, `"4KB"`	1024, 4096
Megabytes	`"1MB"`	1048576
Hex	`"0x1000"`	4096
Decimal	`"512"`	512

Example

result = await client.call_tool("esp_memory_dump", {
    "port": "/dev/ttyUSB0",
    "start_address": "0x3ff00000",
    "size": "256B"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "start_address": "0x3ff00000",
  "bytes_read": 256,
  "hex_dump": "0x3ff00000: 00 00 00 00 ff ff ff ff 00 00 00 00 00 00 00 00  ................\n0x3ff00010: 13 00 00 60 00 00 00 00 00 00 00 00 00 00 00 00  ...`............\n...",
  "truncated": false
}

The hex dump is capped at 64 lines (1KB of data). When the dump exceeds this limit, truncated is true.

Each line shows: address: hex bytes (16 per line) ASCII representation

esp_performance_profile

Measure serial transport speed by timing a sequence of esptool operations. Reports individual operation latencies and an overall average. Useful for comparing physical serial vs QEMU socket performance, or for diagnosing slow connections.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.
`duration`	`int`	`30`	Reserved for future use. Does not control timing.

Operations Tested

Operation	What it measures
`chip-id`	Lightweight command round-trip latency
`flash-id`	SPI flash register read latency
`read-mac`	eFuse read latency
`read-flash (4KB)`	Bulk data transfer throughput

Example

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

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "measurements": [
    {"operation": "chip-id", "elapsed_seconds": 0.845, "success": true},
    {"operation": "flash-id", "elapsed_seconds": 0.912, "success": true},
    {"operation": "read-mac", "elapsed_seconds": 0.789, "success": true},
    {
      "operation": "read-flash (4KB)",
      "elapsed_seconds": 1.234,
      "success": true,
      "throughput_bytes_per_sec": 3319.0
    }
  ],
  "summary": {
    "operations_tested": 4,
    "operations_succeeded": 4,
    "average_latency_seconds": 0.945
  }
}

The throughput_bytes_per_sec field is only present for the flash read operation. The average_latency_seconds is computed across all successful operations.

esp_diagnostic_report

Generate a comprehensive device identification report by gathering chip identity, MAC address, flash information, and optionally a small memory dump. All data is collected in a single call.

For security-focused analysis, use esp_security_audit instead.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.
`include_memory`	`bool`	`False`	Include a 256-byte memory dump from address `0x0`.

Example

result = await client.call_tool("esp_diagnostic_report", {
    "port": "/dev/ttyUSB0",
    "include_memory": True
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "chip": "ESP32-S3",
  "chip_id": "0x00f01d83",
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "flash": {
    "manufacturer": "0xef",
    "device": "0x4016",
    "size": "4MB"
  },
  "memory_dump_0x0": "0x00000000: e9 07 02 30 ..."
}

The memory_dump_0x0 field is only present when include_memory is True. If the initial chip-id command fails, the tool returns immediately with the connection error instead of attempting further operations.