Arduino Serial Monitor

This skill provides advanced tools for reading and analyzing serial monitor data from Arduino boards, enhancing the debugging experience beyond the basic Arduino IDE serial monitor.

Features

• Real-time Serial Monitoring: Connect to Arduino serial ports and display data in real-time
• Data Logging: Save serial output to files with timestamps for later analysis
• Filtering & Pattern Matching: Filter output by keywords, regex patterns, or data types
• Error Detection: Automatically highlight common error patterns and warnings
• Multiple Format Support: Handle different data formats (text, JSON, CSV, binary)
• Cross-platform: Works with Windows, macOS, and Linux serial ports

Structured Debugging Workflow

1. Record the exact board/revision, firmware/image identifier, toolchain and

versions, port, baud, reset cause if known, and timestamp source.

1. Prefer one line per event with stable fields such as

tms=123 level=INFO event=sensorread value=...; keep secrets and tokens out of output.

1. Capture the unfiltered log before filtering. Preserve the first boot lines,

reset/brownout/watchdog messages, and the transition that reproduces the symptom.

1. Label conclusions as build, upload, hardware, system, or deployment

evidence. Report the result by proof stages. A clean serial stream is not proof that pins, power, or the full system are correct.

1. Pair with hardware-tdd for a test matrix and embedded-project-loop when

the next observation must come from a user-operated board.

Recommended C++ Event Format

Serial.print("t_ms=");
Serial.print(millis());
Serial.print(" level=INFO event=ready board=");
Serial.println(BOARD_ID);

Use a fixed, bounded format appropriate to the board's memory budget. Do not log Wi-Fi passwords, API keys, certificates, tokens, or private data.

Usage

Basic Serial Monitoring

# Monitor serial port with default settings (9600 baud)
uv run --no-project scripts/monitor_serial.py --port COM3

# Specify baud rate and output file
uv run --no-project scripts/monitor_serial.py --port /dev/ttyACM0 --baud 115200 --output debug.log

# Filter for specific patterns
uv run --no-project scripts/monitor_serial.py --port COM3 --filter "ERROR|WARNING"

Advanced Debugging

# Parse JSON data from serial
uv run --no-project scripts/monitor_serial.py --port COM3 --format json --pretty

# Monitor with timestamp and color coding
uv run --no-project scripts/monitor_serial.py --port COM3 --timestamp --color

# Detect common Arduino errors
uv run --no-project scripts/monitor_serial.py --port COM3 --detect-errors

Script Options

• --port: Serial port (e.g., COM3, /dev/ttyACM0)
• --baud: Baud rate (default: 9600)
• --output: Output file for logging
• --filter: Regex pattern to filter lines
• --format: Data format (text, json, csv, binary)
• --timestamp: Add timestamps to output
• --color: Enable color-coded output
• --detect-errors: Highlight common error patterns
• --timeout: Connection timeout in seconds

Common Arduino Debugging Scenarios

Memory Issues

Filter for: "low memory|stack overflow|heap"

Sensor Data Validation

Filter for: "sensor|reading|value"
Format as: json

Timing Analysis

Enable: --timestamp
Filter for: "start|end|duration"

Communication Errors

Filter for: "timeout|failed|error"
Enable: --detect-errors

Integration with Arduino CLI

# Compile and upload, then monitor
arduino-cli compile --fqbn arduino:avr:uno sketch/
arduino-cli upload -p COM3 --fqbn arduino:avr:uno sketch/
uv run --no-project scripts/monitor_serial.py --port COM3

Troubleshooting

Port Not Found

• Check arduino-cli board list for available ports
• Ensure Arduino is connected and drivers are installed
• Try different port names (COM1-COM99 on Windows, /dev/ttyACM* on Linux)

No Data Received

• Verify baud rate matches Arduino sketch (Serial.begin(9600))
• Check USB cable connection
• Reset Arduino board while monitoring

Permission Errors (Linux/macOS)

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Logout and login again

Evidence And Privacy

Record the board, firmware/image version, toolchain, baud, port, reset cause, and timestamp source. Label serial output as hardware or system evidence only when it was captured on the target. Redact Wi-Fi passwords, API keys, certificates, tokens, and personal data before saving logs or sharing them.

Dependencies

• Python 3.8+
• uv 0.4+ (the script declares pyserial and colorama inline)
• Run the self-contained helper with uv run --no-project scripts/monitor_serial.py --help.

Examples

Basic Temperature Sensor Monitoring

// Arduino sketch
void setup() {
  Serial.begin(9600);
}

void loop() {
  float temp = analogRead(A0) * 0.488;
  Serial.print("Temperature: ");
  Serial.print(temp);
  Serial.println(" C");
  delay(1000);
}

uv run --no-project scripts/monitor_serial.py --port COM3 --filter "Temperature" --timestamp

JSON Data Parsing

// Arduino sketch with JSON output
#include <ArduinoJson.h>

void setup() {
  Serial.begin(115200);
}

void loop() {
  StaticJsonDocument<200> doc;
  doc["temperature"] = analogRead(A0) * 0.488;
  doc["humidity"] = analogRead(A1) * 0.146;
  doc["timestamp"] = millis();
  serializeJson(doc, Serial);
  Serial.println();
  delay(2000);
}

uv run --no-project scripts/monitor_serial.py --port COM3 --format json --pretty

Shared Output Contract

Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md): state assumptions, required tools and versions, implementation steps, tests/evidence by proof stage, known limitations, and recovery/security notes.