Troubleshooting for Customer Service

This page is meant to be a resource for your Customer Service team (or non-app-developers in general) when trying to remotely troubleshoot issues that your users may be having with your app and/or product. Some of these are "make sure it's plugged in"-type of steps, but they bear listing for when you've tried absolutely everything else. If you are an application developer please also see Troubleshooting for Developers for additional measures you may take. Anyway, in rough order of effectiveness...

• Restarting the phone is usually the quickest and most effective option and has to be done occasionally no matter what.
• Restarting the peripheral hardware can also be a good step to perform regularly. Factory reset and take out batteries for a second or two to be sure.
• Restarting Bluetooth fixes some issues as well. How this is done varies per phone/OS, but basically you open the native Settings app on the phone, go to the Bluetooth section, turn it off, then turn it back on. On lots of phones you can swipe down from the top of the screen for a shortcut icon. It's suggested that your app have a big Reset button available as well so it's easier to direct your users and they just have to click one thing. If a developer is reading this, the Reset button should be tied to BleManager.reset().
• Make sure the device you or your user is trying to connect to is powered on and actually in an advertising/connectable mode. Often this means some kind of blinking light on the hardware.
• Make sure the batteries in the peripheral are fresh.
• Make sure the phone has a decent charge. In low battery conditions, like below 5%, Bluetooth might get throttled by the operating system.
• Make sure the peripheral you or your user think is being connected to is actually the correct peripheral. There may be one peripheral A right in front of you and another B on the other side of the building that's still in range but you're trying to connect to it through a wall and it fails when you think you're trying to connect to peripheral A. Especially if you're in a development environment with a bunch of other bluetooth devices around it can get confusing. Good practice is to have the MAC address both on a small sticky somewhere on the peripheral and also displayed in your app's UI (debug UI if need be).
• Stop all other bluetooth apps on the phone. The radio can get overloaded pretty easily.
• Make sure the phone and peripheral are physically close together. Try to connect in low interference areas, for example go outside away from lots of metal and other electronic devices.
• Make sure the phone is being held lightly in hand. We have run into phones that have the connection strength weaken significantly when laid on a table, as if you suddenly walked 30 feet away.
• Make sure the peripheral isn’t connected to another phone already. By default both SweetBlue and Core Bluetooth (iOS Bluetooth framework) are pretty aggressive about staying connected and reconnecting so you have to make sure other apps on other phones aren't stealing your thunder.
• Make sure you or your user is on the latest firmware version. Your firmware developer may have tweaked something in their latest release that improves Bluetooth performance.
• You can also have end-users try reinstalling the app from the Play Store. A simple reinstall itself probably won't help, but it may be that your user is on an old version of your app, and hence an old version of SweetBlue. So this step serves as a sanity check to make sure everything is up-to-date.
• Anecdotal evidence suggests that turning off WiFi can help Bluetooth stability. This hasn't been observed by us directly but you may try it and, if it helps, add custom logic to your app to manage WiFi state at the user's consent. If you have unequivocally observed WiFi hurting BLE stability, please let us know. It would bolster support for implementing this feature.
• Try clearing Bluetooth cache. This varies by device, but go into the system settings, then application manager, then show all apps (usually by swiping right all the way). You should see either "Bluetooth", or "Bluetooth Share". Tap on this, then tap on Clear Data.
• As a sanity check, try to connect to the peripheral using another phone or tablet. Even try on an iOS device. LightBlue is a good utility app. This just helps pare down the possibilities of what could be wrong. If your peripheral isn't even connecting to an iOS device then you can be reasonably sure it's an environmental or peripheral issue.
• FINALLY, the nuclear option, and my personal favorite. Sometimes the Bluetooth stack just quits and stops working completely. You can try all of the above steps until the cows come home and nothing will work. In these cases we suggest a factory reset of the phone. Assuming things were working at some point in the past, this almost always works.