Android app for Amazfit/Zepp accounts: Bluetooth pairing keys for
Gadgetbridge,
GPS assistance downloads, optional gps_uihh.bin build, firmware checks and
downloads, and Apps / Watchfaces browsing with install QR codes.
Based on huami-token. Firmware and market flows follow the same Amazfit paths as Zepp Explorer, with devices from ZeppOS-DevicesList.
Xiaomi Mi Fitness login is not included.
Zelp is not affiliated with, endorsed by, or connected to Zepp, Amazfit, Huami, or their parent companies. Zepp and Amazfit are trademarks of their respective owners. Use Zelp with your own Amazfit/Zepp account.
That is a product disclaimer, not a license restriction. Zelp is free software under the GNU GPL (see License).
Zelp was mostly built with AI assistance. Review carefully before relying on it; treat the codebase as experimental and verify behavior yourself.
Zelp is a portmanteau of Zepp + help.
- GPS — GPS packs and optional
gps_uihh.bin(sign-in required) - Watchfaces — watchface list for a watch model (sign-in required)
- Apps — apps list for a watch model (sign-in required)
- Firmware — firmware history and downloads (no sign-in)
Account, pairing keys, and download folder live under Settings (gear icon on every tab), not as a separate tab. On first launch you complete a short setup: sign in, or continue without signing in.
GPS, Watchfaces, and Apps show a small lock mark and stay closed until you sign in. Tapping them while signed out shows a snackbar. Firmware is open without an account.
- Sign in with Amazfit email + password (credentials are saved). Pairing-key fetch is optional — keys are shown in the UI to copy or share, not saved as a file.
- Or Continue without signing in to use Firmware only.
- Choose where downloads are saved; clear folder with a confirmation that shows the file count.
- Open Settings anytime from the gear in the app bar.
Pick the GPS pack types you want. Building gps_uihh.bin uses temporary packs
in memory and only saves that file unless you also check those pack types.
Pick a watch (compact chooser). If a model has more than one hardware variant,
pick which one to check. Release notes appear when available. Downloads go to
your folder after confirmation; already-downloaded files are called out clearly.
Firmware checks query several Amazfit regions (RU, CN, PL, US) and merge
the OTA chains so region-staged rollouts show up as soon as any region has them.
- Choose a watch model (not a raw hardware channel). Lists are saved on this device and only update when you tap Update list.
- Filter and sort (category, author, price, starred, last updated, size, name).
Release dates come from the market
updated_atfield when Zepp provides one. - Tap an item for About / What’s new, download, star, Show QR
code (Zepp developer-mode install: original Amazfit package URL with
https://…→zpkd1://…for apps,watchface://…for watchfaces), and copy link. - Downloading stars the item by default; starred updates appear at the top after a list refresh.
- Update list is incremental: it re-reads the market list, but skips re-fetching details for unchanged free items that already have download info and About text.
- Refresh queries several Amazfit market regions (
RU,CN,PL,US, same set as Zepp Explorer) and merges the results, so region-gated apps/watchfaces still appear. With expert mode on, Apps and Watchfaces let you limit that query. It starts with those four countries, and you can add any other ISO 3166 country. Some features (e.g. Blood Pressure calibration) may still need an account registered in a supported country.
Setup |
Settings (signed in) |
GPS |
Firmware |
Firmware history |
Watchfaces |
Filter & sort |
Watchface detail |
Watchface QR |
Apps |
App detail |
App QR |
Refresh the PNGs with an attached Android device (copy .env.example to .env,
set ZEPP_EMAIL / ZEPP_PASSWORD):
./scripts/capture_screenshots.shUses flutter drive + --flavor screenshots + integration_test (clears
dev.otaj.zelp.screenshots first so the welcome setup screen is included). That
flavor installs as Zelp Screenshots beside a normal Zelp build. Pass
--keep-data to skip the clear. The integration test swaps credential fields /
stored account email to placeholders (****@****.*** and a fixed bullet string)
for any shot that would otherwise show a real login.
Custom Android launcher icon under assets/icon/.
- FVM with Flutter
stable(see.fvmrc) - Android SDK (for device / APK builds)
- uv (for ShellCheck via
uvxin pre-commit / CI) - pre-commit (for local lint, outdated-deps check, and Conventional Commits hooks)
fvm use
fvm flutter pub getAfter git worktree add, run ./scripts/setup_worktree.sh before any
Flutter/Dart/pre-commit work (see AGENTS.md). Prefer
./scripts/run_fvm.sh … over bare fvm so worktree GIT_DIR cannot
poison the shared SDK cache.
fvm flutter run --flavor prodScreenshot / side-by-side debug installs use --flavor screenshots
(dev.otaj.zelp.screenshots, launcher name “Zelp Screenshots”).
fvm dart format .
fvm flutter analyze
./scripts/analyze_kotlin.sh # detekt (same rules as `cd android && ./gradlew :app:analyze`)
uvx --from shellcheck-py==0.11.0.1 shellcheck scripts/*.shfvm flutter testTests are unit-only (no real network). HTTP and file I/O are mocked or use in-memory fixtures.
Install hooks once after clone (formats/analyzes on commit; ShellCheck on shell
scripts; checks the pubspec versionCode formula and outdated direct/dev pub
dependencies; Conventional Commits on commit-msg):
pre-commit install --hook-type pre-commit --hook-type commit-msgThere is no official pre-commit framework hook for
flutter pub outdated (Flutter/Dart do not ship one either). The community
dart_pre_commit package has an
outdated task, but it is a Dart CLI wired through custom git scripts—not a
drop-in pre-commit repo—and would overlap this project's FVM format/analyze
hooks. Zelp uses a small local hook instead:
scripts/check_pub_outdated.py runs fvm flutter pub outdated --json and
fails when a direct or dev dependency:
- is discontinued, retracted, or affected by a security advisory, or
- has an upgradable version within current pubspec constraints
(
current≠upgradable— usually fixed byfvm flutter pub upgrade).
Transitive-only gaps and constraint-blocked majors (newer resolvable/latest
but not upgradable without editing constraints, and sometimes only via
prereleases) do not fail the hook.
scripts/check_pubspec_version_code.sh fails unless pubspec.yaml is
X.Y.Z+N with N = 10000*major + 100*minor + patch. CI runs the same check.
Run against all files without committing:
pre-commit run --all-filesTagged GitHub Releases (vX.Y.Z, matching pubspec.yaml) are the reference
APKs F-Droid rebuilds against. Artifacts from pushes to master are snapshots
only and are not F-Droid reference builds.
Build one ABI (same recipe as CI and F-Droid). flutter must be on PATH
(after fvm use, export PATH="$PWD/.fvm/flutter_sdk/bin:$PATH"):
./scripts/fdroid_build.sh android-arm64
./scripts/check_no_google_libs.sh build/app/outputs/flutter-apk/app-arm64-v8a-prod-release.apkandroid-arm and android-x64 are the other two ABIs. pubspec.yaml stores
version as X.Y.Z+N with N = 10000*major + 100*minor + patch. ABI packing
(10 * N + ABI) lives only in android/app/build.gradle.kts so Flutter’s
--split-per-abi ABI * 1000 + N overlay is replaced.
check_no_google_libs.sh fails if proprietary Google Mobile Services libraries
(GMS / Firebase / ML Kit / Play) appear on the release classpath, or if an APK
still embeds Google Play’s encrypted Dependency metadata signing block. Release
builds opt out of that metadata in android/app/build.gradle.kts. After
flutter pub get, the build script strips the non-reproducible GNU build ID
from jni’s libdartjni.so (same Obtainium/F-Droid workaround).
.github/workflows/release.yml calls that script per ABI, runs the same
Google-library check, and names APKs {app}-{version}-{abi}.apk (for example
zelp-0.0.6-arm64-v8a.apk). Publishing a GitHub Release requires tag
vX.Y.Z to match pubspec and attaches those APKs. Pushing to master uses an
AUR-style git pkgver
and uploads each ABI APK as its own unzipped workflow artifact. CI and release
workflows read the Flutter version from .fvmrc.
Zelp is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.