Diagnostics and Profiling

When a device is not behaving as expected, you need data — chip identity, flash status, memory contents, and transport performance. mcesptool provides three diagnostic tools that gather this information without modifying anything on the device.

Quick device overview

The esp_diagnostic_report tool collects chip identity, MAC address, and flash information in a single call.

esp_diagnostic_report({
  "port": "/dev/ttyUSB0"
})

The response includes:

• chip: the detected chip type (e.g., “ESP32-D0WDQ6”)
• chip_id: the hardware chip ID
• mac_address: the factory-programmed MAC
• flash.manufacturer: the SPI flash manufacturer ID
• flash.device: the flash device ID
• flash.size: detected flash size (e.g., “4MB”)

Include a memory snapshot

Pass include_memory: true to add a 256-byte hex dump from address 0x0:

esp_diagnostic_report({
  "port": "/dev/ttyUSB0",
  "include_memory": true
})

The memory_dump_0x0 field contains the formatted hex output. This is useful for confirming whether the bootloader region has been written or is still erased (0xFF).

Inspect memory regions

The esp_memory_dump tool reads arbitrary memory addresses and returns a formatted hex dump with ASCII interpretation.

esp_memory_dump({
  "port": "/dev/ttyUSB0",
  "start_address": "0x0",
  "size": "256B"
})

Useful memory regions

Bootloader

esp_memory_dump({
  "port": "/dev/ttyUSB0",
  "start_address": "0x1000",
  "size": "256B"
})

On ESP32, the second-stage bootloader starts at 0x1000. The first bytes should contain the image header if firmware has been flashed.

Peripheral registers

esp_memory_dump({
  "port": "/dev/ttyUSB0",
  "start_address": "0x3FF00000",
  "size": "64B"
})

The 0x3FF00000 region contains peripheral register space on ESP32. Reading here can help verify hardware configuration state.

Partition table

esp_memory_dump({
  "port": "/dev/ttyUSB0",
  "start_address": "0x8000",
  "size": "1KB"
})

The partition table lives at 0x8000. Valid entries start with the magic bytes AA 50. An all-FF dump means no partition table has been written.

Reading hex dump output

The hex dump format shows 16 bytes per line with three columns:

0x00001000: e9 09 02 20 08 10 40 00 ee 00 00 00 05 00 04 00  ... ..@.........
0x00001010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................

• Left column: memory address
• Middle column: hex bytes (16 per line)
• Right column: ASCII interpretation (. for non-printable bytes)

Tip

The maximum dump size is 1MB. For larger flash reads, use esp_flash_read instead — it writes directly to a file and handles larger regions more efficiently.

Performance profiling

The esp_performance_profile tool measures serial transport speed by timing a series of esptool operations. This is useful for comparing physical serial performance against QEMU, or for diagnosing slow connections.

esp_performance_profile({
  "port": "/dev/ttyUSB0"
})

The profiler runs four operations and reports individual timings:

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)	Flash read throughput (bytes/second calculated)

The summary section reports average latency across all successful operations and the total operations tested.

Compare physical vs. QEMU performance

Run the profiler against both a physical device and a QEMU instance to quantify the performance difference:

1. Profile the physical device:

   esp_performance_profile({
     "port": "/dev/ttyUSB0"
   })

2. Profile a QEMU instance:

   esp_performance_profile({
     "port": "socket://localhost:5555"
   })

3. Compare the average_latency_seconds and throughput_bytes_per_sec values from each run.

QEMU typically shows lower latency for metadata operations (no real serial transport) but similar or slower throughput for bulk reads due to emulation overhead.

See the Diagnostics reference for full parameter details.