[언제 호출] 어느 포트가 어느 보드인지 확인할 때, 모니터링 대상을 점검할 때.

[무엇을 반환] 현재 PC의 시리얼 포트 목록. 각 포트의 device/description/vid/pid/ manufacturer/serial_number 에 더해, 이 서버가 모니터링 중이면 monitored=true 와 별칭 name 이 붙는다. monitored_ports 는 현재 모니터링 목록(별칭 표기). VID/PID·description 으로 칩(CH343, CP210x 등)을 추론하라.

[루프 단계] 사전 점검 — 보통 한 번만.

[언제 호출] 로그가 안 들어올 때 '어느 보드가 연결돼 있는지'부터 확인할 때. 포트 점유/미연결/미인식 원인을 구분한다.

[무엇을 반환] port 미지정 시 모니터링 중인 전 포트의 상태 배열(ports). port(별칭 "SSM" 또는 포트명 "COM4") 지정 시 그 포트의 단일 상태. connected 가 false 이고 last_error 에 점유/권한 에러가 있으면 사람에게 같은 포트를 쓰는 다른 프로그램(테라텀 등) 종료를 요청하라.

사람이 로그를 직접 눈으로 보고 싶어 하면 viewer_url 링크를 안내하라(웹 뷰어). [루프 단계] 문제 진단.

[언제 호출] 블랙박스 루프의 '결과 확인' 단계 — 사람이 장비를 동작시킨 뒤 쌓인 로그를 확인할 때. 가장 자주 쓰는 도구.

[port 규약] 보드가 여러 개면 port 를 지정하라(별칭 "SSM" 또는 "COM4", 대소문자 무관). 미지정: 포트 1개면 그 포트, 복수면 에러와 함께 ports 목록을 돌려준다 — 목록에서 골라 즉시 재호출하면 된다.

[무엇을 반환] 최근 N개 라인(시간 오름차순). 근접 중복은 룩백으로 접혀 '(N회 반복, HH:MM:SS~HH:MM:SS)' 표기 — 접힘은 요약이라 반복 줄들의 정밀한 교차 순서는 뭉개진다. 정밀 순서가 필요하면 SERIAL_DEDUP=1 또는 0 으로 낮춰 재시험하라(tee 파일엔 원본 보존).

[팁] 결과가 많으면 query_serial_logs 로 좁혀라. 비어 있으면 get_serial_status 로 연결을 확인하고, 그래도 비면 사람에게 장비 동작/리셋을 요청하라.

[루프 단계] 결과 확인.

[언제 호출] 특정 키워드/에러/마커를 버퍼에서 찾을 때. 예: 부팅 완료 문구, 'ERROR', 특정 상태 출력의 등장 여부.

[port 규약] get_recent_logs 와 동일 — 복수 포트면 지정, 미지정 에러 시 ports 목록에서 골라 재호출.

[무엇을 반환] 정규식 pattern 매칭 라인들(최신 우선 max_results개, 반환은 시간 오름차순, 접힌 묶음 표기 포함). 매칭 0이면 그 문구가 아직 안 나온 것 — 사람에게 해당 동작을 요청하거나 더 기다린 뒤 재조회하라.

[루프 단계] 결과 확인(표적 검색).

[언제 호출] 버퍼가 얼마나 찼는지, 최근/최오래 항목이 무엇인지 빠르게 볼 때. clear_log_buffer 직후 새 로그 유입을 폴링할 때 특히 유용.

[port 규약] get_recent_logs 와 동일.

[무엇을 반환] entries/capacity, oldest/newest, 누적 total_received/total_stored, dedup(룩백 윈도 — 0이면 끔).

[루프 단계] 진행 점검(폴링).

[언제 호출] 블랙박스 시험의 '시작' 단계 — 새 시험을 깨끗한 상태에서 관측하려고 직전 로그를 비울 때. 표준 절차: 비우고 → 사람에게 장비 동작/리셋 요청 → 잠시 후 get_recent_logs 로 회수.

[port 규약] 다른 도구와 달리 미지정 = 전체 포트 비우기(시험 시작 시 모든 보드를 함께 리셋 관측하는 게 보통이므로). 특정 보드만 비우려면 port 지정.

[무엇을 반환] cleared(총 비운 항목 수)와 ports(포트별 내역).

[루프 단계] 시험 시작.