Debug ESP32 firmware with a serial monitor your AI agent can use

Serial settings for ESP32

• Port: the serial port (COM… on Windows, /dev/ttyUSB… or /dev/ttyACM… on Linux) of the board's USB-to-UART bridge (for example CP210x or CH340), or of the native USB port on boards that have one.
• Baud rate: whatever your firmware sets, usually 115200 (Serial.begin(115200) in Arduino, the default console speed in ESP-IDF). The ESP32's ROM boot messages also use 115200.
• ESP8266: its ROM prints boot messages at 74880. Add it as a custom baud rate to read them.
• DTR and RTS: most ESP32 dev boards wire these lines to EN and GPIO0 for auto-reset. If the board resets or stays in download mode when you connect, change DTR when connecting and RTS when connecting in the connection's settings.

Save it as a connection, such as "DevKitC". Termethos reconnects by itself when the board resets or you re-plug it.

Readable logs

Start a line with !E, !W or !I to mark it as an error, warning or info line, and !# to box it. These levels are also what an AI agent filters on with read_trace.

void setup() {
  Serial.begin(115200);
  Serial.println("!#Greenhouse v1.4");
  Serial.printf("!Ireset reason: %d\n", esp_reset_reason());
  WiFi.begin(ssid, pass);
  // ...
  Serial.println("ready");
}

void readSensor() {
  if (!sensor.begin()) {
    Serial.println("!Esensor not found on I2C");
  }
}

ESP-IDF logs: ESP_LOGE and ESP_LOGW lines show in their colors. An agent finds them with a regular expression, such as search: "^E \(" for errors.

Live telemetry on the dashboard

Print @{field:value} and the value appears in one of 24 dashboard fields instead of scrolling past in the log. The field that changed last is highlighted, and an agent can read all of them with read_dashboard.

void reportTelemetry() {
  Serial.printf("@{0:%u}", ESP.getFreeHeap());   // field 0: free heap
  Serial.printf("@{1:%d}", WiFi.RSSI());         // field 1: Wi-Fi signal
  Serial.printf("@{2:%s}", WiFi.isConnected() ? "online" : "offline");
}

More about the dashboard

Reset the ESP32 from a hotkey

A quick command can run a JavaScript script that sets the DTR and RTS lines, which is how the board's auto-reset circuit works. Add this to commands in the advanced settings:

{
  "name": "Reset board",
  "command": "reset",
  "description": "Reset the ESP32 through DTR/RTS",
  "hotKey": "alt+r",
  "script": "async (port) => { port.set({ dtr: false, rts: true }); await new Promise(r => setTimeout(r, 100)); port.set({ dtr: false, rts: false }); }"
}

Termethos shows the script and asks before it runs the first time. An AI agent can run it with run_quick_command once you allow scripts for agents.

Connect Claude Code to the ESP32

1. Turn on the MCP server in Termethos and add it to Claude Code. Setup
2. Allow connecting and disconnecting, so Claude Code can free the port while it flashes. Allow creating and changing connections too, and it can set up the board's connection for you.
3. Tell it how your project builds and flashes, for example in CLAUDE.md:

# PlatformIO
pio run -t upload
# Arduino CLI
arduino-cli compile --upload -p COM5 --fqbn esp32:esp32:esp32 .
# ESP-IDF
idf.py -p COM5 flash

The agent frees the port with disconnect, flashes, reconnects with connect, then waits for your boot message and reads the result.

Example: a reboot loop after Wi-Fi connects

A prompt such as "The board reboots after Wi-Fi connects. Find out why and fix it." lets the agent work through it on the board:

1. It reads the trace around the reboot. A line such as Brownout detector was triggered or a panic backtrace tells it what kind of reset it was.
2. It reads the dashboard to see free heap and signal strength just before the reset.
3. It sends a diagnostic command your firmware supports, or runs your reset script and watches the boot with wait_for_trace.
4. It proposes a fix in the source, such as lowering Wi-Fi transmit power during start-up or fixing a buffer, and flashes it.
5. It waits for ready and reads errors since the reset to confirm the reboot is gone.

An illustration of the steps: what the agent finds depends on your board and firmware.