Skip to content

About

Sideload apps & watchfaces to Xiaomi Mi Band 8/9/10 straight from the browser (Web Serial + Web Bluetooth)

Topics

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

58 Commits

Folders and files

Repository files navigation

MiBand Hack

A webapp to sideload apps (.rpk) and watchfaces (.bin) onto Mi Band 8 / 9 / 10 straight from the browser on macOS, Windows and Linux. No software to install, no Android phone needed.

⚠ This tool can brick your device. Use it at your own risk.

Independent project, not affiliated with Xiaomi. The protocol is ported from Gadgetbridge (AGPL-3.0).

πŸ‘‰ Use it now: https://miband.trinh.uk Β· User guide Β· Developer guide

Why

As of 10/2026, every existing way to sideload requires installing software:

Tool Platform Notes
Notify for Xiaomi Android Paid app, has a tab for installing third-party apps
Gadgetbridge Android Open source, has RpkService
AstroBox-NG Win / Linux / Android / iOS (native app) Rust core, the Tauri app is closed source, no public web version yet

MiBand Hack fills that gap: open a web page and install.

Support

Device Connection Browser API Status
Mi Band 9, 10, 9 Pro, 10 Pro Bluetooth Classic (SPP) Web Serial (Chrome/Edge β‰₯ 117, desktop) Implemented, not yet tested on a real device
Mi Band 9 (on a Mac) BLE V2 (fe95 / 005e, 005f) Web Bluetooth Connect, auth (with the Device ID), device info, app and watchface lists tested (fw 2.3.98); app install not yet confirmed
Mi Band 9 Active BLE V2 (fe95 / 005e, 005f) Web Bluetooth Implemented, not yet tested on a real device
Mi Band 8 BLE V1 (fe95 / 0051–0055) Web Bluetooth Connect, auth, device info, watchface list and watchface install tested (fw 2.3.14, ~2 KB/s); takes no apps (.rpk)
  • Formats: .rpk (Vela quick app), watchface v2 (header 5A A5). Watchface v3 and firmware are deliberately not supported (firmware can easily brick the band).
  • Browser: desktop Chrome or Edge. Safari/Firefox have no Web Serial/Web Bluetooth.
  • Linux: you may need to enable chrome://flags/#enable-experimental-web-platform-features.

Usage

  1. Get the auth key: press "Get it automatically with your Xiaomi account", then scan the QR code with a phone signed in to Xiaomi. If no key comes out, use Other ways on the page (iPhone/iPad: the Mi Fitness folder; Android: the Mi Fitness log), see docs/GUIDE.md.
  2. Turn off Bluetooth on your phone so the band is free to connect.
  3. Mi Band 9/10: pair the band in the OS Bluetooth settings first.
  4. Open the webapp β†’ enter the key β†’ Connect β†’ drag and drop a .rpk file β†’ Install to band.

Demo apps (press Add to install)

App Description Source
Calculator Calculator + βˆ’ Γ— Γ·, decimals demo-apps/calculator
Drawing Freehand drawing: 5 colours, 3 brush sizes, eraser, undo, autosave demo-apps/drawing
Notes Shows the user's notes (read-only). Notes are written in the webapp; the browser repacks and re-signs the .rpk and installs it demo-apps/notes + src/rpk/
Checklist Shopping, to-do and packing lists written in the webapp (repacked and re-signed in the browser like Notes); tap items on the band to tick them off, ticks saved on the band demo-apps/checklist + src/rpk/
Snake Snake game: swipe or tap the left/right half to turn, speeds up, saves the high score demo-apps/snake
SAT Flashcards Learn 1,355 SAT words: flip cards (Know it / Again) or a multiple-choice quiz, spaced repetition (Leitner boxes), progress saved on the band demo-apps/sat-flashcards
Flashcards Your own decks (any subject or language), written or pasted from a spreadsheet in the webapp and repacked into the .rpk like Notes; flip cards or multiple-choice quiz, Leitner progress per deck saved on the band demo-apps/flashcards + src/decks/
Metronome Silent metronome: the beat as a vibration on the wrist plus a flash, 30–250 BPM, tap tempo, accent on beat 1 in 2/4, 3/4, 4/4, 6/8 demo-apps/metronome
Counter Tally counter: tap anywhere to count (short buzz), βˆ’1, reset with a confirming second tap, goal presets with a long buzz and a tick, four named counters saved on the band demo-apps/counter
Random Random number (min/max with βˆ’ / +), dice (1 or 2 with the sum), coin flip; No repeats mode for raffles; buzz on each result, settings saved on the band demo-apps/random

Outside the catalog: Phone Remote (demo-apps/phone-remote) β€” press on the band to take photos, change slides, play/pause on the phone. It needs the companion Android app (same package, same signature) and Mi Fitness to relay messages over system.interconnect; not yet verified on Mi Band 9/10, so it is not in the catalog yet.

