Bluetooth and Other Devices

The SDK supports external devices such as Bluetooth through an optional subsystem.

See also:

Adding Device Support to the App

To add device support to the app, include one or more device libraries in your build file

implementation 'com.drivesync.android:devices-wedge:+'

At the start of app initialization, initialize the device manager by specifying the supported device(s) and providing a callback for optional actions when a known device is detected in background.

// Initialize devices
DsDeviceManager.initialize(
    application, 
    listOf(HeadsetProfileProvider(), WedgeProvider(Regex("^IMS-.*"))), 
    object: DsDeviceEventListener {
        override fun onNotify(dsDevice: DsDevice, value: Any?) {
            onBackgroundNotify(application, dsDevice)
        }
     })

Detecting Devices

The SDK identifies a "known" device by its unique MAC address (Bluetooth) or some other identifier. It is up to the application to get the user to confirm which devices are of interest and/or associated with their vehicles.

To scan for devices, use the device manager's startDeviceDetection() and stopDeviceDetection() methods.

Interactive mode

In discovery (interactive) mode the scan detects all nearby devices of the type(s) specified in DsDeviceManager.initialize(). This mode only works when your app is active and on screen.

DsDeviceManager.startDeviceDetection(context, null, SCAN_DURATION, scanListener)

Android limits the duration and frequency of scans. You should specify a reasonable SCAN_DURATION (say 20 seconds) and provide a button so the user can restart the scan. During the scan devices are reported as they are detected using the listener's onDeviceUpdated(); the same device may be reported more than once. Once the scan is complete the onScanFinished() method is called so you can update the UI.

Verification mode

Android does not allow apps to scan for unknown devices when the app is not active and on screen. However, whenever the app is in foreground (either interactive or running a Foreground Service) then you scan for known devices.

DsDeviceManager.startDeviceDetection(context, devices, SCAN_DURATION, scanListener)

In this case you specify a list of known devices and the scan listener reports any that are detected. The onScanFinished() method is called once the scan is complete.

Background mode

In most cases Android can detect the presence of specific devices from the background, even when the app isn't running. This means you can use proximity to a specific device to wake the app and/or perform a particular operation. For example, you can use proximity to a specific wedge (which is mounted in your car) to start the trip recorder.

Background detection may require special permissions and may have significant latency depending on your phone's version and state.

DsDeviceManager.enableBackgroundMonitor(context)
DsDeviceManager.disableBackgroundMonitor(context)

If you configured the trip manager to use TripDetector.DEVICE then the trip manager will automatically enable and disable the background monitor and your app should not do this itself.

Note that the background mode is different from the scan mode. Detection may happen when the app isn't running, so

• The SDK only reports devices in the saved list of devices

• Detection events are reported through the callback listener specified in DsDeviceManager.initialize().

Device Storage

The list of known devices is managed through the device manager:

DsDeviceManager.loadDevices()
DsDeviceManager.saveDevices(devices)

This device list is saved on each phone and not the DriveSync server. This is because Android obfuscates the hardware identity of Bluetooth and network devices so they cannot be tracked from phone to phone. This means, for example, that the same wedge will always have the same MAC address on the same phone, but will appear to have a different address when detected from different phones.

Limitations and Known Issues

The SDK currently supports a limited set of Bluetooth device providers.

• BluetoothPairedAclProvider: This is the only type of device supported in previous versions of the SDK. Detects all paired devices; reports data connection from background with essentially no latency. No special permissions are required.

• HeadsetProfileProvider, AudioProfileProvider: Scan reports Bluetooth headset (hands-free) and audio devices that are currently connected - users need to be in the vehicle when scanning. Reports connection from background with essentially no latency. No special permissions are required.

• BleDeviceProvider: Scan reports nearby, discoverable BLE devices and requires LOCATION permission. Background detection requires BACKGROUND_LOCATION permission and, depending on Android version, phone make, and phone state, may take up to 15 minutes before the device is detected.

• WedgeProvider: Scan reports nearby, discoverable wedge devices. The wedge provider's constructor uses a regular expression to match the device name before reporting it, e.g. "^IMS-.*" detects only wedges whose name starts with "IMS-". Scan requires LOCATION permission; background detection requires BACKGROUND_LOCATION permission and, depending on Android version, phone make, and phone state, may take up to 15 minutes before the device is detected.

There is currently no support for Beacon devices unless they are discoverable as standard BLE devices.

Notes:

• When using background detection the SDK may detect and report the same device more than once and/or at regular intervals. This is a limitation of the Android Bluetooth implementation.

• During initial device scan Android may first report a Bluetooth device with no name then later report the same device with the correct name.

• The Android Bluetooth stack is fragile and can be corrupted by any 3rd party app. If no devices are detected, try turning Bluetooth off and back on again. If this doesn't help then rebooting the phone usually does.