Contents
Server based pairing
New devices and older devices with updated firmware require server based pairing. This means, that you absolutely must use the original MiFit/Amazfit/Zepp app to make the initial pairing, retrieve the pairing key and then use this key to pair with Gadgetbridge. Currently, Mi Band 4, Mi Band 5, Mi Band 6, Amazfit Bip Lite and Amazfit GTR are known to be the first devices with this enabled from the beginning.
tldr; Entering the pairing key
- obtain the key
- after scanning, long press the device in the Discovery screen
- enter the key to the
Auth Key
Requirements
To set up your band/watch with Gadgetbridge you need Gadgetbridge > 0.35.0 and a unique key for your band. There are several ways to obtain the key.
Obtaining the unique key
On rooted phones
On rooted phone you may grab the key from MiFit/Amazfit database which means that you must:
- install MiFit (for Amazfit GTS install Amazfit)
- create an account
- pair the band/watch
Then, execute the following command in a root shell terminal:
for Mi Band 4/5/6, Amazfit Bip Lite and Amazfit GTR
sqlite3 /data/data/com.xiaomi.hm.health/databases/origin_db_[YOURDBNAMEHERE] "select AUTHKEY from DEVICE"
for Amazfit GTS, Amazfit T-Rex and Amazfit T-Rex Pro
sqlite3 /data/data/com.huami.watch.hmwatchmanager/databases/origin_db_[YOURDBNAMEHERE] "select AUTHKEY from DEVICE"
NOTICE: Every time you hard reset the band/watch, the Bluetooth MAC Address will be changed and you must grab a new key! Also, anytime you unpair your band/watch from MiFit/Amazfit/Zepp the pairing key will be invalidated and you must make new pairing in MiFit/Amazfit/Zepp app.
IMPORTANT: Enter your key prefixed with 0x ( eg. if your key is fedcba01234567890fedcba012345678 enter 0xfedcba01234567890fedcba012345678). Do not press the Enter key. Make sure 0x is really 0x , some keyboards might use different symbols.
On non-rooted phones
Using a python script with your account details
https://github.com/argrento/huami-token
Please see the README for a detailed desctiption on the procedure
Using the huafetcher app with your account details
https://codeberg.org/vanous/huafetcher Please see the README for a detailed desctiption on the procedure
This allows you to run the huami-token script right on your phone, so that you can easily copy and paste the key.
freemyband
On a non rooted phone you may consider using https://www.freemyband.com/ NOTE that the procedure described there is not encouraged or supported by the Gadgetbridge developers and the devs have no information on that app and whether it is safe to use
Preparations
- do not unpair the band/watch from MiFit/Amazfit/Zepp app
- kill or uninstall the MiFit/Amazfit/Zepp app
- ensure GPS/location services are enabled
- unpair the band/watch from your phone's bluetooth (as per below)
You are allowing "location services", which include GPS, because on Android, Bluetooth discovery is considered to be able to reveal a location. You can disable "location services" access for Gadgetbridge after pairing your device.
If you already connected your band/watch with your phone, remove it from Android Bluetooth settings. The procedure depends on which ROM is installed on your smartphone. Here is an example for LineageOS 16 (Android 9):
Setup
1. Once you own your unique key for your band/watch and preparations are done, start Gadgetbridge, go to the home screen and tap "(+)":
2. Allow access to location services (required since Android 6) and Bluetooth. Start discovery:
You are allowing "location services", which include GPS, because on Android, Bluetooth discovery is considered to be able to reveal a location. You can disable "location services" access for Gadgetbridge after pairing your device.
3. After a while, your band/watch should appear. Long press on "Device name", for example "Mi Smart Band 4":
4. Scroll down, tap "Auth Key" and enter your own key. Do NOT hit Enter/Return key.
IMPORTANT: Enter your key prefixed with 0x ( eg. if your key is fedcba01234567890fedcba012345678 enter 0xfedcba01234567890fedcba012345678). Do not press the Enter key. Make sure 0x is really 0x , some keyboards might use different symbols.
5. Go back and tap on "Device name", for example "Mi Smart Band 4". Pairing should start now:
6. After successful connection you will see your band/watch on the home screen.
Congratulations, you did it!
Troubleshooting
If you encounter problems with Bluetooth discovery or pairing process, try the following steps:
- Make sure MiFit/Amazfit/Zepp is not running
- Make sure you did not unpair your band/watch from MiFit/Amazfit/Zepp
- Make sure to add 0x in from your key when pasting/typing it to Gadgetbridge
- Make sure 0x is really 0x , some keyboards might use different symbols, see here.
- Do not press Enter/Return key when typing the key
- Make sure that band/watch is unpaired from the phone's Bluetooth
- Toggle Bluetooth OFF and ON
- Reboot your smartphone
- Reboot your band/watch (More-> Settings-> Reboot)
General
- Home
- ReadMe
- Configuration
- Notifications
- ChangeLog
- Widget
- Weather
- Data Backup
- Pairing
- Find phone
- Permissions Explained
Sports/Activities
- Sports Activities Workouts
- Activity Sessions List
- Activity and Sleep Charts
- Heartrate measurement
- GPS recording of sports activities
- Integrating Sports Tracking apps with Gadgetbridge Sports Activities/Workouts
Smart Device Related
Wireless Earbuds
Full list of supported devices
Development
- How to Release
- Developer Documentation
- BT Protocol Reverse Engineering
- Support for a new Device
- New Device Tutorial
- Translating Gadgetbridge
Feature Discussion
FAQ