All catalog apps are built with aiot-toolkit 2.0.5 (Xiaomi Vela's official toolchain). None has been run on a real band yet.

src/rpk/ is a WebCrypto port of aiot-toolkit's "RPK Sig Block 42" signature format (a variant of APK Signature Scheme v2, RSA PKCS#1 v1.5 + SHA-256). Tests confirm the signature is byte-for-byte identical to the one the toolkit produces. Notes is signed with a demo key that is deliberately public (src/rpk/demo-key/).

Getting the key via QR: how it works

worker/xiaomi-cloud.ts does a Xiaomi QR login for the Mi Fitness service (sid=miothealth, callback https://sts-hlth.io.mi.com/healthapp/sts): /api/xiaomi/qr creates the QR code, then /api/xiaomi/poll long-polls until the user scans it and then:

  1. Mi Fitness: gets the service token and calls POST https://hlth.io.mi.com/app/v1/source/get_source_list with data={"page_size":50,"status":1} (then the regional <region>.hlth.io.mi.com if a region is picked). The bound bands come back with detail.encrypt_key / detail.auth_key (and sometimes detail.token); every distinct 32-hex value is offered. Two request encodings are tried: the Mi Home one (params in the query, used by ha_miband, Apache-2.0) and a single RC4 stream over sorted params in the body (huami-token, MIT; AstroBox, AGPL-3.0).
  2. Mi Home (only if no Mi Fitness key was found): signs in to sid=xiaomiio with the passToken of the same login (no second scan), lists devices and calls blt_get_beaconkey, as in Xiaomi Cloud Tokens Extractor (MIT).

The login session (ssecurity/serviceToken/passToken) only lives within a single Worker request: it is not returned to the browser, not stored, and observability is off. A proxy is needed because Xiaomi's API does not let browsers call it directly (CORS is blocked).

Unverified here: the Mi Fitness route follows three independent open-source clients and Xiaomi's servers accept the miothealth QR login, but this project has not yet run it against a real account with a band. The Mi Home route rarely helps for Mi Band 8/9/10, which are not Mi Home devices.

Fallbacks that need no cloud call (also in the page under Other ways and in docs/GUIDE.md):

  • iPhone / iPad: Files β†’ On My iPhone/iPad β†’ Mi Fitness β†’ Compress, then pick the zip in the page. src/core/mifitness-files.ts reads MHWCahe/<uid>/VirtualDevice_registerList/manifest.sqlite (+ -wal) in the browser: a small SQLite reader, a binary-plist reader and NSKeyedArchiver unwrapping, taking encryptKey from every registerList_<region> entry. Layout documented by xiaomi-band-ios-export (MIT, tested there with a Smart Band 10); tested here with synthetic fixtures only.
  • Android: the Mi Fitness logs in Android/data/com.mi.health/files/log/ contain encryptKey= / token= (see Gadgetbridge and Gadgetbridge issues #4052, #4859).

Health data

Download what the band recorded (steps, heart rate, sleep, SpOβ‚‚, stress, workouts) as JSON, CSV or raw files, query it with your own AI agent through a local MCP server (tools/health-mcp) Nothing leaves your machine. Format, privacy and what is still untested: docs/health-data.md.

Deploy

One Worker serves both the static page (dist/) and /api/*, on the custom domain miband.trinh.uk:

echo 'CLOUDFLARE_ACCOUNT_ID=<your id>' > .env   # Wrangler reads this file itself; it is gitignored
npm run deploy

To deploy to a different domain, edit routes in wrangler.jsonc.

The page is a PWA (manifest + service worker): users press "Install as app" to get their own icon, and it opens even offline (except for the key retrieval step).

Development

npm install
npm run dev        # http://localhost:5173 (Web Serial/Bluetooth work on localhost)
npm run dev:worker # also runs the Worker (/api/xiaomi/*) at http://localhost:8787
npm test           # unit tests + integration tests against a simulated band
npm run build      # static build to dist/, deploy to any HTTPS host

Structure

src/
  core/        bytes, checksum (CRC16/ARC, CRC32), crypto (hand-written AES-CCM, AES-CTR, HMAC),
               auth (miwear-auth handshake), proto (protobuf subset), packets (SPP V1/V2), files (.rpk/.bin)
  transport/   serial.ts (Web Serial β†’ RFCOMM SPP), ble.ts (Web Bluetooth, auto-detects BLE V1/V2)
  protocol/    stream-link.ts (SPP V1/V2 + sliding window, used for both SPP and BLE V2),
               ble-v1-link.ts (Mi Band 8 chunk protocol)
  device.ts    auth, device info, app/watchface lists, install (DataUpload)
  main.ts      UI (including the "Demo apps" catalog read from public/apps/catalog.json)
worker/        Cloudflare Worker: serves the page + the Xiaomi QR key API
demo-apps/     demo app sources (Calculator)
test/
  core.test.ts         crypto checked against node:crypto, frame/protobuf vectors, file parsing
  fake-band.ts         simulated band (band-side crypto uses node:crypto, independent of the main code)
  integration.test.ts  version probe β†’ SPP V2 β†’ auth β†’ end-to-end .rpk install

Protocol details: docs/protocol.md. Real-device captures (Mi Band 10 with Mi Fitness on iOS: session config, binding flow, NO_BOUND): docs/captures/mi-band-10-ios.md; why the browser cannot bind such a band: docs/binding-research.md.

Next steps

  • Test on a real Mi Band 9/10 over Web Serial on macOS, Windows and Linux (the biggest risk, see the "Risks" section in the docs).
  • Test Mi Band 8 and tune the BLE write size (default 180 bytes).
  • App/watchface store (catalog + search + one-tap install).
  • i18n (English / δΈ­ζ–‡).
  • Confirm the Mi Fitness QR route (get_source_list) and the iPhone/iPad folder route with a real account and band; note which key field (encrypt_key, token) the band accepts.

License

AGPL-3.0-or-later, because the protocol code is a port of Gadgetbridge (AGPL-3.0). The Xiaomi login flow is ported from Xiaomi Cloud Tokens Extractor (MIT); the Mi Fitness calls follow ha_miband (Apache-2.0), huami-token (MIT) and AstroBox (AGPL-3.0). See LICENSE.

About

Sideload apps & watchfaces to Xiaomi Mi Band 8/9/10 straight from the browser (Web Serial + Web Bluetooth)

Topics

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages