Introduction

This module makes the Bluetooth Low Energy functionality in Android 4.3 and later available to Titanium developers.

The module defines the following object classes:

• Peripheral
• Service
• Characteristic
• Descriptor

You do not need to (and in fact: can't) create any of these objects explicitly. You will, however, receive instances of these (proxy) classes as event parameters. The properties available on these JavaScript objects roughly correspond to the properties of their native counterparts. However, one of the objectives of the Android version of the Bluetooth LE module is to match, as closely as possible, the API of the iOS version of the module. This means that the names of the properties and functions follow the iOS naming convention, not necessarily the Android native names.

For example, the Android SDK does not have a class that directly corresponds to a "peripheral"; the module's Peripheral class is an amalgamation of the native BluetoothDevice and BluetoothGatt classes.

It is not always practical to provide complete parity between the platforms as the underlying native SDKs differ in some significant ways. The most significant difference is in the initialization -- the Usage section explains how initialization is done on Android.

Usage

The following code segments are not complete; they only demonstrate the essentials of using the module. The module includes a complete example app that demonstrates many different use cases, including communication with a heart rate monitor, a blood pressure monitor, monitoring iBeacons, and launching an app automatically when a beacon is detected. You will find this in the standard example directory.

To access this module from JavaScript, you would do the following:

var BluetoothLE = require("com.logicallabs.bluetoothle");

The BluetoothLE variable is a reference to the Module object.

On Android, the module needs to start a service and connect to it. It fires the moduleReady event when this is done. Several functions of the module don't work until the service is running so you should wait for this event before calling any functions on the module. On iOS, the module is usable immediately; it still fires this event to allow platform independent coding on the JavaScript side.

One big difference between the Android and the iOS versions of the Bluetooth Low Energy module is how the Bluetooth adapter is initialized. On Android, the app may not need to initialize the Bluetooth adapter at all if the user already turned Bluetooth on in the Settings. You can use the BluetoothLE.isEnabled() function to check this:

    if (BluetoothLE.isEnabled()) {
        BluetoothLE.startScan();
    } else {
        BluetoothLE.enable();
    }

Beacons

Use the createBeaconRegion function to create beacon region objects:

var beaconRegion = BluetoothLE.createBeaconRegion({
    UUID: uuid,
    identifier: '#' + idCounter
});

This object then can be passed to the startRegionMonitoring function to start monitoring:

BluetoothLE.startRegionMonitoring({
    beaconRegion: region
});

This will result in enteredRegion, exitedRegion, and regionStateUpdated events.

Once the user enters a region, the startRangingBeacons function can be used to get periodic updates about the beacons in range:

BluetoothLE.addEventListener('regionStateUpdated', function(e) {
    switch(e.state) {
        case BluetoothLE.REGION_STATE_INSIDE:
            BluetoothLE.startRangingBeacons({
                beaconRegion: e.region
            });
            break;
        case BluetoothLE.REGION_STATE_OUTSIDE:
            BluetoothLE.stopRangingBeacons({
                beaconRegion: e.region
            });
            break;
    }
});

This will result in rangedBeacons events.

Use the stopRangingBeacons and stopRegionMonitoring functions to stop ranging and monitoring, respectively.

Beacon Support

In order to provide support for beacons on Android, the module automatically starts and stops BLE scanning at a relatively high frequency (every 1.1 secs by default) as long as region monitoring or beacon ranging is turned on. This is necessary because this is the only way to receive updated information about the beacons from the native Android API.

The setScanTimers function can be used to change the default timers.

When it comes to scanning, the general BLE functionality is to some extent in conflict with beacon support, due to a limitation of the native Android SDK. Although the native Android SDK allows us to run multiple scans in parallel, BLE devices that were within range at the time the scan started will be reported only to the first scan. For this reason, the module makes an attempt to coalesce all scanning activity into one scanning request at the native level. This makes it possible to support both general and beacon specific activities at the same time, but it comes with the following caveats:

1) Beacon related functionality and scanning for specific service UUIDs are not compatible with each other because scanning for beacons requires a scan that is not limited by service UUIDs. If you call the startScan function with service UUIDs while beacon related scanning is active, beacon related scanning will be suspended. If you try to start beacon related scanning while general scanning limited by service UUIDs is active, beacon related scanning will be placed on hold. Beacon related scanning will (re)start as soon as the general scan limited by service UUIDs is stopped.

2) Beacon related functionality and general scanning not limited by service UUIDs are compatible with each other. However, when these two are active at the same time, the discoveredPeripheral event related to the general scan will be fired according to the timers set by the setScanTimers function (that is, every 1.1 seconds by default).

Background operations

Your app will receive Bluetooth LE and beacon related events normally as long as it is in memory, even if it is in the background.

Use the setAppLaunchIntent to configure the module to automatically launch your app when a beacon is detected after the Android device was rebooted.

Issues and Limitations

The general BLE functionality to some extent conflicts with the beacon support, see the Beacon Support section above.

Change Log

Version 1.0.0

• First release

Version 1.0.1

• Added documentation for Peripheral's name property.
• Added isConnected property to Peripheral object.
• Documentation fixes.

Version 1.0.2

• Improved disconnect efficiency.
• Added createPeripheral function.
• Fixed bug in subscribeToCharacteristic.
• Added support for 4-digit UUIDs in startScan.
• Improved sample app.

Version 1.1.0

• Introduced iBeacon support.

Version 1.1.1

• Fixed bugs related to regionStateUpdated and rangedBeacons events.

Version 1.2.0

• Documentation fixes and improvements.
• Hardened module interface to deal more gracefully with incorrect parameters.
• Added moduleReady event.
• Added functions related to app launching by the module (setAppLaunchIntent, isAppLaunchConfigured, clearAppLaunchIntent).
• Added setScanTimers function.
• Improved interoperability between general BLE functionality and beacon support.
• Added rangedRegions property.
• Introduced the moduleReady event.

Version 1.2.1

• Documentation and sample app improvements.
• Added createBeacon function.

Version 1.2.2

• Improved the updatedValueForCharacteristic event.
• Documentation improvements.

Version 1.2.3

• Added example for Texas Instruments CC2541 Sensor Tag.

Version 1.2.4

• Documentation improvements
• Sample app improvements
• Added requestRegionState function.
• Bug fixes.

Version 1.2.5

• Added retrieveMonitoredRegions function and retrievedMonitoredRegions event.
• Other improvements to maintain parity with iOS.

Version 1.2.6

• N/A

Version 1.2.7

• Base BLE fixes

Author

Zsombor Papp titanium@logicallabs.com

License

Logical Labs Commercial License

Copyright

Copyright (c) 2013 by Logical Labs, LLC