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.
Usage of non-free (as-in freedom) software ahead
Unfortunately, these steps will take you outside of Gadgetbridge and require you to create an account with your gadget's vendor's website and/or download a proprietary app.
As the authentication keys are stored on vendor servers, there is no way to generate these keys locally at the moment.
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.
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.
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.
On non-rooted phones¶
Huami token¶
This section only applies to devices manufactured by Huami.
Supported apps
Some devices like the Mi Band 7 are supported by multiple apps. In order for the following projects to get the auth key, you need to pair them with the Zepp / Zepp Life app.
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.
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 -Eo "authKey=[[:xdigit:]]+" /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log | tail -1 | cut -d= -f2
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:
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:
Multiple keys in the log file
There can be multiple keys in the log file, so make sure to use the last one that shows up, closest to the end of te file.
There is a report that getting the authentication key fails in some cases. See this issue for more details.
Entering key¶
Don't unpair from vendor app
Anytime you unpair your gadget from Mi Fit / Amazfit / Zepp the pairing key will be invalidated and you must follow these steps again to grab the newly generated key. Just uninstall the vendor app.
Hard resetting the gadget invalidates the key
Every time you hard reset the gadget, the Bluetooth MAC address will be changed and you must grab a new key.
Before entering the key and attempting to connect, you should remove all permissions from the vendor app or uninstall it, since it can conflict with Gadgetbridge. Do not unpair the watch from the vendor app, as that will invalidate the auth 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", open the "Authentication" section, 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.
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
0xin from your key when pasting/typing it to Gadgetbridge. - Make sure
0xis really0(zero) andx(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).