arduino-serial-monitor

Arduino Serial Monitor

本技能为读取和分析 Arduino 板串口监视器数据提供进阶工具，增强超出 Arduino IDE 基础串口监视器的调试体验。桌面可视化/测试台控制台请参阅 references/desktop-console.md；无线传输与追踪语义属于 wireless-telemetry，不要在此重复其驱动或测量工作流。原生 ESP-IDF 日志也可作为串口诊断的有效输入，并不意味着使用 Arduino 框架。

功能

实时串口监视：连接 Arduino 串口并实时显示数据。
数据日志：将串口输出保存到文件并附带时间戳，便于后续分析。
过滤与模式匹配：按关键词、正则表达式或数据类型过滤输出。
错误检测：自动高亮常见错误模式与警告。
多格式支持：处理不同数据格式（文本、JSON、CSV、二进制）。
跨平台：支持 Windows、macOS 和 Linux 串口。

结构化调试工作流

记录确切的开发板/版本、固件/镜像标识、工具链与版本、端口、波特率、复位原因（若已知）以及时间戳来源。
优先采用每条事件一行并带稳定字段，例如 t_ms=123 level=INFO event=sensor_read value=...；输出中不要包含密钥和令牌。
过滤前先捕获未过滤日志。保留首次启动行、复位/掉电/看门狗消息，以及复现症状的转换过程。
将结论标注为构建、上传、硬件、系统或部署证据。按证明阶段报告结果。干净的串口流并不能证明引脚、电源或整个系统正确。
需要测试矩阵时配合 hardware-tdd，当下一次观察必须来自用户操作的开发板时配合 embedded-project-loop。

使用方法

基础串口监视

# 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"

进阶调试

# 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

脚本选项

--port：串口（例如 COM3、/dev/ttyACM0）
--baud：波特率（默认：9600）
--output：日志输出文件
--filter：用于过滤行的正则表达式
--format：数据格式（text、json、csv、binary）
--timestamp：为输出添加时间戳
--color：启用彩色输出
--detect-errors：高亮常见错误模式
--timeout：连接超时（秒）

常见 Arduino 调试场景

内存问题

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

传感器数据校验

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

时序分析

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

通信错误

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

与 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

故障排查

找不到端口

用 arduino-cli board list 检查可用端口
确认 Arduino 已连接且驱动已安装
尝试不同端口名（Windows 上 COM1-COM99，Linux 上 /dev/ttyACM*）

未接收到数据

验证波特率与 Arduino 草图一致（Serial.begin(9600)）
检查 USB 线缆连接
监视时复位 Arduino 板

权限错误（Linux/macOS）

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

证据与隐私

记录开发板、固件/镜像版本、工具链、波特率、端口、复位原因以及时间戳来源。仅当串口输出是在目标设备上捕获时，才将其标注为硬件或系统证据。保存日志或分享前，脱敏 Wi-Fi 密码、API 密钥、证书、令牌和个人数据。

依赖

Python 3.8+
uv 0.4+（脚本以内联方式声明 pyserial 和 colorama）
用 uv run --no-project scripts/monitor_serial.py --help 运行自包含辅助脚本。

示例

基础温度传感器监视

// 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 数据解析

// 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

共享输出契约

使用共享 Arduino 技能契约（../../docs/arduino-skill-contract.md）：声明假设、所需工具与版本、实现步骤、按证明阶段划分的测试/证据、已知限制以及恢复/安全说明。

技能介绍