Huami/Xiaomi server pairing¶

New Amazfit and Xiaomi gadgets and older gadgets with updated firmware require server based pairing. This means, that you absolutely must use the original Mi Fit / Amazfit / Zepp app to make the initial pairing, retrieve the pairing key and then use this key to pair with Gadgetbridge.

The authentication key is stored on Huami servers or in the original Mi Fit / Mi Fitness / Xiaomi Wear / Zepp app's database. There are several ways to obtain the key.

Older devices without encryption¶

Some old Xiaomi devices use the Xiaomi account ID as authentication key. For these, you can just use the numeric account ID, as seen in the official app next to the account name. These devices are:

• Mi Watch Color Sport
• Mi Watch Lite

If you have one of these devices, continue to the next section.

Entering key

On rooted phones¶

Install Zepp Life or Zepp vendor app depending which app supports your gadget. Then create your account and pair your gadget. After that, quit the vendor app (don't uninstall it yet), and run the appropriate command for your gadget in a root shell. (e.g. Termux for on-device, or ADB for on-computer)

Replace [YOURDBNAMEHERE] with the name of the database file of vendor app. You can use a file explorer to get the name of the database file name.

sqlite3 /data/data/com.xiaomi.hm.health/databases/origin_db_[YOURDBNAMEHERE] "select AUTHKEY from DEVICE"

sqlite3 /data/data/com.huami.watch.hmwatchmanager/databases/origin_db_[YOURDBNAMEHERE] "select AUTHKEY from DEVICE"

sqlite3 /data/data/com.xiaomi.wearable/databases/device_db "select detail from device"

Within the obtained JSON, the attribute auth_key contains the key. Note that the key name might be different for some devices not manufactured by Huami, such as encrypt_key as explained in comment on issue #3146.

Now, keep that key in your clipboard and jump to the next section to continue.

Entering key

On non-rooted phones¶

This section only applies to devices manufactured by Huami.

Huami token¶

This section only applies to devices manufactured by Huami.

The full process is not covered here, but you can try these projects to obtain the authentication key from Huami servers by logging into your Xiaomi or Amazfit account.

• huafetcher
• huami-token

Mi Fitness / Xiaomi Wear¶

If your device is supported by the Mi Fitness app, there are reports that it prints the authKey in the logs ( issue #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

Assuming you've enabled USB debugging on your mobile device, you can obtain the key from logs on your device with 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:

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}'

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 on 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:

grep -E "encryptKey=[a-z0-9]*," ~/downloads/XiaomiFit.device.log | awk -F ", " '{print $12}' | grep encryptKey | tail -1 | awk -F "=" '{print $2}'

grep -E "token=[a-z0-9]*," ~/downloads/XiaomiFit.device.log | awk -F ", " '{print $11}' | grep token | tail -1 | awk -F "=" '{print $2}'

There is a report that getting the authentication key fails in some cases. See this issue for more details.

Entering key

Entering key¶

If you are currently on the "Device discovery" page, long press on the device name and click on "Auth key" to enter the key.

If you added the gadget already, touch the icon under your gadget name (while on the home screen) to go to the "Device specific settings", and click on "Auth key" to enter the key.

Enter your key prefixed with 0x ( eg. if your key is 46fec12c98382dgf enter 0x46fec12c98382dgf). Don't press Enter/Return key on the keyboard and make sure 0x is really 0x before pressing "OK", as some keyboards might use different symbols.

After entering your authentication key, try connecting to your gadget to see if it is working.

If everything works alright, congratulations! Now you can uninstall the vendor app of your gadget and start using Gadgetbridge.

Configuring your gadget

Troubleshooting¶

If you encounter problems with Bluetooth discovery or pairing process, try the following steps:

• Make sure to have first paired in Mi Fit / Amazfit / Zepp vendor app.
• Make sure these vendor apps is not running at the moment.
• Make sure you did not unpair your gadget from vendor app.
• Make sure to add 0x in from your key when pasting/typing it to Gadgetbridge.
• Make sure 0x is really 0 (zero) and x (lowercase X), since some keyboards might use different symbols, see comment on issue #1775.
• Do not press Enter/Return key when typing the key, which may cause adding a new line.
• Make sure that gadget is unpaired from the phone's Bluetooth.
• Toggle Bluetooth OFF and ON.
• Reboot your smartphone.
• Reboot your gadget (More → Settings → Reboot).