Table of Contents
- Server based pairing
- tldr; Entering the pairing key
- Requirements
- Obtaining the unique key
- On rooted phones
- for Mi Band 4/5/6, Amazfit Bip Lite and Amazfit GTR
- for Amazfit GTS, Amazfit T-Rex and Amazfit T-Rex Pro
- for Mi Band 6 with Mi Fitness (Xiaomi Wear) (com.xiaomi.wearable)
- On non-rooted phones
- Preparations for adding to Gadgetbridge
- Adding to Gadgetbridge
- 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:
- 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.
- 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.
- Troubleshooting
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, Mi Band 7, Amazfit Bip Lite, Amazfit GTR (and more as time goes on) are known to be the first devices with this enabled from the beginning.
tldr; Entering the pairing key
- pair the band in the official app
- obtain the key
- kill or uninstall the MiFit/Amazfit/Zepp app
- unpair the band from Android pairing
- 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 to get the unique key for your band. It is stored on Huami servers or in original Mifit/Zepp apps database. There are several ways to obtain the key.
Obtaining the unique key
- The key is available either from Mifit/Zepp internal data storage or from their online servers. You must not unpair the watch from their original app as this would erase the key.
On rooted phones
On rooted phone you may grab the key from MiFit/Amazfit database which means that you must:
- install Zepp Life (for Amazfit GTS install Zepp)
- 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"
for Mi Band 6 with Mi Fitness (Xiaomi Wear) (com.xiaomi.wearable)
sqlite3 /data/data/com.xiaomi.wearable/databases/device_db "select detail from device"
Within the contained JSON, the attribute auth_key
contains the key.
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 zero (0
) and lowercase X (x
) since some keyboards might use different symbols.
On non-rooted phones
Using a python script with your account details
https://codeberg.org/argrento/huami-token
Please see the README for a detailed description on the procedure.
If using a watch/band from Xiaomi, this method may not work at the moment.
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. If using a watch/band from Xiaomi, this method may not work at the moment.
From Mi Fitness logs
If your device is supported by the Mi Fitness app, there are reports that it prints the authKey in the logs (#2991), which are available in the phone's internal storage. Accessing the logs does not require root and the path to the relevant file is /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log
.
The key can be printed with the following two commands, assuming you've enabled USB debugging on your mobile device
adb shell
grep -E "authKey=[a-z0-9]*," /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log | awk -F ", " '{print $17}' | grep authKey | tail -1 | awk -F "=" '{print $2}'
It seems that in the latest versions of Mi Fitness (+3.20.2i) the field authKey
is null so you have two more options with the fields token
or encryptKey
adb shell
grep -E "encryptKey=[a-z0-9]*," /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log | awk -F ", " '{print $12}' | grep encryptKey | tail -1 | awk -F "=" '{print $2}'
or
adb shell
grep -E "token=[a-z0-9]*," /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log | awk -F ", " '{print $11}' | grep token | tail -1 | awk -F "=" '{print $2}'
This process can be done within Termux in the same device if you can access to /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log
. It seems that in custom ROMs is possible but not in some stock ROMs like in the Pixel's. If you are able to access it, you can copy the log to a more comfortable location and run a command like the followings:
adb shell
grep -E "encryptKey=[a-z0-9]*," ~/downloads/XiaomiFit.device.log | awk -F ", " '{print $12}' | grep encryptKey | tail -1 | awk -F "=" '{print $2}'
or
grep -E "token=[a-z0-9]*," ~/downloads/XiaomiFit.device.log | awk -F ", " '{print $11}' | grep token | tail -1 | awk -F "=" '{print $2}'
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 for adding to Gadgetbridge
- 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 (not from the app), 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):
Adding to Gadgetbridge
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 zero (0
) then lowercase X (x
) since 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 to have first paired in MiFit/Amazfit/Zepp app
- 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 zero (0
) then lowercase X (x
) since 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
- FAQ
- ReadMe
- Configuration
- Notifications
- ChangeLog
- Widget
- Weather
- Data Backup
- Pairing
- Find phone
- Music info
- Permissions Explained
- Firmware Update
- Automation via Intents
Sports/Activities
- Sports Activities Workouts
- Activity Sessions List
- Activity and Sleep Charts
- Heartrate measurement
- Integrating Sports Tracking apps with Gadgetbridge Sports Activities/Workouts
Smart Device Related
- Bangle.js
- Casio devices
- FitPro
- Fossil Hybrid HR
- Garmin devices
- HPlus
- Huami devices
- Amazfit Active
- Amazfit Active Edge
- Amazfit Balance
- Amazfit Band 5
- Amazfit Band 7
- Amazfit Bip
- Amazfit Bip Lite
- Amazfit Bip S
- Amazfit Bip U
- Amazfit Bip 3 Pro
- Amazfit Bip 5
- Amazfit Cheetah
- Amazfit Cheetah Pro
- Amazfit Cor
- Amazfit Cor 2
- Amazfit Falcon
- Amazfit GTR
- Amazfit GTR 3
- Amazfit GTR 3 Pro
- Amazfit GTR 4
- Amazfit GTR Mini
- Amazfit GTS
- Amazfit GTS 3
- Amazfit GTS 4
- Amazfit GTS 4 Mini
- Amazfit Neo
- Amazfit T-Rex
- Amazfit T-Rex 2
- Amazfit T-Rex Ultra
- Mi Band 1
- Mi Band 2
- Mi Band 3
- Mi Band 4
- Mi Band 5
- Mi Band 6
- Mi Band 7
- MyKronoz ZeTime
- Pebble
- PineTime
- Sony Wena 3
- SMA
- WithingsSteel
Wireless Earbuds
Others
- iTag Keyring trackers
- Nut Keyring trackers
- UM25 USB Voltage meter
- VESC BLDC controller VESC
- Flipper Zero Multi-tool Device for Geeks
- Roidmi Roidmi/Mojietu FM Trans.
- Vibratissimo Private toy
- Shell Racing Toy RC cars
- Femometer Vinca II
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
- OpenTracks-API
- Intent-API
Feature Discussion
FAQ