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). 원본 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채널 (CH0CH2) 로 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)

설정 패널 라벨 크기는 화면 너비에 따라 자동 조절:

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 의 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