Board debug
타겟 보드 디버깅 스킬. SSH 원격 테스트, 시리얼 로그 수집/분석, 디버그 리포트 생성. Triggers: 보드 디버깅, 보드 테스트, board debug, boot check, 부팅 확인From its SKILL.md
npx -y skills add solitasroh/rkit --skill board-debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.8 KB, as published. Nobody here has run it
0. 문서 구조 (본 SKILL의 세 층)
- 도메인 본문 (§1 ~ §N): 이 SKILL의 프로토콜. grandfathered SKILL — 잠금 어휘 사용 허용 (Cycle 3 변환). 본문 자체가 도메인 기술입니다.
- 방법론 본문 — 도메인 중립 (선택): 공통 방법론 절이 있다면
<!-- BEGIN: cycle3-body-neutral -->마커로 분리. - 도메인 예시 부록 (§A): SoT(
policies/locked-vocab.json)에서 자동 생성.
직접 부록을 편집하지 마세요 — node scripts/gen-locked-vocab.mjs로 재생성됩니다.
Board Debug
타겟 보드의 부팅 및 기능을 디버깅/검증하고 리포트를 생성한다.
전제 조건: 환경변수
.env 확인 (공통)
스킬 실행 전 프로젝트 루트의 .env 파일을 확인한다:
.env파일이 있으면 → 정상 진행 (값을 읽어서 사용).env파일이 없으면:- devkit plugin 디렉토리의
templates/env.template파일을 찾는다 env.template이 있으면 → 프로젝트 루트에.env.example과.env로 복사- 사용자에게 안내: "
.env파일이 생성되었습니다. 필요한 값을 채워주세요." env.template이 없으면 → "devkit plugin이 설치되지 않은 것 같습니다." 안내
- devkit plugin 디렉토리의
.env에서 이 스킬에 필요한 변수를 읽는다 (빈 값이면 사용자에게 질문)
.env에 타겟 보드 접속 정보를 설정한다:
### 타겟 보드 SSH
BOARD_SSH_HOST=192.168.1.100 # 보드 IP
BOARD_SSH_PORT=22
BOARD_SSH_USER=root
BOARD_SSH_PASSWORD= # 비어있으면 BOARD_SSH_KEY 사용
BOARD_SSH_KEY=~/.ssh/id_rsa # 기본 키 경로 (다른 키로 변경 가능)
### 시리얼 디버그 서비스 (serial-debug)
SERIAL_DEBUG_HOST=10.10.23.100 # serial-debug 서비스 호스트
SERIAL_DEBUG_API_PORT=8090 # REST API + Web UI 포트
SERIAL_DEBUG_TCP_PORT=9000 # TCP raw proxy 시작 포트
SSH 인증 우선순위
BOARD_SSH_PASSWORD가 설정되어 있으면 → 비밀번호 인증- 비어있으면 →
BOARD_SSH_KEY경로의 SSH 키 인증 (기본~/.ssh/id_rsa)
# 비밀번호 인증
sshpass -p "${BOARD_SSH_PASSWORD}" ssh -o StrictHostKeyChecking=no \
-p ${BOARD_SSH_PORT} ${BOARD_SSH_USER}@${BOARD_SSH_HOST} "uname -r"
# 키 인증 (비밀번호 미설정 시)
ssh -i ${BOARD_SSH_KEY} -o StrictHostKeyChecking=no \
-p ${BOARD_SSH_PORT} ${BOARD_SSH_USER}@${BOARD_SSH_HOST} "uname -r"
STM32MP OpenSTLinux 기본 이미지는 dropbear SSH + debug-tweaks로 root 비밀번호 없이 접속 가능. 이 경우 비밀번호/키 모두 불필요.
시리얼 디버그 서비스 (serial-debug)
별도 호스트에서 실행되는 serial-debug 서비스가 시리얼 포트를 관리한다. 이 스킬은 REST API로 로그를 가져오고, 필요시 명령을 전송한다.
- REST API / Web UI:
http://${SERIAL_DEBUG_HOST}:${SERIAL_DEBUG_API_PORT}/ - TCP raw proxy:
${SERIAL_DEBUG_HOST}:${SERIAL_DEBUG_TCP_PORT}(장치별 9000, 9001, ...)
REST API 사용법
SERIAL_API="http://${SERIAL_DEBUG_HOST}:${SERIAL_DEBUG_API_PORT}"
# 장치 목록 조회
curl -s ${SERIAL_API}/api/devices | python3 -m json.tool
# 특정 장치 로그 가져오기 (최근 200줄)
curl -s ${SERIAL_API}/api/devices/{name}/log?lines=200
# 명령 전송 + 응답 대기
curl -s -X POST ${SERIAL_API}/api/devices/{name}/send \
-H "Content-Type: application/json" \
-d '{"command": "uname -r\n", "wait_ms": 2000}'
# 로그 파일 목록
curl -s ${SERIAL_API}/api/devices/{name}/logs
# 로그 파일 다운로드
curl -s ${SERIAL_API}/api/logs/{filename} -o boot_log.txt
TCP raw 접속 (양방향 시리얼)
장치 목록 API에서 tcp_port를 확인하여 직접 접속 가능:
# raw 접속 (에코 제거 권장)
stty -echo; nc ${SERIAL_DEBUG_HOST} ${SERIAL_DEBUG_TCP_PORT}; stty echo
# socat
socat -,rawer tcp:${SERIAL_DEBUG_HOST}:${SERIAL_DEBUG_TCP_PORT}
Web UI
http://${SERIAL_DEBUG_HOST}:${SERIAL_DEBUG_API_PORT}/ 에서 장치별 탭으로 실시간 모니터링 가능.
접근 방식
| 방식 | 용도 | 사용 시점 |
|---|---|---|
| A. SSH 원격 테스트 | 기능 검증 | Linux 부팅 후, 네트워크 연결됨 |
| B. serial-debug API | 부팅 로그, U-Boot | 부팅 실패, U-Boot 디버깅, 전체 로그 |
| C. 로그 파일 분석 | 오프라인 분석 | 시리얼 로그 파일을 전달받은 경우 |
절차
실행 시 메뉴를 표시한다:
Board Debug:
1. SSH 원격 테스트 — 네트워크로 보드 접속하여 체크리스트 실행
2. 시리얼 로그 수집 — serial-debug API로 부팅 로그 가져오기
3. 부팅 로그 분석 — 로그 파일/API에서 에러 패턴 검출
4. 개별 테스트 — 항목 선택하여 SSH로 실행
5. 생산 QC — 최소 체크리스트 (SSH)
메뉴 1: SSH 원격 테스트 (추천)
보드가 네트워크에 연결되고 SSH 접근 가능한 상태에서 체크리스트를 자동 실행한다.
체크리스트
| # | 항목 | 명령 | 판정 기준 | 필수 |
|---|---|---|---|---|
| 1 | Kernel 버전 | uname -r | 예상 버전과 일치 | O |
| 2 | Boot 로그 에러 | dmesg | grep -i -E "error|fail|panic" | critical 에러 없음 | O |
| 3 | rootfs 마운트 | mount | grep "on / " | ext4, rw | O |
| 4 | 디스크 용량 | df -h / | 정상 크기 | O |
| 5 | eMMC/SD 파티션 | lsblk | 예상 파티션 구조 | O |
| 6 | 네트워크 인터페이스 | ip addr show | eth0/end0 존재 | O |
| 7 | IP 획득 | ip addr show | grep "inet " | IP 할당됨 | O |
| 8 | 드라이버 로드 | lsmod | 주요 모듈 로드 확인 | O |
| 9 | USB 장치 | lsusb | USB 컨트롤러 인식 | - |
| 10 | WiFi 스캔 | iw dev wlan0 scan | grep SSID | AP 목록 (WiFi 있는 경우) | - |
| 11 | BT 스캔 | hciconfig | BT 인터페이스 (BT 있는 경우) | - |
| 12 | 오디오 장치 | aplay -l | 사운드카드 인식 | - |
| 13 | 디스플레이 | cat /sys/class/drm/card*/status | connected | - |
| 14 | Qt 라이브러리 | ls /usr/share/qt6/ | Qt 존재 | - |
| 15 | systemd 서비스 | systemctl --failed | failed 서비스 없음 | O |
| 16 | 시간 | timedatectl | RTC 또는 NTP 동기 | - |
| 17 | 온도 센서 | cat /sys/class/thermal/thermal_zone*/temp | 정상 범위 | - |
| 18 | CPU 정보 | cat /proc/cpuinfo | 예상 코어 수/모델 | O |
실행 방법
# SSH 접속 (인증 방식 자동 선택)
if [ -n "${BOARD_SSH_PASSWORD}" ]; then
SSH_CMD="sshpass -p ${BOARD_SSH_PASSWORD} ssh -o StrictHostKeyChecking=no -p ${BOARD_SSH_PORT} ${BOARD_SSH_USER}@${BOARD_SSH_HOST}"
else
SSH_CMD="ssh -i ${BOARD_SSH_KEY} -o StrictHostKeyChecking=no -p ${BOARD_SSH_PORT} ${BOARD_SSH_USER}@${BOARD_SSH_HOST}"
fi
# 전체 체크리스트 일괄 실행
${SSH_CMD} bash << 'TESTEOF'
echo "=== Kernel ==="
uname -r
echo "=== Boot Errors ==="
dmesg | grep -i -c -E "error|fail|panic" || echo "0"
echo "=== Rootfs ==="
mount | grep "on / "
echo "=== Disk ==="
df -h /
echo "=== Partitions ==="
lsblk
echo "=== Network ==="
ip addr show
echo "=== Modules ==="
lsmod | head -20
echo "=== systemd ==="
systemctl --failed
echo "=== CPU ==="
cat /proc/cpuinfo | grep -E "processor|model|Hardware"
echo "=== Temperature ==="
cat /sys/class/thermal/thermal_zone*/temp 2>/dev/null || echo "N/A"
TESTEOF
판정
- PASS: 필수(O) 항목 모두 통과
- WARN: 비필수 항목 실패 (WiFi, BT, Audio 등 — 보드 구성에 따라)
- FAIL: 필수 항목 1개 이상 실패
메뉴 3: 부팅 로그 분석
시리얼 로그(API에서 수집, 파일 전달, 또는 붙여넣기)를 분석한다.
tools/log_analyze.py를 사용하거나, AI가 직접 Read 도구로 읽고 분석한다.
로그 입력 방법
| 방법 | 명령 |
|---|---|
| 파일 분석 | python tools/log_analyze.py boot_log.txt |
| stdin 리다이렉트 | python tools/log_analyze.py < boot_log.txt |
| 파이프 | cat boot_log.txt | python tools/log_analyze.py |
| 붙여넣기 (대화형) | python tools/log_analyze.py --paste |
| 마크다운 출력 (리포트용) | python tools/log_analyze.py boot_log.txt --markdown |
| API에서 직접 | curl -s ${SERIAL_API}/api/devices/{name}/log?lines=500 | python tools/log_analyze.py |
분석 패턴
| 패턴 | 심각도 | 설명 |
|---|---|---|
Kernel panic | CRITICAL | 커널 패닉 |
Unable to mount root | CRITICAL | rootfs 마운트 실패 |
Oops, BUG: | CRITICAL | 커널 oops/BUG |
probe failed | HIGH | 드라이버 프로빙 실패 |
Error | HIGH | 드라이버/서브시스템 에러 |
failed | MEDIUM | 서비스/작업 실패 |
timeout | MEDIUM | 하드웨어 응답 없음 |
WARNING | LOW | 커널 경고 |
분석 결과를 정리하여 리포트에 포함한다.
부팅 로그 분석은 시리얼 연결 없이도 가능하므로, 로그 파일, 붙여넣기, 파이프 등 어떤 방식으로든 분석할 수 있다.
메뉴 5: 생산 QC
생산 라인에서 최소한으로 확인할 항목만 SSH로 실행한다:
| # | 항목 | 명령 | 시간 |
|---|---|---|---|
| 1 | SSH 접속 | ssh root@{IP} "echo ok" | ~1초 |
| 2 | Kernel 버전 | uname -r | 즉시 |
| 3 | eMMC 파티션 | lsblk | grep mmcblk | 즉시 |
| 4 | 네트워크 | ip link show | 즉시 |
| 5 | systemd 상태 | systemctl is-system-running | 즉시 |
총 QC 시간: ~5초 (보드 부팅 완료 후)