Android Beacon Library - correct use of BluetoothMedic?

Question

I have some questions on the use of Bluetooth Medic, based on the following observations.

Because Bluetooth stops on one of my devices I have been looking at the BluetoothMedic to see whether it can help. I've looked at the debug messages and the source code. I get somewhat different results depending on whether I use enablePeriodicTests() or individually run runScanTest() and runTransmitterTest().

With enablePeriodicTests(), BluetoothTestJob.onStartJob() runs scan and transmitter tests every 15 minutes, apparently OK. If my beacon is transmitting, I get "Scan test succeeded" then "scan test complete" from the scan test, and if not I get "Timeout running scan test" then "scan test complete". After that the transmitter test runs and I get "Transmitter test succeeded" then "transmitter test complete" in all cases.

However I get different behaviour when I add buttons that execute the runScanTest() and runTransmitterTest() calls. In both cases the code enters the while() loops waiting for a non-null test result, and times out after 5s. Because the test results are null, the calls then return true (for the scan test) and false (for the transmitter test).

In the case of the scan test, the onScanResult() callback is never called if my beacon is not transmitting, but if the beacon is transmitting it is called 10-20 times (I see many "Scan test succeeded" messages) but only AFTER runScanTest() returns.

In the case of the transmitter test, the onStartSuccess() callback is fired once and I see a "Transmitter test succeeded" message but only AFTER the runTransmitterTest() returns.

Behaviour is the same for two devices (Android 7 and 8).

It would be good to have further documentation on these tests and how to use them.

Firstly, what do these tests do and what errors might they find?

Secondly - how should they be used? It looks like runScanTest() and runTransmitterTest() can't be called simply - do they need their own threads or something?

Finally, are they safe to use while the ranging and monitoring code is in action, or do they interfere?

Answer 1

The Android Beacon Library's BluetoothMedic is designed to detect symptoms of the Android bluetooth stack getting into a bad state, and then optionally cycle power to bluetooth to get out of it. The Medic looks for two OS-level error codes that come back from attempting to scan for a Bluetooth LE device or transmit a Bluetooth LE advertisement. These error codes are known to be associated with a bad state of the bluetooth stack from which recovery generally does not happen without intervention.

The simplest way to set it up is passively like this:

BluetoothMedic medic = BluetoothMedic.getInstance();
medic.enablePowerCycleOnFailures(context);

The above two lines will start the medic listening for any bluetooth errors that happen as a result of regular use of the library's functions (scanning and/or transmitting) by the enclosing app. If these are detected, it will cycle power in an attempt to recover.

This is generally safe to do, but cycling power can cause problems to other functions like classic bluetooth -- if the phone is using a bluetooth speaker when this happens, it will obviously disconnect. Bluetooth LE functions are less likely to be adversely affected by a power cycle, as the error condition in the bluetooth stack probably prevents the functions form working, anyway.

As you have seen, you can also set up the BluetoothMedic to run its own test periodically. This may be a a good idea if you app only periodically works with beacons, and you want to proactively recover from any error conditions before your app needs to use them. To set this up, call:

medic.enablePeriodicTests(context, BluetoothMedic.SCAN_TEST | BluetoothMedic.TRANSMIT_TEST);

You can also call the tests directly, but this is an advanced usage which is not the primary design. If you decide to do so, you should definitely do this on a new thread as they will otherwise block the UI thread until the test completes. This will cause problems like you describe.

If there are no BLE devices in the vicinity during the scan test, then the test "times out" and the results are inconclusive -- you don't know for sure that the bluetooth stack is in a good state. The debug line is an indication of that fact.