arduino-serial-monitor

Arduino 串口监视器

本技能提供用于读取和分析 Arduino 开发板串口监视器数据的高级工具，在基础 Arduino IDE 串口监视器之外增强调试体验。

功能特性

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

结构化调试工作流

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

推荐的 C++ 事件格式

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

使用适合开发板内存预算的固定、有界格式。不要 记录 Wi-Fi 密码、API 密钥、证书、令牌或私人数据。

使用方法

基础串口监视

# 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 技能约定： 说明假设、所需工具和版本、实现步骤、 按证明阶段划分的测试/证据、已知限制以及恢复/安全注意事项。