docs: v6 전체 업데이트 (1.0.0-design, VBTFW0116 짝, 2026-05-26 기준)

a1042b8(v5) 이후 13개 커밋을 반영해 세 문서 일괄 갱신. USER_GUIDE.md: - 헤더: VBTAND0101 → 1.0.0-design (versionCode 24), 권장 펌웨어 VBTFW0116 - PIN DEMO 자동통과 안내 (배포 전 정리 필요) - Personalization 평행 2-카드 (Maximum Bladder Capacity + Catheter Threshold) - Sensor Alignment 리디자인 (38sp 큰 타이틀, pubic bone 빨강, 3-stop gradient, Canvas 화살표/아치 제거) - Measurement Screen top bar에 Home 아이콘 + Voiding/ 텍스트 + 48sp Recorded Dialog - Auto Scan 600ms로 단축 + 측정 사이클 ~330ms 실측 안내 - 설정 패널 폰/태블릿 자동 폰트 분기 (fontScale 표 추가) - Dev Mode 추가 기능 (DeviceScan 측정 직진입 버튼, Status 더미 주입) - Navigation에 placementFromMonitoring 라우팅 분기 설명 + startFromHome fix VesiScan_Android_Pipeline_Summary.md: - v6 주요 변경 요약 (헤더에 한눈 보기) - §5.1 BLE 통신: Connection Parameter 협상 (MTU 247, CONN_PRIORITY HIGH), maa throttle state-based gate, 측정 사이클 실측 표 - 측정 흐름: Auto/Single Scan 600ms 동기화 + Voiding 시 자동 stop - 연속 스캔 동작: Placement loop 1000 → 600ms + v6 화면 디자인 변경 박스 - §14 BLE 명령어 포맷: VBTFW0116 신규 사항 (pending slot 1→8, 안드로이드 짝꿍 변경) - §22 향후 과제: v6 완료 항목 12개 추가 docs/ALGORITHM_COMPARISON.md: - Placement loop 1s → 600ms, canSendMaa 게이트 단계 명시 - v6 BLE 사이클 실측 (330ms 평균) - Measurement Modes: 800 → 600ms, Voiding 자동 stop - 신규 섹션: BLE maa Throttle — State-Based Gate (배경/구현/효과/logcat 키워드) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 10:26:00 +09:00
parent 31e9b8acbb
commit 4252464ef6
3 changed files with 296 additions and 32 deletions
@@ -2,7 +2,20 @@

 ## 작성일: 2026-04-23
 ## 작성자: dwjang
-## 마지막 업데이트: 2026-05-11 (v5) — VBTAND0101
+## 마지막 업데이트: 2026-05-26 (v6) — 1.0.0-design (versionCode 24)
+## 권장 펌웨어: **VBTFW0116** (pending slot 1→8 확장으로 ADC drop 안정)
+
+### v6 주요 변경 요약 (2026-05-12 ~ 2026-05-26)
+
+- **BLE throttle 상태 기반 게이트화** — 시간 단독(800ms)에서 `isMultiChannel && !isComplete` + 시간(600ms) 복합 게이트로 전환. 잔여 reb 폐기로 인한 CH0/CH1만 도착 + BV_FAIL/BV_SKIP 증상 해소
+- **CONNECTION_PRIORITY_HIGH 요청 추가** — CCCD write 완료 시점에 `gatt.requestConnectionPriority(HIGH)` 호출. peripheral이 수락 시 interval ~15ms로 단축
+- **MTU 247 협상 확정** — VBT26050202 + VBTFW0116 조합에서 247 정상 협상 (logcat 검증)
+- **측정 사이클 시간 1.2s → 0.33s** (4배 향상). Placement loop 1000ms → 600ms, Auto loop 1500ms → 600ms
+- **PinView DEMO 우회**, **DeviceScanView Dev 측정모드 진입 버튼**, **AppState placementFromMonitoring 라우팅 분기** 추가
+- **PiezoPersonalizationView 평행 2-카드 리디자인** (Maximum Bladder Capacity + Catheter Threshold, StepperButton, roundToInt fix)
+- **PlacementGuideView Sensor Alignment 리디자인** (3-stop gradient, 38sp 큰 타이틀, "pubic bone" 빨강 강조, Canvas 화살표/아치 제거, chestY 0.09)
+- **PiezoMonitoringView 누적 업데이트** (Voiding/ 텍스트, 48sp Recorded Dialog, useScrollLayout, Volume 72sp ExtraBold, Bladdy 0.483, Home 아이콘, 설정 패널 폰/태블릿 자동 분기)
+- **HomeView Bladdy 3× 확대** (220 → 660dp + BoxWithConstraints 90% 캡)

 ---

