arduino-serial-monitor

Arduino Serial Monitor

对于桌面可视化／工作台控制台，请阅读 桌面控制台指南。无线传输和跟踪语义属于 wireless-telemetry；请勿在此重复其驱动程序或测量工作流。原生 ESP-IDF 日志可用于串口诊断，并不意味着使用了 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 技能契约： 说明假设、所需工具与版本、实现步骤、 按证明阶段划分的测试/证据、已知限制，以及恢复/安全注意事项。