Logical Labs Bluetooth Low Energy Module for Android

API Docs for: 1.2.7
Show:

BluetoothLEModule Class

Module: Readme

Methods

cancelPeripheralConnection

(
  • peripheral
)
Void

Available since 1.0.0

Cancels an active or pending connection to the specified peripheral. This command is non-blocking, and any commands that are still pending to the peripheral may or may not complete.

It extremely important to note that canceling a connection does not guarantee the immediate disconnection of the underlying physical link. This can be caused by a variety of different factors, including other application(s) that hold an outstanding connection to the peripheral. However, in this situation, you will still immediately receive a disconnectedPeripheral event.

Parameters:

Returns:

Void:

clearAppLaunchIntent

() Void

Available since 1.2.0

Use this function to instruct the module not to launch the app when the user enters a monitored region.

Returns:

Void:

connectPeripheral

(
  • params
)
Void

Available since 1.0.0

Initiates a connection to the specified peripheral. Connection attempts never time out and, depending on the outcome, will result in a connectedPeripheral or failedToConnectPeripheral event.

Pending attempts are cancelled automatically upon deallocation of the peripheral, and explicitly via the cancelPeripheralConnection method.

Parameters:

  • params Object

    An object with the following properties:

    • peripheral: Peripheral

      The object representing the peripheral.

    • [autoConnect=false] Boolean optional

      Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).

Returns:

Void:

createBeacon

(
  • params
)
Beacon

Available since 1.2.1

Creates a beacon object from scan data.

You can use this function to create a beacon object from information received via the discoveredPeripheral event, if the discovered peripheral is in fact a beacon. Returns null if the peripheral is not a beacon.

Parameters:

  • params Object

    An object with the following properties:

    • rawAdvertisementData TiBuffer
    • RSSI Number

Returns:

Beacon:

createBeaconRegion

(
  • params
)
Void

Available since 1.1.0

Creates a BeaconRegion object that can be used to start advertising an iBeacon.

Parameters:

  • params Object

    An object with the following properties (see the properties of the BeaconRegion class for details):

    • identifier String

      A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application.

    • UUID String

      The UUID of the beacon.

    • [major] Number optional

      The major number of the beacon. If not specified, the major and minor numbers of the beacon are ignored.

    • [minor] Number optional

      The minor number of the beacon. If not specified, the minor number of the beacon is ignored.

    • [notifyEntryStateOnDisplay=false] Boolean optional

      When set to true, the beacon notifications will be sent only when the user turns on the display and the device is already inside the region.

Returns:

Void:

createPeripheral

(
  • params
)
Peripheral

Available since 1.0.2

Creates a Peripheral object from a MAC address.

Parameters:

  • params Object
    • address String

      The MAC address as string.

Returns:

Peripheral:

disable

() Boolean

Available since 1.0.0

Disables the Bluetooth adapter.

Returns:

Boolean:

Returns true if the Bluetooth adapter was successfully disabled.

enable

() Boolean

Available since 1.0.0

Enables the Bluetooth adapter.

Returns:

Boolean:

Returns true if the Bluetooth adapter was successfully enabled.

getState

() Number

Available since 1.0.0

Returns the current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Returns:

Number:

isAppLaunchConfigured

() Boolean

Available since 1.2.0

Determines whether the module is currently configured to launch the app when BLE activity is detected.

Returns:

Boolean:

isEnabled

() Boolean

Available since 1.0.0

Determines whether the Bluetooth adapter is enabled and ready for use.

Returns:

Boolean:

Returns true if Bluetooth is currently enabled.

isSupported

() Boolean

Available since 1.0.0

Determines whether the device is capable of communicating with other devices via Bluetooth Low Energy radio.

Returns:

Boolean:

requestRegionState

(
  • params
)
Void

Available since 1.2.4

Retrieves the state of a region asynchronously.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

retrieveMonitoredRegions

() Void

Available since 1.2.5

Retrieves the currently monitored beacon regions.

Async function; returns the results in a retrievedMonitoredRegions event.

Returns:

Void:

retrievePeripherals

