Cross-platform companion app for the ZSWatch open-source smartwatch
⚠️ Experimental / Work in Progress — This app is under active development. Features may be incomplete, and APIs may change. Contributions and bug reports are welcome!
A Flutter companion app that connects to ZSWatch over BLE using the Gadgetbridge/BangleJS JSON protocol. It replaces Gadgetbridge on Android and provides features not available through standard iOS ANCS/AMS services.
| Feature | Android | iOS |
|---|---|---|
| BLE connection & auto-reconnect | ✅ | ✅ |
| Notification forwarding | ✅ | — (uses ANCS) |
| Music control | ✅ | — (uses AMS) |
| Firmware update (DFU) | ✅ | ✅ |
| LVGL resource upload | ✅ | ✅ |
| Health data (steps, heart rate) | ✅ | ✅ |
| Battery & connection analytics | ✅ | ✅ |
| GPS location relay | ✅ | ✅ |
| Weather sync | ✅ | ✅ |
| HTTP proxy for watch | ✅ | ✅ |
| Developer tools (logs, sensors) | ✅ | ✅ |
| Background BLE connection | ✅ | ✅ |
On iOS, notification forwarding and media control are handled natively by the watch using Apple ANCS/AMS services — no app involvement needed.
Download the latest prebuilt APK from GitHub Releases.
No prebuilt IPA is available. See Building from Source to build and install on your device.
- Flutter SDK 3.10+ (stable channel)
- Android Studio (for Android builds) or Xcode 15+ (for iOS, macOS only)
Verify your setup:
flutter doctor -v# Clone with submodules (includes MCUmgr fork)
git clone --recurse-submodules https://github.com/ZSWatch/ZSWatch-App.git
# Or if already cloned without submodules:
# git submodule update --init
cd ZSWatch-App/zswatch_app
# Install dependencies
flutter pub get
# Generate code (Drift database, Riverpod)
dart run build_runner build --delete-conflicting-outputs# Debug (connected device)
flutter run
# Release APK
flutter build apk --release
# Output: build/app/outputs/flutter-apk/app-release.apk# Install CocoaPods (first time)
cd ios && pod install && cd ..
# Debug (connected device or simulator)
flutter run
# Release
flutter build ios --releaseNote: iOS release builds require an Apple Developer account and signing configuration in Xcode.
ZSWatch-App/
├── zswatch_app/ # Flutter application
│ ├── lib/
│ │ ├── core/ # Constants, theme, utilities
│ │ ├── data/ # Database (Drift/SQLite), models, repositories
│ │ ├── services/ # BLE, protocol, DFU, notifications, media, health
│ │ ├── providers/ # Riverpod state management
│ │ └── ui/ # Screens and widgets
│ ├── android/ # Android platform code (Kotlin)
│ ├── ios/ # iOS platform code
│ └── test/ # Tests
├── specs/ # Feature specifications
└── LICENSE
- State management: Riverpod — providers in
providers/, one per domain - Database: Drift (SQLite) with code generation
- BLE protocol: JSON-over-NUS (Nordic UART Service), Gadgetbridge/BangleJS format
- DFU: MCUmgr/SMP protocol via mcumgr_flutter
- Navigation: go_router
After modifying Drift schemas or Riverpod annotations:
dart run build_runner build --delete-conflicting-outputsflutter analyze
dart format .flutter test- ZSWatch Firmware — The smartwatch firmware (Zephyr RTOS)
- ZSWatch Docs — Documentation and getting started guides
- mcumgr_flutter fork — MCUmgr plugin for DFU
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes and ensure
flutter analyzepasses - Run tests:
flutter test - Commit and push:
git push origin feature/my-feature - Open a Pull Request
This project is licensed under the MIT License — see LICENSE for details.
- GitHub Issues — Bug reports and feature requests
- Discord — Community chat
- zswatch.dev — Documentation