Serial Port Monitoring

Applicable Scenarios

• Users need to view the startup logs, assertion outputs, or interactive UART outputs of the target board.
• Flashing or resetting has just been completed, and the next step is to observe runtime behavior.
• Need to avoid missing early startup logs, or want to reset the target board immediately after monitoring starts.
• There is a clear UART port or baud rate defined in the workspace or Project Profile.

Required Inputs

• A serial port, or a Project Profile sufficient for serial port detection.
• Optional baud rate, monitoring mode, key strings, and log save path.
• For automatic reset, an OpenOCD configuration is also required, which can come from explicit input or an existing project profile.

Automatic Detection

• Serial port priority: explicit user input > Project Profile > script automatic detection result; otherwise, the process will block.
• Baud rate priority: explicit user input > Project Profile > workspace documents or code constants; finally falls back to

  115200

  .
• During automatic detection, priority is given to common serial ports or debugger virtual serial ports such as CH340, CP210x, CMSIS-DAP, ST-Link.
• If there are multiple equally reasonable serial port candidates, list the candidates first, then block as needed instead of making silent guesses.

Execution Steps

1. First read references/usage.md to confirm whether this operation is for listing ports, capturing logs, waiting for specific strings, continuous monitoring, or "monitor first then reset".
2. Run the built-in script scripts/serial_monitor.py. Use

   --list

   to list serial ports, and

   --auto

   to automatically select a port.
3. Use

   --duration

   for regular log capture,

   --wait

   to wait for specific output, and

   --monitor --timestamp

   for continuous monitoring.
4. Use

   --wait-reset

   if you are worried about missing early startup logs; enable

   --auto-reset

   only when the OpenOCD configuration is clearly defined.
5. Read the analysis results output by the script instead of just relaying the original serial port text; focus on errors, warnings, startup markers, and key peripheral keywords.
6. Write the selected serial port, baud rate, command, and log conclusion back to the Project Profile, and pass them to downstream skills if needed.

Failure Diversion

• Return

  environment-missing

  when dependencies such as

  pyserial

  or

  openocd

  are missing.
• Return

  connection-failure

  when the selected serial port cannot be opened or disappears during monitoring.
• Return

  permission-problem

  when the host does not have permission to access the serial port device.
• Return

  ambiguous-context

  when there are multiple reasonable serial port candidates, or there are conflicting baud rates implied in the workspace.
• Return

  target-response-abnormal

  when the serial port is accessible but the logs clearly show startup failure, repeated reset, assertion, or Fault.

Platform Notes

• The serial port naming rules for Linux, macOS, and Windows reuse platform-compatibility.md.
• The built-in script uses

  pyserial

  , so the serial port capture path itself is cross-platform.
• In Windows output, retain the exact

  COM

  port name and the command line quote format required by the shell.

Output Conventions

• Output the selected serial port, baud rate, actual execution command, and a concise summary of the log analysis results.
• Update the Project Profile with

  serial_port

  and

  baud_rate

  once the serial port and baud rate are confirmed.
• If

  --auto-reset

  is used, record the source of the OpenOCD configuration and the reset command at the same time.
• When logs indicate program crash, freeze, or abnormal startup, recommend

  debug-gdb-openocd

  .

Handover Relationship

• When logs indicate the need for breakpoints, registers, or backtracking, pass the results to

  debug-gdb-openocd

  .