Pairing¶
"Pairing" means establishing a connection between two Bluetooth devices. It can be a complex process and the type of pairing can determine what possibilities are given to the connected device during day-to-day operation.
Before you add the device to Gadgetbridge, it is recommended to unpair the gadget from your phone's Bluetooth and uninstall the vendor's app. If your gadget supports Bluetooth pairing then enable it, so when you add your gadget in Gadgetbridge, it will also be paired in the Android Bluetooth settings of your phone.
Adding a new device¶
To connect a new gadget, press Add on the bottom-right corner of the home screen in Gadgetbridge. Then you will be presented with the "Device discovery" page.
Press on "Start discovery" to search for gadgets nearby, and wait until it finds your gadget.
Find your device from the list and try to add it, then depending on your situation, continue reading with one:
Troubleshooting¶
In the Discovery and Paring options (available from Device discovery screen as well as from Settings) there are a few options that might be helpful for pairing.
If your scan never finishes and seems to cause Gadgetbridge to freeze and become non-responsive, check the "Disable new BLE scanning". You can also re-try the pairing in a place with less Bluetooth traffic, and placing your gadget more closer to your phone.
Authentication key¶
This section isn't for you if you are not asked for a key
You should follow this section only if Gadgetbridge explicitly asks for a key when pairing your gadget. (It shows as KEY REQUIRED on the discovery screen.)
Depending on which gadget you use, you might be asked for an "authentication key" instead. These gadgets communicate with an encrypted protocol, thus requiring both the gadget and Gadgetbridge to know a key for encrypting and decrypting the communication.
It is in most of these cases simply impossible to add your device to Gadgetbridge unless you provide a valid authentication key. Some devices (for example Fossil) can still be connected but support less features when no key or an invalid key was provided.
As we don't know how proprietary gadgets work internally (proprietary firmware, obviously), we can't simply create the key for you, so you will usually need to extract it by pairing your gadget first with its official (vendor) application or a third-party app created specifically for this purpose.
After you successfully paired your gadget on the vendor app, you can use various methods to obtain the authentication key from the vendor's servers, then later configure it in Gadgetbridge.
To learn how to obtain authentication key of your gadget, see manufacturer-specific instructions below.
Includes gadgets manufactured by Huami (uses Zepp Life / Zepp / Mi Fitness / Xiaomi Wear app).
Pairing unsupported gadgets¶
This section isn't for you if you are not advised to do that
Do not perform pairing unsupported gadgets without being advised.
If your gadget is not supported by Gadgetbridge, but you have a gadget that is similar to one that is supported by Gadgetbridge, you can try pairing it with Gadgetbridge to see if it works as-is and let us know.
Do note that if the gadget requires special pairing key (like Huami gadgets), you must obtain it before pairing, see above.
Other requirements from above are still valid, if your gadget's official app is running, stop or uninstall it and unpair the gadget from Bluetooth menu, (if it is already paired).
Bluetooth pairing
Adding as device as unsupported does not pair it at Bluetooth level. For some devices you might need to pair manually in Android Bluetooth settings before executing the following steps.
Press and hold on an unsupported gadget to show options for a scanned device.
Then pick Add test device. This option won't be shown for gadgets that are already bonded to Gadgetbridge.
Now you can choose like which gadget you want Gadgetbridge to handle your device.
You should choose the gadget which is the most similar to yours (model name, operation logic and etc.) for the best compatibility.
If it works, make sure to report it so it can be enabled for everyone in next releases!
Finishing up¶
Congratulations, you now have your gadget added to Gadgetbridge! You can stop using the official app for your gadget at this point! (and you should, to avoid running into any synchronization problems).
If your gadget required an authentication key, factory resetting your gadget or unlinking it from the vendor app most likely will rotate the required key, so you will need to start over again to obtain the key, so as always, just uninstalling or disabling the vendor app is enough.
To learn more about what Gadgetbridge offers for your gadget, head over to Features section.