VesiscanClinicalAndroid/USER_GUIDE.md

# VesiScan-Basic User Guide

## App Version: 1.2.0-demo (versionCode 26)
## Last Updated: 2026-07-13
## Recommended Firmware: **VBTFW0120+** (mim FIFO 지원 필수. VBTFW0121 은 `mls mode 0` handler 취약)

---

## 1. Getting Started

### First Launch
1. Install the app and open it
2. Complete the onboarding screens
3. Register your information (name, age, height, weight)
4. ~~Set a 4-digit PIN~~ — **현재 빌드는 PIN 데모 자동통과**: PinView 진입 시 즉시 verified 처리 (시연용)
5. You will arrive at the **Home** screen

> ⚠️ **DEMO 빌드 표시**: 현재 빌드는 PIN 잠금이 우회됩니다 ([PinView.kt:23-29](app/src/main/java/com/medithings/vesiscan/ui/views/pin/PinView.kt#L23-L29)). 원본 UI는 `if (false) { ... }` 안에 보존되어 있어 배포 시 1줄 제거로 복구 가능. 배포 전 정리 체크리스트 참조.

### Home Screen
- 큰 **Bladdy 캐릭터** (3× 확대, 최대 660dp, 작은 화면에선 90% 캡)
- Tap **Start** to begin
- The app version is displayed below "Smart Bladder Monitoring"
- To enable Developer Mode: tap the Bladdy character **3 times quickly** (within 1.5 seconds)

---

## 2. Connecting the Device

1. Tap **Start** on the Home screen
2. The app will scan for nearby VesiScan devices (sorted alphabetically)
3. When your device appears in the list, tap it to connect
4. **Complete the Bluetooth pairing** when the system dialog appears
   - A "Pairing Required" dialog will guide you through the process
   - Tap **Pair** on the system Bluetooth dialog — canceling will block the connection
   - The app waits up to 30 seconds for pairing to complete
5. Once paired, you will move to the Personalization screen

### Personalization (전면 리디자인 — 평행 2-카드)

상하 정렬된 두 카드로 구성:

**Card 1: Maximum Bladder Capacity**
- 큰 숫자 표시 (예: `500` 64sp ExtraBold + `mL` 24sp)
- 56dp 원형 솔리드 **StepperButton −/+** 좌우 배치
- 슬라이더 (200~800 mL, 50 단위, `roundToInt()` 절삭 fix 적용)
- 카드 헤더 34sp ExtraBold

**Card 2: Catheter Threshold**
- 3분할 텍스트: `Level` 24sp + `7` 64sp + `/10` 24sp (Card 1과 픽셀 매칭)
- 56dp StepperButton −/+
- 슬라이더 Level 1~10 (`roundToInt` 적용)
- 카드 헤더 34sp ExtraBold

두 카드는 64dp 간격으로 수직 중앙 정렬. Bladdy 히어로는 상단에 동적 사이징.

Tap **Continue** to proceed to Sensor Alignment.

---

## 3. Sensor Alignment (Placement)

This step ensures the sensor is positioned correctly over your bladder for accurate measurement.

### 화면 디자인 (리디자인 적용)
- **큰 타이틀 "Sensor Alignment"** 38sp ExtraBold 검정 (Maximum Bladder Capacity 톤 통일)
- **3-stop vertical gradient 배경** (MlTeal 14% / 흰 / MlPrimary 10%) — GREEN 진입 시 단색 톤으로 덮임
- **Hint 텍스트에서 "pubic bone" 인라인 빨강 ExtraBold 강조**
- Canvas 방향 화살표 제거 — hint 텍스트만으로 방향 안내 (이전 4종 화살표 + 치골 아치 라인+halo+endpoint 모두 제거)
- 토르소 실루엣 상단 16% UP shift (chestY 0.06 → 0.09)

### Before Starting
- Place VesiScan above the pubic bone
- Apply ultrasound gel between the sensor and your skin
- Tap the **Start Alignment** button (large orange button)

### 알고리즘 V1 (일반 사용자, 3-stage) / V2 (Clinical Alignment 세션, 6-stage)

일반 진입 (모니터링 → Settings → 재측정 등) 은 **V1 (3-stage)**, Clinical
Home 의 **Sensor Alignment** 버튼으로 진입한 세션은 자동으로 **V2 (6-stage)**
로 활성화됩니다. Step indicator ("단계 N/M") 로 구분 가능.

### V1: 3-stage (일반 진입)

**Step 1/3: Vertical Alignment**
- **"Slide up ↑"** / **"Slide down ↓"** / **"Slide up slightly ↑"** 등의 방향 안내
- 1~2mm 씩 천천히 이동, 위치가 잡히면 Step 2/3

**Step 2/3: Lateral Alignment**
- **"Checking..."** → **"Slide left ←"** / **"Slide right →"** — CH4/CH5 균형
- 균형 잡히면 Step 3/3

**Step 3/3: Final Check (Green Zone)**
- CV + LR deviation 확인 → **"최적의 위치입니다!"** (2026-07-07 문구 개선)
- 배경 초록 + **5초 hold** (2026-07-07: 7초 → 5초 유지, 조기 unlock 방지 강화)
- **Start Scanning** 활성 → 측정 화면으로

### V2: 6-stage (Clinical Alignment 세션 전용)

방광 하부/후벽 각도 오차를 실시간 보정하는 정밀 정렬 알고리즘.

| 단계 | 화면 문구 예 | 조건 |
|:---:|---|---|
| 1/6 INITIAL_ACCUM | "잠시 그대로 두세요 (n/10)" | baseline 10 cycle 누적 |
| 2/6 VERTICAL_CLIMB | "↑ 위로 조금씩 올리세요 (hit N/6)" | CH3 sliding window majority — 최근 6 프레임 중 3회 hit |
| 3/6 CH3_STABILIZE | "✓ ch3 검출 — 위치 유지 (n/10)" | CH3 안정 확인, 단발 flick 무시 (window=4, majority=3) |
| 4/6 CENTER_OPTIMIZE | "↑/↓ 조금 (CV=0.xx)" | CH0~CH3 chord CV 임계 0.15 |
| 5/6 LR_BALANCE | "← / → \|Δ\|=n" | CH4/CH5 균형 |
| 6/6 FINAL_CONFIRM | "✓ 최적의 위치입니다!" | 5 프레임 재확인 통과 → GREEN |

**추가 안전장치**:
- **Relaxed mode**: VERTICAL_CLIMB 에 20 프레임 (~5초) 이상 갇히면 CH3 없이도
  상단 3채널 (CH0~CH2) 로 CENTER_OPT 진입. CH3 flicker 심한 자세에서 무한 대기 방지.
- **Soft hint**: 12 프레임 (~3초) 이상 반복되면 "↑ 위로" → "CH3 신호 확인 중 · 위치 유지"
  로 문구 자동 완화.
- **6단계 완료 후 GREEN 5초 hold**: 사용자가 "측정 시작" 버튼 누를 시간 확보.

### If Alignment is Lost
- Green Zone 유지 중 실패해도 즉시 리셋 X — **10 consecutive failures** (약 5초+)
  까지 관대하게 유지 (2026-07-07 완화, 이전 3-strike → 10-strike). 이 사이는
  GREEN 유지 + "최적의 위치입니다!" 표시.
- 10회 연속 실패: **"위치를 놓쳤습니다. 치골 위에서 다시 시작해주세요"** →
  자동 재시작 대기.

### If the Sensor is Detached
- If the sensor loses contact with skin:
  - The app will show **"Sensor detached. Restart above pubic bone."**
  - Re-attach the sensor with gel and tap **Start Alignment**

### Tips
- Use **plenty of ultrasound gel** — dry contact causes poor readings
- Keep the sensor **flat against the skin** — tilting reduces accuracy
- Move **slowly** — fast movements cause unstable readings
- You can tap **Skip** to go directly to measurement without alignment

---

## 4. Measurement Screen

After alignment, you will see the main measurement screen with a donut chart.

### Screen Layout

```
  [Home] [Placement]  [Battery]  [Catheters]  [Settings]    ← Home 아이콘 추가됨
  
            Enjoy your day!
            
         ┌─────────────────┐
         │    Donut Chart   │   ← 너비 × 0.85 적응형 (이전 0.75 + 360dp cap 제거)
         │                  │
         │     [Bladdy]     │   ← 0.483 비율 (이전 0.55에서 -15% 후 +15%)
         │    325 mL        │   ← 72sp ExtraBold (이전 24sp의 3배), letterSpacing -1
         └─────────────────┘
         
   Current Measurement    |     65%
        280 mL            |   325/500 mL
        
   [Voiding/             [Auto Scan] [Single Scan]
    Catheterization]
```

### Top Bar
- **Home 아이콘** (좌측 추가) — `appState.goHome()` 호출, 즉시 홈으로
- **Placement 아이콘** (Home 옆) — `enterPlacementFromMonitoring()` 호출 → Back 시 Monitoring으로 복귀
- 배터리 / 카테터 카운트 / Settings 톱니바퀴는 기존과 동일

### Understanding the Display

| Element | Description |
|---------|-------------|
| **Donut Chart** | Fills based on max measured volume / max volume setting |
| **Center Value** | Maximum measured volume this session (updates every 5 seconds) |
| **Current Measurement** | Latest trimmed mean value (Auto) or last Spot result |
| **Fill Card** | Top: fill percentage, Bottom: max measured / bladder max volume |
| **Battery Icon** | Device battery level with visual indicator |
| **Catheter Count** | Remaining catheters (tap to add more) |

---

## 5. Auto Scan

1. Tap the **Auto Scan** button (orange)
2. The device will measure continuously (**minimum 600ms interval**, 이전 1500ms에서 단축)
3. For the first 5 measurements, the display will show **"—"** (collecting data)
4. After 5+ measurements, the **trimmed mean** value will be displayed (10-sample window, top/bottom excluded)
5. The donut chart will update every 5 seconds
6. Tap **Stop Scan** (red) to end Auto measurement

> **속도 향상 배경 (2026-05-26)**: FW VBTFW0116 + MTU 247 + CONNECTION_PRIORITY_HIGH 조합으로
> 한 측정 사이클이 ~330ms로 단축. 이전(~1.2초) 대비 **4배 향상**. 자세한 내용은 Pipeline Summary §5.1 참조.

### Auto Measurement Failure
- If 2+ channels fail **5 times in a row** (sensor shifted or lost contact):
  - A dialog will appear: **"Position lost. Restart from alignment"**
  - Tap **Realign** to re-align the sensor
  - Or tap **Dismiss** to stay on the measurement screen

---

## 6. Single Scan (Spot)

1. Tap the **Single Scan** button
2. The device will take **5 consecutive measurements** (~4 seconds total, max 8 attempts)
3. A **spinner** will show during measurement
4. The result (trimmed mean of 5 readings) will be displayed immediately
5. The donut chart and Current Measurement card will update

> During Single Scan, the Auto Scan and Void buttons are disabled.

---

## 7. Voiding / Catheterization (텍스트 변경)

1. Tap the **Voiding / Catheterization** button (이전 "Void/Catheterization" → **"Voiding/"** 로 첫 줄 갱신)
2. The current measurement is recorded to the voiding diary
3. **자동: Auto Scan 진행 중이면 stop** + 측정 상태 정규화 (`displayMaxVolumeMl`/window/timer 모두 0)
4. The catheter count decreases by 1
5. The bladder level resets to 0
6. **큰 "Recorded" 다이얼로그** (48sp ExtraBold 흰색, MlPrimary 0.95 alpha 배경, 1.5초 자동 닫힘) — 이전 Toast 대체

### Managing Catheters
- The catheter count is shown at the top of the screen (hospital icon + number)
- **Tap the catheter count** to add more catheters
- Enter the number and tap **Add**

---

## 8. Settings

Tap the **gear icon** at the top right to open settings.

### General Settings (always visible)
| Setting | Description | Default |
|---------|-------------|---------|
| Bladder Capacity | Maximum bladder volume for fill calculation | 500 mL |
| Catheter Threshold | Alert level for catheterization | Level 8 |

### Developer Settings (Developer Mode only)
| Setting | Description |
|---------|-------------|
| Threshold | Otsu (auto) or manual echo threshold |
| DPS | Distance per sample (mm) |
| Detection | Method A / B / C |
| BV | Frustum / V41 (volume calculation method) |
| SG Filter | Savitzky-Golay noise filter on/off |
| Post Max | Maximum sample index for wall detection (filters floor reflections) |

### 폰/태블릿 자동 폰트 분기 (2026-05-26)

설정 패널 라벨 크기는 화면 너비에 따라 자동 조절:
```kotlin
val fontScale = (screenWidth / 360f).coerceIn(1.0f, 1.8f)
val isTablet = screenWidth >= 600
labelSize    = (14 * fontScale).sp       // 폰 14sp, 태블릿 ~25sp
rowSpacing   = (6  * fontScale).dp       // 폰 6dp, 태블릿 ~10dp
dividerPadding = if (isTablet) 12.dp else 0.dp
```

| 기기 | screenWidth | labelSize |
|---|---|---|
| Galaxy S20 (폰) | 360dp | 14sp |
| Pixel 7 (폰) | 412dp | 16sp |
| 갤탭 S6 Lite | 600dp | 23sp |
| 갤탭 S8 / iPad Pro | 800dp+ | 25sp (cap) |

이전 시도(28sp 하드코딩)에서 폰 화면이 곱창나던 문제를 해결.

### Dev Mode 추가 기능

- **HomeView Bladdy 3탭** → Developer Mode 토글
- **DeviceScanView "No devices found" 화면 + dev 모드** → "Enter Measurement Mode (Dev)" 버튼 (BLE 없이 측정 화면 진입)
- **PiezoMonitoring Status 배지 dev 탭** → 60~maxVol-50 범위 더미 측정값 랜덤 주입 (BLE 없이 동작 검증용)
- **dev 모드 한정 ChannelPanel / BleDebugPanel** 표시 (Developer Tools 버튼 토글)

---

## 9. Navigation

| Action | Result |
|--------|--------|
| **Home button** (top left) | Go to Home screen (`appState.goHome()`) |
| **Placement button** (Home 옆) | Re-enter Sensor Alignment (`enterPlacementFromMonitoring()`) |
| **Settings button** (top right) | Open/close settings panel |
| **Back button** (Android) | Go to previous screen |
| **Back button on Home** | "Exit App?" confirmation dialog |

### Placement 진입 경로 분기 (2026-05-12 신규)

`placementFromMonitoring` 플래그로 Back 동작이 자동 분기:

- **Personalization → Placement → Monitoring** (정방향): Placement에서 Back = Personalization으로 복귀
- **Monitoring → Placement** (재정렬): Placement에서 Back = Monitoring으로 복귀

코드: [AppState.kt](app/src/main/java/com/medithings/vesiscan/AppState.kt) 의 `enterPlacementFromMonitoring()` / `backFromPlacementGuide()`.

### startFromHome() 라우팅 fix

페어링 완료 상태에서 Home → Start 시 Personalization부터 시작 (이전: Monitoring 직행 버그).

---

## 10. Troubleshooting

| Problem | Solution |
|---------|----------|
| "Place VesiScan above the pubic bone" won't go away | Make sure the sensor is attached with gel, then press **Start Alignment** |
| Alignment keeps showing "Slide up/down" | Move the sensor **very slowly**, 1-2mm at a time |
| Auto measurement shows "—" | Wait for at least 5 measurements to accumulate |
| Donut chart value doesn't change | Max volume updates every 5 seconds |
| Single Scan takes too long | Each scan takes ~4 seconds (5 readings) |
| "Position lost" dialog appears | The sensor may have shifted — go to Alignment |
| Bluetooth connection lost | The app will attempt auto-reconnect (up to 5 times) |
| Pairing dialog appears but app won't proceed | You must tap **Pair** — canceling will block the connection |

---

## 11. LED Indicators (Device)

| LED State | Meaning |
|-----------|---------|
| State 0 | OFF (default) |
| State 4 | Sensor detached warning |
| State 5 | Alignment searching (orange) |
| State 6 | Alignment complete / In position (green) |

---

## 12. Important Notes

- **Always use ultrasound gel** between the sensor and skin
- **Keep the sensor still** during measurement — movement reduces accuracy
- **Do not use the device while charging**
- The app keeps the screen on during use to prevent BLE disconnection
- Measurement logs are automatically saved to your device:
  - BLE logs: `Downloads/VesiScan_BLE_*.log`
  - ADC data: `Downloads/VesiScan_ADC/*.csv`

---

## Contact

For technical support, contact:
- App Development: dwjang
- Algorithm: Charles KWON / eunji.won
- Medithings Co., Ltd. — https://medithings.net