RideFlux
A live dashboard for electric unicycles — with an optional AR-glasses HUD.
Speed · Battery · Temperature · PWM alerts · Trip recording · Rokid HUD
English · 繁體中文 · Website · Privacy · Docs · Story · PLEV White Paper
Screenshots show sample data, not a real ride.
What it does
RideFlux connects to your electric unicycle (EUC) over Bluetooth Low Energy and shows what the wheel is doing, live, on your phone — and, if you have them, on AR glasses. Electric-scooter support is still in development (see Supported vehicles).
| |
|---|
| ⚡ Live dashboard | Speed gauge, battery %, voltage, current, power and temperatures, plus BMS details, live charts, parameter and event pages. Automatically adapts layout for scooters and EUCs. |
| 🛡️ Safety alerts & interlock | Overspeed, over-temperature, low battery and high PWM load. Motion interlock locks risky commands until the vehicle has reported three fresh zero-speed readings. |
| 🗺️ Trip recording | Starts by itself when the vehicle starts moving. Every ride keeps its route plus speed, voltage and current. Export a trip as CSV or GPX, or back up all trips and settings to a ZIP. |
| 🥽 AR glasses HUD | An optional heads-up display on Rokid AR glasses, so you can keep your eyes up. A Bluetooth ring can show or hide it. More ↓ |
| 🎛️ Vehicle controls | Headlight, horn, speed limit, calibration and remote power-off on unicycles — where the wheel supports them. Calibration, speed limit and power-off are refused unless the wheel has reported three fresh zero-speed readings. |
| 🔒 Private by design | No internet permission, no ads, no analytics, no accounts. Everything stays on your phone unless you export it. |
| 🌍 18 languages | Follows the device language by default, with a separate language choice on phone and glasses. Includes right-to-left Arabic and Urdu. |
AR glasses HUD
flowchart LR
W["🛞 Electric vehicle (EUC / Scooter)"] -- "BLE" --> P["📱 RideFlux phone app"]
P -- "BLE bridge · 1 frame / s" --> G["🥽 HUD app on Rokid glasses"]
R["💍 BLE ring"] -. "show / hide" .-> G
- One link to the vehicle. The phone holds the vehicle's single BLE connection and relays a compact frame (speed, battery, voltage, trip, stale flag) to the glasses, so two devices never fight over the peripheral. The glasses can also read the vehicle directly when no phone is around.
- Only your phone. The glasses pair to a token that the phone mints on first run, not to a Bluetooth address that rotates every few minutes, and the phone only streams to glasses you approved.
- Hands-free. A Bluetooth ring paired to the glasses reveals or blanks the HUD. A safety alert still breaks through a blanked HUD.
- Optional. The phone app is a complete dashboard on its own.
Hardware it is developed and tested on: a Begode A2 wheel, Rokid Glasses RV101 (standalone glasses that connect to the phone wirelessly, no cable), and an Android phone.
How the bridge works, byte by byte: docs/BRIDGE_PROTOCOL.md.
Supported vehicles
Electric Unicycles (EUC)
| Brand | Models | Status |
|---|
| Begode / Gotway / ExtremeBull | A2 | ✅ Verified on hardware — a few readings (trip distance, PWM) are known to be off and are being fixed |
| Other models, dual-BMS | 🧪 Experimental |
| KingSong | — | 🧪 Experimental |
| Veteran | Sherman, Abrams, Patton, Lynx, Oryx, Nosfet | 🧪 Experimental |
| Ninebot | One, E+, S2, Mini · Z, ZT, KickScooter Z | 🧪 Experimental |
| Inmotion | V5, V8, V10 · V9, V11, V12, V13, V14 | 🧪 Experimental |
Electric Scooters (PLEV) & Smart BMS
| Category | Brand / Lineage | Status |
|---|
| Scooter | Ninebot Retail (KickScooter ES2 is the reference model) | 🚧 In development — frame codec, pairing state machine and B0 telemetry are written from reverse-engineering notes. Never connected to a real scooter. Pairing and lock stay blocked in the app until a per-model stationary-speed source is verified |
| Scooter | Xiaomi M365 | 🧪 Experimental, read-only vehicle registers — L2 written protocol/crypto specifications plus hardware-log regression fixtures. FE95 authentication and encrypted B0 telemetry already implemented; all 12 writable registers remain NotYetEnabled. The expanded community register inventory is L1 and requires explicit Experimental opt-in. See T07 evidence and gaps. |
| Smart BMS | JBD / Xiaoxiang & Ant BMS | 🧪 Packet decoders (read-only) |
| Controller | VESC | 🧪 Telemetry decoder (read-only) |
- ✅ Verified on hardware means the developer connected a real wheel of that model and checked the app against it.
- 🧪 Experimental means the decoder is implemented from open-source references and recorded test frames, but has not been tried on a real vehicle. It may misread values on yours. Compare it with your vehicle's own display before you rely on it for safety.
- Own one of the experimental vehicles? A short report helps a lot — open an issue with the model, firmware, and what RideFlux showed against what the vehicle's own display showed.
The wire formats and GATT layouts behind each family: docs/PROTOCOLS.md & PLEV White Paper.
Get RideFlux
./gradlew :app:assembleDebug # phone APK
./gradlew :hud-app:assembleDebug # glasses APK
./gradlew test # JVM unit tests
Built with Kotlin, Jetpack Compose, Hilt, Room and DataStore. You need JDK 17 or 21; newer JDKs are not verified.
The story behind RideFlux
A long-form write-up of how the project came to be: why it is not a WheelLog fork, how the Bluetooth protocols were decoded and which bugs real frames exposed, how the phone talks to the glasses, and what is verified and what is not. It was first published on Medium in December 2025 and has been updated for what RideFlux is today. It is written in English.
Privacy
- No internet access. The app declares no
INTERNET permission, so it cannot send anything off your phone.
- No tracking. No ads, analytics, crash reporting or accounts.
- Location only while recording. It is used to draw a trip's route, runs as a visible foreground service, and is never requested in the background. Deny it and trips are still recorded, without a route.
- Your data, your call. Trips stay on the phone until you export them; Android cloud backup is switched off for the app.
Full text: PRIVACY.md.
For developers
The technical reference that used to fill this README now lives in docs/, word for word.
| Document | What is in it |
|---|
| Architecture | Module layering, design rules, repository layout |
| Wheel protocols | Wheel families, GATT topologies, where the protocol knowledge comes from |
| Phone ↔ glasses bridge | Pairing token, startup ordering, scan budget, frame layout |
| Localization | The 18 translations, the coverage test, how to add a string or a language |
| Building & releasing | JDK and SDK, signing and secrets, tests, Sonar, dependency verification |
| Play Store assets | Store graphics and the scripts that regenerate them |
| Website | The GitHub Pages site in site/ and how it is built |
| Articles | Long-form writing about the project; the website's /story/ page is rendered from the article here |
Disclaimer
RideFlux is an independently developed third-party application. It is not affiliated with, endorsed by, or sponsored by any of the wheel manufacturers or Rokid named above; those names are trademarks of their owners and appear only to say which products RideFlux can talk to. Pay attention to the road while you ride and do not operate your phone while riding.
License
Distributed under the GNU General Public License v3.0 or later. Source files carry
SPDX-License-Identifier: GPL-3.0-or-later. See LICENSE for the full text.
Additional permission: Rokid CXR SDK
The RideFlux project contributors, as the copyright holders of the RideFlux source code,
grant the following additional permission under section 7 of the GNU General Public License,
version 3. It applies to the RideFlux source code in this repository; the GPL applies
unchanged otherwise.
If you modify this Program, or any covered work, by linking or combining it with the Rokid
CXR SDK libraries (com.rokid.cxr:client-m and com.rokid.cxr:cxr-service-bridge) (or a
modified version of those libraries), containing parts covered by the terms under which
Rokid provides them, the licensors of this Program grant you additional permission to
convey the resulting work.
This permission does not:
- give you any rights in the Rokid libraries. They are Rokid's proprietary software and are
not licensed by this project; Rokid's own terms govern whether and how you may use and
redistribute them (see
NOTICE);
- reach material that other people wrote, such as the third-party material listed in
NOTICE, which stays under its own license.
As section 7 of the GPL allows, you may remove this additional permission from your copy of
the Program, or from any part of it.
Acknowledgements
Some protocol test data comes from WheelLog, and the Rokid CXR SDK is Rokid's own software. Credits and terms are in NOTICE.
