raman/docs/serial_tx_startup_race.md

Serial TX Startup Race 정리

1) FD(File Descriptor)란?

• FD는 리눅스/안드로이드에서 열린 리소스(파일/소켓/시리얼 포트)를 가리키는 정수 핸들입니다.
• 이 프로젝트에서 시리얼 포트 상태는 다음처럼 판단합니다.
  • FD == -1: 포트 미오픈(유효하지 않음)
  • FD >= 0: 포트 오픈 완료(유효)
• 따라서 FD == -1 상태에서 write()를 호출하면 실제 시리얼 전송이 되지 않습니다.

2) 문제 원인

• txPacketOnce()가 앱 시작 직후 실행됩니다.
• 시리얼 포트 open()은 rxPacketLoop() 내부에서 코루틴으로 비동기 시작됩니다.
• 기존 순서에서 txPacketOnce()가 먼저 호출되면, 포트 오픈 완료 전(FD == -1)에 TX가 시도되어 초기 패킷 전송이 누락될 수 있습니다.

3) 적용한 수정

A. 초기 호출 순서 조정

• 파일: app/src/main/java/com/laseroptek/raman/ui/MainActivity.kt
• 변경:
  • 이전: txPacketOnce() -> rxPacketLoop() -> txPacketLoop()
  • 이후: rxPacketLoop() -> txPacketOnce() -> txPacketLoop()
• 목적: RX 루프가 먼저 포트 오픈을 시작하도록 해서 초기 TX 레이스 확률을 줄임

B. txPacketOnce()에 포트 준비 대기 추가

• 파일: app/src/main/java/com/laseroptek/raman/ui/screens/main/MainViewModel.kt
• 변경:
  • txPacketOnce()를 IO 코루틴에서 실행
  • waitUntilSerialReady()(최대 2초, 20ms 폴링)로 FD != -1 확인 후 TX 진행
  • 시간 내 준비 실패 시 로그를 남기고 전송 중단
• 목적: 순서만으로 보장되지 않는 코루틴 스케줄링 레이스를 방어

4) 왜 TX에서 직접 open()하지 않았는가?

• 현재 구조에서 open()의 데이터 콜백은 rxPacketLoop()의 callbackFlow와 연결됩니다.
• TX 경로에서 별도 open()을 하면 중복 오픈/콜백 소유권/FD 교체 타이밍 이슈가 생길 수 있습니다.
• 안정적인 패턴은:
  • 포트 오픈 책임: RX(단일 지점)
  • 포트 사용(TX): ready 확인 후 write

5) 확인 포인트

• 앱 시작 직후 로그에서 FD가 유효해진 뒤 txPacketOnce()의 TX 로그가 출력되는지 확인
• 장비 측 시리얼 모니터에서 초기 패킷(Version/Q-Switch/GuideBeam/DCD/SprayDCD) 수신 여부 확인