embedded-debug-entry

name	embedded-debug-entry
description	Use when triaging embedded device, MCU, firmware, board bring-up, flashing, serial log, RTOS, bootloader, low-power, or peripheral debug requests

Embedded Debug Entry

Overview

Use this skill as the first stop for embedded debugging. The agent should classify the target, failure phase, access method, toolchain, and risk level, then route to the narrowest specialized skill instead of guessing from incomplete context.

When To Use

Use this skill when:

• The user reports an embedded device, MCU, board, firmware, RTOS, bootloader, or peripheral issue.
• The architecture or debugging path is unclear.
• The task might involve flashing, serial logs, SWD/JTAG, UART, ADB, bootloaders, low power, or hardware signals.

Do not use this skill when the user already named a more specific skill path, such as Cortex-M HardFault, 8051 timer, RISC-V trap, or embedded Linux SSH login.

First Questions

Ask only what is needed to route:

• Target type: MCU, embedded Linux device, mixed SoC, module, or unknown board.
• Architecture or chip family: Cortex-M, Cortex-R, RISC-V, 8051, Linux-capable ARM, or unknown.
• Failure phase: cannot connect, cannot flash, no boot, crash/fault, no logs, peripheral failure, RTOS issue, bootloader issue, low-power issue.
• Available access: SWD/JTAG, serial UART, SSH, ADB, Telnet, local console, logic analyzer, oscilloscope, or vendor tool.
• Toolchain and artifacts: ELF/HEX/MAP, firmware log, programmer output, schematic, boot log, or fault dump.

Routing Guide

Use the most specific path:

Symptom or target	Prefer
Cortex-M MCU, SWD/JTAG, HardFault, startup	cortex-m-debug
Cortex-R5/R4/R7, TCM, MPU, lockstep, safety core	cortex-r5-debug
8051/51/STC/Nuvoton/Silabs C8051	8051-mcu-debug
RISC-V MCU, OpenOCD/GDB, trap, CSR	riscv-mcu-debug
Embedded Linux login before debugging	embedded-linux-login-debug
OpenOCD/J-Link/ST-Link probe, SWD/JTAG attach	openocd-jlink-stlink-debug
Flash/download/verify/connect failure	mcu-flashing-debug
UART boot log, serial console, 乱码, no logs	embedded-serial-log-debug
Crash, exception, trap, fault, stack corruption	embedded-fault-debug
GPIO/UART/SPI/I2C/PWM/ADC bring-up	embedded-peripheral-bringup
Sensor driver, IMU, I2C/SPI sensor data	sensor-driver-integration
QSPI/OSPI flash, XIP, memory-mapped boot	qspi-xip-flash-debug
FreeRTOS kernel: tasks, heap, tick, ISR API	freertos-kernel-debug
Zephyr devicetree, Kconfig, west, drivers	zephyr-integration
RT-Thread BSP, FinSH, device framework, DFS	rt-thread-integration
General RTOS scheduling, stacks, priorities	rtos-debug
STM32 HAL/LL, CubeMX, clocks, DMA, NVIC	stm32-hal-ll-integration
ESP-IDF, sdkconfig, partitions, NVS, Wi-Fi	esp-idf-integration
Nordic nRF Connect SDK, BLE, DFU, Partition Mgr	nrf-connect-sdk-integration
BLE GATT services, characteristics, MTU, pairing	ble-gatt-integration
Bootloader, app jump, upgrade state	bootloader-debug
MCUboot image slots, signing, swap, rollback	mcuboot-integration
OTA package, transport, validation, activation	ota-update-integration
Sleep, wakeup, current consumption, lost debug	low-power-debug
Power, reset, clock, pins, board-level signals	hardware-interface-debug

Workflow

1. Classify before acting. Do not start with code edits, reflashing, or resets until the target and failure phase are known.

2. Route to one primary skill. If multiple skills apply, pick the one closest to the current blocker. Example: "cannot flash Cortex-M" starts with mcu-flashing-debug, not general Cortex-M logic.

3. Collect minimal evidence. Ask for the smallest artifact that proves the current state: programmer error, serial log, GDB register dump, schematic snippet, or tool output.

4. Preserve safety boundaries. Treat erase, option bytes, boot config, security bits, fuses, production data, and power changes as explicit-approval actions.

5. Summarize the route. Tell the user which path you selected and why before continuing with detailed debug instructions.

Verification

Before moving into a specialized workflow:

• State target class, architecture, failure phase, available access, and selected skill.
• State what evidence is already available and what is still missing.
• Confirm no destructive operation has been recommended without approval.

Common Failures

• Treating every embedded issue as a firmware code problem.
• Asking for every possible tool output before choosing a debug path.
• Starting with flash erase when the failure is actually serial wiring or reset.
• Debugging application logic before proving the target boots and the image matches.
• Mixing Linux device login workflows with MCU bare-metal workflows.

Example

User:

板子起来以后没日志，也不知道是不是程序没跑。

Agent:

1. Asks for chip family, access methods, firmware artifact, and whether serial pins are known.
2. Routes to embedded-serial-log-debug if the first blocker is "no logs".
3. If serial is healthy but no heartbeat exists, routes to the architecture-specific startup workflow.