Epley Coach

Your phone becomes the angle gauge for the five-minute vertigo cure, and it won't start the timer until your head is actually in position.

Comment

Inspiration

BPPV is the most common cause of vertigo. The fix is the Epley manoeuvre: a few head positions, about five minutes, no medicine. When I read the research I found that in a German population study only 8% of people with BPPV received effective treatment, and that people doing it at home from a video get their head angles wrong by 40 to 51 degrees. The treatment exists. Getting the angles right alone, at 3 a.m., while the room is spinning, is the hard part. Every phone already has the sensors to measure a head angle, so I wanted to see if a phone could guide it properly.

What it does

  1. Safety check first, every run. Positional vertigo can sometimes be a stroke, and an app cannot see the eye movements that tell them apart. So before anything else it asks about red-flag symptoms. Any yes stops the app and points you to emergency help. It can't be skipped and it is never behind a paywall.
  2. Finds which ear. BPPV often comes back somewhere different: in a 585-patient randomised trial (JAMA Neurology 2023), 56% of failed home treatments were a different type of BPPV from the original diagnosis. Using six questions from that trial resolved 72.4% of recurrences, compared with 42.9% when people reused their old diagnosis. If the answers point to the horizontal canal, the app says the Epley is the wrong manoeuvre.
  3. Guides every position. You hold the phone against your cheek, calibrate seated, and the app tracks both head angles live (turn and tip). Each position is shown on a 3D head. The 45-second hold timer only counts while your head is inside the target range and still, and a voice talks you through it, because by position four you can't look at the screen.
  4. After-care and a doctor's PDF. It gives the after-care advice from the clinical guideline, and you can export every run (ear, time, hold times and measured angles) as a PDF for your doctor.

How I built it

  • Kotlin and Jetpack Compose for Android. All the maths (quaternions, swing-twist decomposition, angle unwrapping, the hold gate, the triage and after-care rules) lives in a pure Kotlin module with no Android code, so it is tested on the JVM in seconds.
  • The phone's game rotation vector sensor (gyroscope and accelerometer, fused). Every angle is measured relative to a calibration on your own head, so the phone's fixed sensor error cancels out.
  • A real 3D head model rendered with three.js for the position figures.
  • RevenueCat for the one paid feature (details below).
  • 212 automated tests, plus screenshot tests (Robolectric and Roborazzi) that compare every screen against the design, day and night.
  • I built it on a Windows laptop with no Android Studio, everything from the command line, and I used Claude Code a lot as my pair programmer.

Challenges I ran into

  • A single phone sensor can't tell "the head turned" from "the phone slipped on the cheek". I handle it by speed: a turn faster than a neck can move triggers a "the phone moved" warning and asks you to recalibrate.
  • My test phone reads about 8 degrees off true when lying flat. Instead of trusting the hardware, every angle is relative to the calibration, and I wrote a test that pushes 9.2 degree offsets through the real code to prove the guided angles don't move.
  • Designing for someone who is dizzy right now: one action per screen, big type, a night theme, a voice, and calm motion only. Nothing spins, because for this user a moving screen is a symptom.

Accomplishments that I'm proud of

  • The timer genuinely refuses to start until both angles are in range and you are still. That one rule is the whole point of the app.
  • Every clinical number in the app traces back to a citation in the repo, including the ones that made my pitch weaker.
  • It is my first Android app, and it is fully open source.

What I learned

How phone orientation sensors really work (and fail), how to read clinical trials carefully instead of overselling them, and how much design matters when your user is unwell.

What's next for Epley Coach

A small supervised study with a physiotherapist to check the angle guidance on real patients, a headband mount option for steadier readings, and an iOS version.

Honest limits

Epley Coach is not a medical device. It claims angle accuracy, which I measured on my own phone, and nothing about cure rates, which nobody has tested for this app.

Built With

Share this project:

Updates

Submission history