VesiscanClinicalAndroid/USER_GUIDE.md

# VesiScan-Basic User Guide

## App Version: VBTAND0101
## Last Updated: 2026-05-11

---

## 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
5. You will arrive at the **Home** screen

### Home Screen
- 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
- Set your **Max Volume** (200-800 mL, default: 500 mL)
- 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.

### 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)

### Step 1/3: Vertical Alignment

The app will begin scanning and provide direction:
- **"Slide up ↑"** — slide the device upward toward your navel
- **"Slide down ↓"** — slide the device downward toward your pubic bone
- **"Slide up slightly ↑"** / **"Slide down slightly ↓"** — make small adjustments
- Move the sensor **slowly, 1-2mm at a time**
- When the vertical position is correct, the app will show **Step 2/3**

> The hint text will show animated dots (e.g., "Slide up ↑.", "Slide up ↑..", "Slide up ↑...") to indicate the system is actively scanning.

### Step 2/3: Lateral Alignment

1. The app will first show **"Checking..."** for a few seconds
2. Then it will guide you:
   - **"Slide left ←"** — slide the device to the left
   - **"Slide right →"** — slide the device to the right
3. Adjust until both lateral sensors (CH4 and CH5) detect the bladder equally
4. When balanced, the app will show **Step 3/3**

### Step 3/3: Final Check (Green Zone)

1. The app checks overall alignment quality (CV + LR deviation)
2. If everything is optimal, the hint will show **"In position!"**
3. The screen background turns green and holds this state for **7 seconds** to confirm stability
4. The **Start Scanning** button (green) becomes active
5. Tap **Start Scanning** to proceed to the measurement screen

### If Alignment is Lost
- If the sensor shifts significantly after reaching "In position!":
  - The app allows up to **3 consecutive failures** before exiting GREEN
  - After 3 failures: **"Position lost. Restart above pubic bone."**
  - The scanning will stop automatically
  - Re-place the sensor and tap **Start Alignment** again

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

```
  [Placement]  [Battery]  [Catheters]  [Settings]
  
            Enjoy your day!
            
         ┌─────────────────┐
         │    Donut Chart   │
         │                  │
         │     [Bladdy]     │
         │    325 mL        │
         └─────────────────┘
         
   Current Measurement    |     65%
        280 mL            |   325/500 mL
        
   [Void/Catheterization] [Auto Scan] [Single Scan]
```

### 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 800ms interval)
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

### 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. Void / Catheterization

1. Tap the **Void / Catheterization** button
2. The current measurement is recorded to the voiding diary
3. The catheter count decreases by 1
4. The bladder level resets to 0
5. A toast message **"Recorded"** will appear

### 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 |
|---------|-------------|---------|
| Max Volume | Maximum bladder volume for fill calculation | 500 mL |
| Catheter Threshold | Alert level for catheterization | Level 7 |

### 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) |

---

## 9. Navigation

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

---

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