agentsclimarketplace

Board debug

Skill solitasroh/rkit/skills/board-debug

타겟 보드 디버깅 스킬. SSH 원격 테스트, 시리얼 로그 수집/분석, 디버그 리포트 생성. Triggers: 보드 디버깅, 보드 테스트, board debug, boot check, 부팅 확인From its SKILL.md

Install
npx -y skills add solitasroh/rkit --skill board-debug

Assembled 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. 도메인 본문 (§1 ~ §N): 이 SKILL의 프로토콜. grandfathered SKILL — 잠금 어휘 사용 허용 (Cycle 3 변환). 본문 자체가 도메인 기술입니다.
  2. 방법론 본문 — 도메인 중립 (선택): 공통 방법론 절이 있다면 <!-- BEGIN: cycle3-body-neutral --> 마커로 분리.
  3. 도메인 예시 부록 (§A): SoT(policies/locked-vocab.json)에서 자동 생성.

직접 부록을 편집하지 마세요 — node scripts/gen-locked-vocab.mjs로 재생성됩니다.


Board Debug

타겟 보드의 부팅 및 기능을 디버깅/검증하고 리포트를 생성한다.

전제 조건: 환경변수

.env 확인 (공통)

스킬 실행 전 프로젝트 루트의 .env 파일을 확인한다:

  1. .env 파일이 있으면 → 정상 진행 (값을 읽어서 사용)
  2. .env 파일이 없으면:
    • devkit plugin 디렉토리의 templates/env.template 파일을 찾는다
    • env.template이 있으면 → 프로젝트 루트에 .env.example과 .env로 복사
    • 사용자에게 안내: ".env 파일이 생성되었습니다. 필요한 값을 채워주세요."
    • env.template이 없으면 → "devkit plugin이 설치되지 않은 것 같습니다." 안내
  3. .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 인증 우선순위

  1. BOARD_SSH_PASSWORD가 설정되어 있으면 → 비밀번호 인증
  2. 비어있으면 → 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 접근 가능한 상태에서 체크리스트를 자동 실행한다.

체크리스트

#항목명령판정 기준필수
1Kernel 버전uname -r예상 버전과 일치O
2Boot 로그 에러dmesg | grep -i -E "error|fail|panic"critical 에러 없음O
3rootfs 마운트mount | grep "on / "ext4, rwO
4디스크 용량df -h /정상 크기O
5eMMC/SD 파티션lsblk예상 파티션 구조O
6네트워크 인터페이스ip addr showeth0/end0 존재O
7IP 획득ip addr show | grep "inet "IP 할당됨O
8드라이버 로드lsmod주요 모듈 로드 확인O
9USB 장치lsusbUSB 컨트롤러 인식-
10WiFi 스캔iw dev wlan0 scan | grep SSIDAP 목록 (WiFi 있는 경우)-
11BT 스캔hciconfigBT 인터페이스 (BT 있는 경우)-
12오디오 장치aplay -l사운드카드 인식-
13디스플레이cat /sys/class/drm/card*/statusconnected-
14Qt 라이브러리ls /usr/share/qt6/Qt 존재-
15systemd 서비스systemctl --failedfailed 서비스 없음O
16시간timedatectlRTC 또는 NTP 동기-
17온도 센서cat /sys/class/thermal/thermal_zone*/temp정상 범위-
18CPU 정보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 panicCRITICAL커널 패닉
Unable to mount rootCRITICALrootfs 마운트 실패
Oops, BUG:CRITICAL커널 oops/BUG
probe failedHIGH드라이버 프로빙 실패
ErrorHIGH드라이버/서브시스템 에러
failedMEDIUM서비스/작업 실패
timeoutMEDIUM하드웨어 응답 없음
WARNINGLOW커널 경고

분석 결과를 정리하여 리포트에 포함한다.

부팅 로그 분석은 시리얼 연결 없이도 가능하므로, 로그 파일, 붙여넣기, 파이프 등 어떤 방식으로든 분석할 수 있다.

메뉴 5: 생산 QC

생산 라인에서 최소한으로 확인할 항목만 SSH로 실행한다:

#항목명령시간
1SSH 접속ssh root@{IP} "echo ok"~1초
2Kernel 버전uname -r즉시
3eMMC 파티션lsblk | grep mmcblk즉시
4네트워크ip link show즉시
5systemd 상태systemctl is-system-running즉시

총 QC 시간: ~5초 (보드 부팅 완료 후)

Keep looking

Skills are one crate of 609,856. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.