() Void

Available since 1.0.0

This function doesn't do anything on Android; only present for compatibility with iOS.

Returns:

Void:

setAppLaunchIntent

(
  • params
)
Void

Available since 1.2.0

Specifies the parameters for the intent the module is expected to use to launch the app. Use this function to instruct the module to launch the app when the user enters a monitored region.

The intent launching the app will have an extra called eventName, which is a string holding the name of the event that caused the module to launch the app.

Parameters:

  • params Object
    • packageName String

      The package name of the app to be launched by the module.

    • className String

      The name of the class (typically the app's main activity) to be launched by the module.

Returns:

Void:

setScanTimers

(
  • params
)
Void

Available since 1.2.0

Use this function to control the timing of beacon related scanning. By default, scanning is restarted every 1.1 seconds while region monitoring or beacon ranging is enabled, to be able to provide beacon related events in a timely manner. You can use this function to increase the scan interval if less frequent beacon related events are sufficient for your use case.

Note that these timers don't impact general scanning unless general scanning is used in parallel with beacon related functionality. See the Beacon Support section of the Readme for more information.

Calling this function will reset scanning to make sure the new timers take effect immediately.

Parameters:

  • params Object
    • scanPeriod Number

      Scan period in milliseconds. This is how long each scanning session lasts.

    • scanPausePeriod Number

      Scan pause period in milliseconds. This is the time gap between scan periods.

Returns:

Void:

startRangingBeacons

(
  • params
)
Void

Available since 1.1.0

Starts the delivery of notifications for beacons in the specified region.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

startRegionMonitoring

(
  • params
)
Void

Available since 1.1.0

Starts monitoring the specified region.

You must call this method once for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. If that old region was being ranged, then so will the new one. Note that "identifier" literally means the identifier property, not the UUID! The regions you add using this method are stored in the monitoredRegions property.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

startScan

(
  • params
)
Void

Available since 1.0.0

Starts scanning for peripherals.

The result of this operation is returned via the discoveredPeripheral event.

Parameters:

  • params Object

    An object with the following properties:

    • [UUIDs] Array of Strings optional

      The UUIDs of services.

Returns:

Void:

stopRangingBeacons

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions.

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

stopRegionMonitoring

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions. Note that the region is being identified by its identifier property, not the UUID!

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

stopScan

() Void

Available since 1.0.0

Stops scanning for peripherals.

Returns:

Void:

Properties

filterDuplicateBeacons

Boolean

Available since 1.1.0

Determines whether the beacons included with the rangedBeacons event will be filtered for duplicates. Defaults to false. A beacon is considered a duplicate of another if their UUID, major, and minor numbers are all the same.

monitoredRegions

Array of BeaconRegions read-only

Available since 1.1.0

The beacon regions currently being monitored by the module.

rangedRegions

Array of BeaconRegions read-only

Available since 1.2.0

The beacon regions currently being ranged by the module.

state

Number read-only

Available since 1.0.0

The current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Constants

BEACON_PROXIMITY_FAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_IMMEDIATE

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_NEAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_UNKNOWN

Number

Available since 1.1.0

One of the possible values of the proximity property.

CHAR_PERM_NONE

Number

Available since 1.0.0

Characteristic has no permissions.

CHAR_PERM_READ_ENCRYPTED

Number

Available since 1.0.0

Characteristic is readable by trusted devices.

CHAR_PERM_READABLE

Number

Available since 1.0.0

Characteristic is readable.

CHAR_PERM_WRITE_ENCRYPTED

Number

Available since 1.0.0

Characteristic is writeable by trusted devices.

CHAR_PERM_WRITEABLE

Number

Available since 1.0.0

Characteristic is writeable.

CHAR_PROP_BROADCAST

Number

Available since 1.0.0

Permits broadcasts of the characteristic value using a characteristic configuration descriptor. Not allowed for local characteristics.

CHAR_PROP_EXTENDED_PROPERTIES

Number

Available since 1.0.0

If set, additional characteristic properties are defined in the characteristic extended properties descriptor. Not allowed for local characteristics

CHAR_PROP_INDICATE

Number

Available since 1.0.0

Permits indications of the characteristic value.

CHAR_PROP_NOTIFY

Number

Available since 1.0.0

Permits notifications of the characteristic value, without a response.

CHAR_PROP_READ

Number

Available since 1.0.0

Permits reads of the characteristic value.

CHAR_PROP_SIGNED_WRITES

Number

Available since 1.0.0

Permits signed writes of the characteristic value.

CHAR_PROP_WRITE

Number

Available since 1.0.0

Permits writes of the characteristic value.

CHAR_PROP_WRITE_WITHOUT_RESPONSE

Number

Available since 1.0.0

Permits writes of the characteristic value, without a response.

CHARACTERISTIC_TYPE_WRITE_WITH_RESPONSE

Number

Available since 1.0.0

Use this constant for the type parameter of the writeValueForCharacteristic method. It specifies that the write to be performed requires a response.

CHARACTERISTIC_TYPE_WRITE_WITHOUT_RESPONSE

Number

Available since 1.0.0

Use this constant for the type parameter of the writeValueForCharacteristic method. It specifies that the write to be performed does not require a response.

DISABLE_NOTIFICATION_VALUE

TiBuffer

Available since 1.0.0

Value used to disable notifications or indications for a client configuration descriptor. You may pass this constant to the unsubscribeFromCharacteristic method.

ENABLE_INDICATION_VALUE

TiBuffer

Available since 1.0.0

Value used to enable indication for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.

ENABLE_NOTIFICATION_VALUE

TiBuffer

Available since 1.0.0

Value used to enable notification for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.

REGION_STATE_INSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_OUTSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_UNKNOWN

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

STATE_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned off.

STATE_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned on.

STATE_TURNING_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn off.

STATE_TURNING_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn on.

Events

connectedPeripheral

Available since 1.0.0

This event is fired when a connection initiated by the connectPeripheral method has succeeded.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that connected to the local central manager.

disconnectedPeripheral

Available since 1.0.0

Fired when a peripheral disconnects from the local central manager.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that disconnected.

  • errorCode Number

    The error code; only present if an error occurred.

discoveredPeripheral

Available since 1.0.0

Fired when a peripheral is discovered.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that was discovered by the local central manager.

  • RSSI Number

    An integer representing the RSSI value of the connection.

  • rawAdvertisementData TiBuffer

    A TiBuffer object holding the content of the advertisement record offered by the remote device. Note that on iOS, this information is provided as a dictionary (an object with various properties).

enteredRegion

Available since 1.1.0

This event is fired when the user enters a monitored region.

Event Payload:

exitedRegion

Available since 1.1.0

This event is fired when the user exits a monitored region.

Event Payload:

failedToConnectPeripheral

Available since 1.0.0

This event is fired when a connection initiated by the connectPeripheral method fails.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that failed to connect.

  • errorCode Number

    The error code; only present if an error occurred.

  • errorDescription String

    The error description; only present if an error occurred.

moduleReady

Available since 1.2.0

This event is fired when the module is ready. Wait for this event before calling any methods on the module.

rangedBeacons

Available since 1.1.0

Use this event to determine which beacons are in range.

See also the filterDuplicateBeacons property.

Event Payload:

  • beacons Array of Beacons

    An array of Beacon objects representing the beacons currently in range. You can use the information in these objects to determine the range of each beacon and its identifying information.

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

regionStateUpdated

Available since 1.1.0

This event is fired when the state of a monitored region is updated.

Event Payload:

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

  • state Number

    One of the REGION_STATE_* constants.

retrievedMonitoredRegions

Available since 1.2.5

Returns the result of the retrieveMonitoredRegions function.

Event Payload:

  • beaconRegions Array of BeaconRegions

    An array of BeaconRegion objects, representing the currently monitored beacon regions.

stateChanged

Available since 1.0.0

Fired when the state of the local Bluetooth adapter changes.

Event Payload:

  • state Number

    An integer describing the state of the Bluetooth adapter.