@@ -122,6 +135,68 @@ reb:(4바이트) + repeat_count(2바이트) + ADC데이터(200바이트) + CRC(2
 └ "reb:" 문자  └ 항상 100     └ 100개 × 2바이트(16-bit)  └ 체크섬
 ```

+### Connection Parameter 협상 (v6 신규)
+
+**MTU 247**: 연결 직후 `gatt.requestMtu(247)` 호출. 208B `reb:` 패킷을 단일 노티로 전송하여
+단편화 drop 위험 제거. 실측 VBT26050202 + VBTFW0116에서 247 정상 협상 확인.
+
+**CONNECTION_PRIORITY_HIGH**: CCCD write 성공 직후(서비스 ready 시점) 호출:
+```kotlin
+gatt.requestConnectionPriority(BluetoothGatt.CONNECTION_PRIORITY_HIGH)
+debugLogger.info("CONN_PRIORITY HIGH requested (ok=$priorityOk)")
+```
+peripheral이 connection parameter update를 수락하면 interval ~15ms로 협상되어
+Central Link Layer ACK 속도가 향상됨 → 펌웨어 SoftDevice TX queue 포화 빈도 감소.
+수락 여부는 안드로이드 API로 직접 확인 불가(HCI 레벨 차단) — 응답 시간 측정으로 간접 확인.
+
+### maa Throttle (v6 상태 기반 게이트로 강화)
+
+이전: 시간 단독 `now - lastMaaSentMs < 800` 차단 → 펌웨어 응답이 1.2s 걸릴 때
+`startMultiChannel(6)`이 응답 도중 호출되어 잔여 reb 패킷이 폐기되는 race 발생.
+
+신규: [BleManager.kt:464-481](app/src/main/java/com/example/medilightv2android/ble/BleManager.kt#L464-L481) `canSendMaa()`
+```kotlin
+private fun canSendMaa(caller: String): Boolean {
+    val now = System.currentTimeMillis()
+    val collectorBusy = piezoCollector.isMultiChannel && !piezoCollector.isComplete
+    val sinceLast = now - lastMaaSentMs
+    if (collectorBusy) {
+        if (sinceLast < 3000) {
+            Log.w("BleManager", "maa BUSY [$caller] — prev response in progress")
+            return false                              // (A) 상태 차단
+        }
+        Log.w("BleManager", "maa FORCE [$caller] — prev incomplete after ${sinceLast}ms")
+    }
+    if (sinceLast < 600) {
+        Log.w("BleManager", "maa THROTTLED [$caller] — ${sinceLast}ms since last")
+        return false                                  // (B) 시간 차단
+    }
+    return true
+}
+```
+
+| 게이트 | 차단 조건 | 풀림 조건 |
+|---|---|---|
+| (A) State | `isMultiChannel && !isComplete` (raa 미도착) | raa 도착 OR 3초 경과 (FORCE) |
+| (B) Time | 마지막 송신 후 600ms 미만 | 600ms 경과 |
+
+두 게이트 모두 통과해야 maa 송신. State gate가 안전망, time gate가 펌웨어 burst 방어.
+
+### 측정 사이클 실측 (VBTFW0116 + MTU 247 + CONN_PRIORITY HIGH)
+
+logcat 측정 (2026-05-26):
+
+| 사이클 | TX maa | RX raa | 소요 |
+|---|---|---|---|
+| Placement #1 | 57.333 | 57.652 | **319ms** |
+| Monitor #1 | 00.952 | 01.233 | **281ms** |
+| Monitor #2 | 02.851 | 03.191 | **340ms** |
+| Monitor #3 | 04.414 | 04.719 | **305ms** |
+| Monitor #4 | 05.982 | 06.292 | **310ms** |
+| Monitor #5 | 07.549 | 07.972 | **423ms** |
+
+**평균 ~330ms**. 이전 ~1.2~1.4s 대비 4배 향상. 모든 사이클에서 6/6 채널 도착, 유실 0건.
+
 ### Big Endian 자동 감지

 ```
@@ -480,7 +555,7 @@ Start Scanning 버튼 활성화 (초록색)
 | 위치 이탈 | "Position lost. Restart above pubic bone." |
 | 센서 미부착 | "Sensor detached. Restart above pubic bone." |

-## 연속 스캔 동작
+## 연속 스캔 동작 (2026-05-26 업데이트)

 ```
 "Start Alignment" 버튼 탭 (waitingForStart → false)
@@ -489,7 +564,7 @@ Start Scanning 버튼 활성화 (초록색)
    ↓
 즉시 첫 스캔 (maa 6채널)
    ↓ 결과: CV, 방향, Score 표시 (28sp 대형 힌트)
-1초 대기
+600ms 대기 (이전 1000ms → 600ms 단축, BleManager throttle과 동기화)
    ↓
 자동 재스캔 (scanCount 증가 → CV threshold 완화)
    ↓
@@ -498,6 +573,15 @@ Start Scanning 버튼 활성화 (초록색)
 is_pass = true → Lock → 7초 hold → "Start Scanning" 버튼 활성화
 ```

+### v6 화면 디자인 변경
+- 큰 "Sensor Alignment" 38sp ExtraBold 검정 (Maximum Bladder Capacity 카드와 톤 통일)
+- Hint 텍스트 "pubic bone" 인라인 빨강 ExtraBold (AnnotatedString + SpanStyle)
+- 3-stop vertical gradient 배경 (MlTeal 14% / 흰 / MlPrimary 10%) — GREEN 진입 시 단색 톤
+- Canvas 방향 화살표 4종 제거 (hint 텍스트만으로 안내)
+- 치골 아치 라인 + halo + endpoint 모두 제거
+- 토르소 chestY 0.06 → 0.09 (실루엣 위로 16% shift)
+- Body 상단 Spacer 8dp
+
 ---

 # 7. "Spot" 버튼 측정 흐름
@@ -534,20 +618,22 @@ Spot 버튼 탭
 화면에 "305 ml" 표시! (도넛차트 + 레벨 업데이트)
 ```

-## Auto Scan 모드 (2026-05-11 업데이트)
+## Auto Scan 모드 (2026-05-26 업데이트)

 "Auto Scan" 버튼으로 자동 반복 측정:
- 최소 800ms 간격 자동 측정 (BLE maa throttle 보장)
+- **최소 600ms 간격** 자동 측정 (BLE maa state-based throttle 보장)
+- LaunchedEffect loop delay: 1500ms → **600ms** (FW VBTFW0116 + MTU 247 + CONN_PRIORITY HIGH 적용 후 응답 ~330ms이므로 일관 단축)
 - 첫 5회: "—" 표시 (데이터 수집 중)
 - 5회 이상: **sliding window trimmed mean** (10개 윈도우, 최대/최소 각 1개 제외 → 8개 평균)
 - "Stop Scan" 버튼으로 종료
+- **Voiding/Catheterization 버튼 클릭 시 Auto 자동 stop + 측정 상태 정규화** (displayMaxVolumeMl/window/timer 모두 0) — v6 신규
 - Auto fail: 2ch+ missing 5회 연속 → "Position lost. Restart from alignment" 다이얼로그

 ## Single Scan 모드 (2026-05-11 업데이트)

 "Single Scan" 버튼 1탭 → **5회 측정 → trimmed mean**:
 - 최대 8회까지 재시도 (유효값 5개 수집 목표, 최소 3개)
- 측정 간격: maa 800ms throttle이 간격 보장
+- 측정 간격: maa 600ms throttle이 간격 보장 (v6에서 800 → 600 단축)
 - 중간 값 화면 미표시 (isSpotInProgress 플래그)
 - 1초 쿨다운 후 재사용 가능

@@ -626,6 +712,8 @@ medilightv2android/
 │   └── (onboarding, registration, pin, ...)
 │
 └── AppState.kt                    ← 전역 상태 관리 + 화면 라우팅
+                                     (v6: placementFromMonitoring 플래그 +
+                                      enterPlacementFromMonitoring() / backFromPlacementGuide())
 ```

 ## 포팅 원본 대조
@@ -875,7 +963,26 @@ RX: "raa all-ch complete [8B]"

 # 14. BLE 명령어 포맷 (펌웨어 특이사항)

-이 기기(VBTFW0111)는 파라미터 없는 명령어에도 **`cmd? `(물음표+공백)** 포맷이 필요합니다.
+이 기기(VBTFW0111 ~ **VBTFW0116**)는 파라미터 없는 명령어에도 **`cmd? `(물음표+공백)** 포맷이 필요합니다.
+
+### VBTFW0116 신규 사항 (펌웨어 측 패치)
+
+```
+원인:
+- Central(앱)의 Link Layer ACK / connection event 처리 속도보다 Peripheral이
+  notify enqueue를 더 빨리 시도해서 SoftDevice TX queue 포화
+- 기존 FW: pending slot 1개만 보관 (이미 pending 있으면 다음 패킷 drop)
+- PC 환경에선 Central 처리 빨라 문제 없음 → 실제 앱 환경에선 OS/connection 영향으로 포화 잦음
+
+개선:
+- pending slot 1 → 8개 확장 → TX queue 포화 시 보관/재전송 → 중간 채널 데이터 유실 감소
+- 결과: ADC drop 현상 재현되지 않음 (장시간 반복 테스트 진행 중)
+
+안드로이드 측 짝꿍 변경:
+- MTU 247 협상 (208B reb 단일 노티)
+- CONNECTION_PRIORITY_HIGH 요청 (interval 단축 시도)
+- maa throttle을 state-based gate로 강화 (잔여 reb 폐기 방지)
+```

 ```kotlin
 // ❌ 안 됨 (rxs: cmd_not_supported 응답)
@@ -1313,6 +1420,18 @@ ADC 파싱 시 Big/Little Endian을 자동 감지:
 | 앱 아이콘 | ✅ 완료 | 방광이 캐릭터 PNG (5 density) |
 | Placement 화살표 수정 | ✅ 완료 | 디바운스/보호 중에도 화살표 항상 표시 |
 | GREEN 안정성 | ✅ 완료 | 7초 hold + 3회 연속 실패 exit + phase 보호 |
+| MTU 247 + CONN_PRIORITY HIGH | ✅ 완료 (v6) | VBT26050202 + VBTFW0116 정상 협상 |
+| maa throttle state-based gate | ✅ 완료 (v6) | isComplete + 600ms + 3s FORCE |
+| 측정 사이클 1.2s → 0.33s | ✅ 완료 (v6) | 4배 향상, 6/6 유실 0 |
+| Placement loop 600ms 단축 | ✅ 완료 (v6) | 1000 → 600ms |
+| Auto loop 600ms 단축 | ✅ 완료 (v6) | 1500 → 600ms |
+| placementFromMonitoring 라우팅 분기 | ✅ 완료 (v6) | enterPlacementFromMonitoring/backFromPlacementGuide |
+| PiezoPersonalization 평행 2-카드 | ✅ 완료 (v6) | Maximum Bladder Capacity + Catheter Threshold |
+| PlacementGuide Sensor Alignment 리디자인 | ✅ 완료 (v6) | 3-stop gradient + 38sp 큰 타이틀 + pubic bone 빨강 |
+| PiezoMonitoring Home 아이콘 / Voiding/ / Recorded Dialog | ✅ 완료 (v6) | |
+| HomeView Bladdy 3× (660dp 캡) | ✅ 완료 (v6) | BoxWithConstraints 90% cap |
+| 설정 패널 폰/태블릿 자동 분기 | ✅ 완료 (v6) | fontScale (360dp→1.0, 600dp+→1.8) |
+| PinView DEMO 자동통과 | ✅ DEMO 빌드 한정 | 배포 전 if(false) 블록 제거 |
 | IMU 모션 감지 | 🔜 예정 | vesiscanbasicAndroid에서 포팅 예정 |
 | Placement 팬텀 테스트 | 🔜 예정 | Gradient vs SWEEP 비교 |
 | 5-Anchor calibration | 🔜 검토 | CKLaw 전체 포팅 여부 결정 |