diff --git a/USER_GUIDE.md b/USER_GUIDE.md new file mode 100644 index 0000000..dab369e --- /dev/null +++ b/USER_GUIDE.md @@ -0,0 +1,260 @@ +# VesiScan-Basic User Guide + +## App Version: VBTAND0101 + +--- + +## 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 +3. When your device appears in the list, tap it to connect +4. **Complete the Bluetooth pairing** when the system dialog appears + - Do NOT press Cancel — the app will not proceed without pairing +5. Once paired, you will move to the Personalization screen + +### Personalization +- Set your **posture** (standing/sitting/lying) +- Set the **sensor position** +- Set the **Max Volume** (default: 500 mL) +- Tap **Next** to proceed to Sensor Alignment + +--- + +## 3. Sensor Alignment (Placement) + +This step ensures the sensor is positioned correctly over your bladder for accurate measurement. + +### Step 1: Vertical Alignment + +1. **Place the VesiScan-Basic device just above your pubic bone** +2. Apply ultrasound gel between the sensor and your skin +3. Tap the **Start Alignment** button +4. The app will begin scanning and provide direction: + - **"Raise the sensor up"** — slide the device upward toward your navel + - **"Lower the sensor down"** — slide the device downward toward your pubic bone + - **"Raise the sensor slightly"** / **"Lower the sensor slightly"** — make small adjustments +5. Move the sensor **slowly, 1-2mm at a time** +6. When the vertical position is correct, the app will show **Step 2/3** + +> The hint text will show animated dots (e.g., "Raise the sensor up.", "Raise the sensor up..", "Raise the sensor up...") to indicate the system is actively scanning. + +### Step 2: Lateral Alignment + +1. The app will first show **"Checking left/right balance..."** for a few seconds +2. Then it will guide you: + - **"Move left"** — slide the device to the left + - **"Move 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: Final Check (Green Zone) + +1. The app checks overall alignment quality +2. If everything is optimal, the hint will show **"Optimal position!"** +3. The screen will hold this state for **7 seconds** to confirm stability +4. Tap **Alignment Complete** to proceed to the measurement screen + +### If Alignment is Lost +- If the sensor shifts significantly after reaching Optimal: + - The app will show **"Position lost. Place sensor above pubic bone, then press Start"** + - 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. Place above pubic bone, then press Start"** + - 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/Catheterize] [Auto] [Spot] +``` + +### 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 Measurement + +1. Tap the **Auto** button (orange) +2. The device will measure continuously every ~1.5 seconds +3. For the first 5 measurements, the display will show **"—"** (collecting data) +4. After 5+ measurements, the **trimmed mean** value will be displayed +5. The donut chart will update every 5 seconds +6. Tap **Stop** (red) to end Auto measurement + +### Auto Measurement Failure +- If measurements fail **5 times in a row** (sensor shifted or lost contact): + - A dialog will appear: **"Sensor Position Issue"** + - Tap **Go to Alignment** to re-align the sensor + - Or tap **Dismiss** to stay on the measurement screen + +--- + +## 6. Spot Measurement + +1. Tap the **Spot** button +2. The device will take **5 consecutive measurements** (~4 seconds total) +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 Spot measurement, the Auto and Void buttons are disabled. + +--- + +## 7. Void / Catheterize + +1. Tap the **Void / Catheterize** 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 **"Voiding 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** +- Default starting count: **15 catheters** + +--- + +## 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) | + +### Saving Settings +- Adjust values using sliders and toggles +- Tap **Save** to apply and close +- Tap **Cancel** to close without changes (note: slider changes apply in real-time) + +--- + +## 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 sensor above pubic bone" won't go away | Make sure the sensor is attached with gel, then press **Start Alignment** | +| Alignment keeps showing "Raise/Lower" | 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 | +| Spot measurement takes too long | Each Spot takes ~4 seconds (5 readings) | +| "Sensor Position Issue" dialog appears | The sensor may have shifted — go to Alignment | +| Bluetooth connection lost | The app will attempt auto-reconnect (up to 5 times) | +| App freezes on measurement screen | Check BLE connection, try disconnecting and reconnecting | +| Pairing dialog appears but app won't proceed | You must tap **Pair** — canceling will block the connection | + +--- + +## 11. LED Indicators (Device) + +| LED State | Meaning | +|-----------|---------| +| Green blink (0.5s) | Bluetooth scanning | +| Green on 1s / off 3s | Device idle (not attached) | +| Orange blink (1s) | Sensor Alignment in progress | +| Green solid | Alignment complete (Optimal position) | +| Orange fast blink (3Hz) | Error detected | +| Orange solid | Charging | +| Blue solid | Charging complete | + +--- + +## 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