Huami/Xiaomi server pairing¶

New Amazfit and Xiaomi gadgets, as well as older gadgets with updated firmware, require server-based pairing. This means you must use the correct official app to perform the initial pairing, which pushes the authentication token to the backend. After pairing, you can retrieve the pairing key and use it to pair with Gadgetbridge. On some older devices, if the auth token is not present in the backend, you may need to try one of the other supported apps.

The naming of these apps can be confusing. For a detailed overview, see the App naming overview section below.

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.

App naming overview¶

It has been reported in that for some earlier Mi Bands the "Zepp Life" app won't push the auth token to backend however it does work with the "Zepp" app even though those devices are not officially supported in that app.

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 and already got your numeric account ID, skip to the "Entering key" section.

Entering key

But for gadgets requiring a key, choose only one method from below to learn how to obtain your own encryption key:

On a computer (easiest)¶

When you log into your Zepp account online, your account token gets stored in the browser, which then can be used to retrieve your gadgets.

• Sign into Watchface Maker with the same account your gadget is currently linked to.
• Press Ctrl + Shift + I to open browser console, or if it didn't work, right-click anywhere in the page and choose "Inspect" option, and then open "Console" tab by yourself.
• Copy and paste this JavaScript snippet and hit Enter to execute it in the webpage, and allow for pop-ups if asked.

(()=>{try{
    const zeppCookie = document.cookie.match("hm-user-login-info=(.*?);")?.[1]?.replaceAll("%2C", ",");
    if (!zeppCookie) { throw new Error("Account was not found, make sure you've currently visiting and signed in https://watchface.zepp.com/"); }
    const userCredentials = JSON.parse(decodeURI(zeppCookie))["token_info"];
    console.log("Your user credentials is:");
    console.log(userCredentials);
    const userId = userCredentials["user_id"];
    console.log("User ID:", userId);
    fetch(`https://api-mifit-us3.zepp.com/users/${userId}/devices` + "?" + new URLSearchParams({
        "appid": "2882303761517383915", "channel": "play", "enableMultiDevice": "true", "device_type": "android_phone",
        "cv": "151262_8.7.1-play", "device": "android_33", "v": "2.0", "lang": "en_US", "country": "US"
    }), { method: "GET", headers: {
        "User-Agent": "Zepp/8.5.3-play (2201116SG; Android 12; Density/2.525)",
        "apptoken": userCredentials["app_token"],
        "channel": "play", "appname": "com.huami.midong", "appplatform": "android_phone",
        "cv": "151262_8.7.1-play", "v": "2.0", "lang": "en_US", "country": "US",
        "hm-privacy-diagnostics": "false", "hm-privacy-ceip": "true"
    }}).then((x) => x.json()).then((d) => {
        const linkedDevices = d["items"];
        if (!linkedDevices.length) { throw new Error("There is no device found linked to this account.") }
        const devicesData = new Blob([JSON.stringify(linkedDevices)], { type: "application/json" });
        if (!window.open(URL.createObjectURL(devicesData))) { console.log("Listing linked devices below:"); console.log(linkedDevices); }
    })
}catch (e){alert(`An error is detected.\n${e}\n\nIf this script doesn't work, make sure to report this issue and try another browser or other methods.`)}})();

Then it should print another message to the console or pop up a new tab containing the data returned from Zepp servers. From there, you can find your hexadecimal auth_key value located inside additionalInfo object.

additionalInfo: {"sn":"12345/ABCDEFGHIJKLMN","bind_timezone":12,"auth_key":"b0f9c10d025c6b7333bf21f3a701e5fc","productId":"103","productVersion":"259","hardwareVersion":"0.91.18.5","brand type":-1,"lastDevicePAIDataSyncTime":1000000000000}

So in this case, the auth key for this device would be b0f9c10d025c6b7333bf21f3a701e5fc.

After obtaining your key, keep it and jump to the "Entering key" section to continue.

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.

After obtaining your key, keep it and jump to the "Entering key" section to continue.

Entering key

On non-rooted phones¶

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 / Mi Health / Xiaomi Wear¶

This section applies to the following apps:

• Mi Fitness - com.xiaomi.wearable
• Mi Health - com.mi.health
• Xiaomi Wear - com.xiaomi.wearable

If your device is supported by one of these apps, there are reports that they print the auth key 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/<package_name>/files/log/<log_file>, where:

• The package name depends on the app you have installed (see above)
• The log file can be different for each app version (XiaomiFit.device.log, XiaomiFit.main.log Transfer.device.log, etc)

The key can be displayed in multiple fields depending on the app. The following fields are known to contain the auth key in the logs:

• encryptKey
• token
• authKey
• huamiAuthKey

You can access this file in multiple ways:

• adb shell - If you have enabled USB debugging on your mobile device, you can obtain the key from logs on your device with adb shell
• mtp - you should be able to connect the phone to a computer and access the folder from the internal storage, using the computer's file manager
• termux - You can also use Termux on the device, if you can access /sdcard/Android/data/com.xiaomi.wearable/files/log/XiaomiFit.device.log. It seems that some custom ROMs allow it, but not all stock ROMs (for example, the Pixel's does not allow it).

The following command can be used to search for all possible fields, across all possible apps and log files:

grep -Eo '(encryptKey|token|authKey|huamiAuthKey)[":= ]+[[:xdigit:]]{32}' /sdcard/Android/data/{com.xiaomi.wearable,com.mi.health}/files/log/*.log | grep -oE '[[:xdigit:]]{32}' | sort | uniq

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

After obtaining your key, keep it and jump to the "Entering key" section to continue.

Entering key

Entering 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 value you've obtained previously.

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" menu, and click on "Auth key" to enter the key.

Enter your key prefixed with 0x ( e.g. 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).