# Modules.BLE
Add-on Bluetooth Low Energy module
# Overview
Using Bluetooth Low Energy module is used to interact with Bluetooth Low Energy (BLE) devices.
You can download the module at appcelerator.ble (opens new window)
Note (IOS): Starting iOS 13, it's mandatory for developers to specify the Privacy Usage Description for Bluetooth by including NSBluetoothAlwaysUsageDescription in their tiapp.xml file. Otherwise accessing any Core Bluetooth APIs would lead to a crash. For backward support for older iOS versions, NSBluetoothPeripheralUsageDescription needs to be defined.
If your app needs to run in background to perform certain Bluetooth-related tasks, it must declare that it supports a Core Bluetooth background execution mode in tiapp.xml using UIBackgroundModes key
<key>UIBackgroundModes</key> <array> <string>bluetooth-central</string> <string>bluetooth-peripheral</string> </array>
bluetooth-central : The app communicates with Bluetooth low energy peripherals using the Core Bluetooth framework. bluetooth-peripheral :The app shares data using the Core Bluetooth framework.
The Apple documentation states that applications are allowed to scan while backgrounded but the scan must specify the service types. wild card scan is not supported in the background.
Note: A detailed information about how to use module in your application, can be found with artifacts at path modules/iphone (platform)/appcelerator.ble/x.y.z (version of module)/documentation/index.html
# Properties
# apiName READONLY
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button
.
# bubbleParent
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
# lifecycleContainer
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
# Methods
# addEventListener
Adds the specified callback as an event listener for the named event.
Parameters
Name | Type | Description |
---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. |
Returns
- Type
- void
# applyProperties
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
Parameters
Name | Type | Description |
---|---|---|
props | Dictionary | A dictionary of properties to apply. |
Returns
- Type
- void
# createBeaconIdentityConstraint
create a constraint that describes the identity caracteristics of a beacon.
Parameters
Name | Type | Description |
---|---|---|
uuid | String | UUID associated with the constraint. |
major | Number | Most significant value associated with the constraint. If a major value wasn't specified, this will be nil. |
minor | Number | Least significant value associated with the constraint. If a minor value wasn't specified, this will be nil. |
Returns
# createBeaconRegion
create Beacon Region.
Parameters
Name | Type | Description |
---|---|---|
uuid | String | The value of uuid. |
identifier | String | The value of beacon identifier. |
major | Number | The value of major. |
minor | Number | The value of minor. |
Returns
# createDescriptor
create descriptor.
Parameters
Name | Type | Description |
---|---|---|
value | Object | The value of descriptor. |
uuid | String | The Bluetooth-specific UUID of the descriptor. |
permission | Number | The permission for descriptor. This parameter is only for android. In android, the permissions can be different for characteristic and descriptor. If Characteristic have the read permission then it is only readable and if descriptor have the write permission, then it is only writable. |
Returns
# createMutableCharacteristic
create mutable characteristic.
Parameters
Name | Type | Description |
---|---|---|
properties | Array<Number> | Characteristic properties determine how the characteristic value can be used, or how the descriptor(s) can be accessed. |
permissions | Array<Number> | The permissions of the characteristic value. |
uuid | String | The Bluetooth-specific UUID of the characteristic. |
descriptors | Array<Modules.BLE.Descriptor> | An array of the characteristic’s descriptors. |
Returns
# createRegionManager
create a region manager to scan beacons.
Returns
# disable
Disables the local Bluetooth adapter.
This method requires bluetooth permissions to successfully work. To check whether these permissions are granted or not, call isBluetoothAndBluetoothAdminPermissionsGranted method. Listen for the didUpdateState event to be notified when the local Bluetooth adapter is turning off.
Returns
Returns true if the process is initiated successfully or when the bluetooth is already off.
- Type
- Boolean
# enable
Enables the local Bluetooth adapter.
This method requires bluetooth permissions to successfully work. To check whether these permissions are granted or not, call isBluetoothAndBluetoothAdminPermissionsGranted method. Listen for the didUpdateState event to be notified when the local Bluetooth adapter is turning on.
Returns
Returns true if the process is initiated successfully or when the bluetooth is already on.
- Type
- Boolean
# fireEvent
Fires a synthesized event to any registered listeners.
Parameters
Name | Type | Description |
---|---|---|
name | String | Name of the event. |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
Returns
- Type
- void
# initCentralManager
Initializes the module's central manager. This function must be called in an app that acts as a central before any other function can be used.
Parameters
Name | Type | Description |
---|---|---|
showPowerAlert | Boolean | A Boolean value that specifies whether the system warns the user if the app instantiates the central manager when Bluetooth service isn’t available. |
restoreIdentifier | String | A string containing a unique identifier (UID) for the central manager to instantiate. |
Returns
# initPeripheralManager
Initializes the module's peripheral manager object. This function must be called in an app that acts as a peripheral before any other function can be used.
Parameters
Name | Type | Description |
---|---|---|
showPowerAlert | Boolean | A Boolean value that specifies whether the system warns the user if the app instantiates the peripheral manager when Bluetooth service isn’t available. |
restoreIdentifier | String | A string containing a unique identifier (UID) for the peripheral manager to instantiate. |
Returns
# isAdvertisingSupported
Determines whether Bluetooth Low Energy Advertising feature is supported on the local Bluetooth device.
Returns
Returns true if BLE Advertising is supported on the device, false on bluetooth off or if BLE Advertising is not supported.
- Type
- Boolean
# isBluetoothAndBluetoothAdminPermissionsGranted
Determines if bluetooth permissions have been granted.
If this method returns false
, then you'll need to call the
requestPermissions method to request these permissions from the user.
Returns
Returns true if bluetooth permissions have been granted
- Type
- Boolean
# isEnabled
Determines if Bluetooth is currently enabled and ready for use.
Returns
Returns true if the local adapter is on.
- Type
- Boolean
# isSupported
Determines whether Bluetooth Low Energy feature is supported on the local Bluetooth device.
Returns
Returns true if BLE is supported on the device, false otherwise.
- Type
- Boolean
# removeEventListener
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback
parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Parameters
Name | Type | Description |
---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to |
Returns
- Type
- void
# requestPermissions
Displays a dialog requesting bluetooth permissions from the user.
Displays a dialog requesting the BLUETOOTH_ADVERTISE
, BLUETOOTH_CONNECT
, and BLUETOOTH_SCAN
permissions
if running on Android 12 or higher. These permission are required by this module to
discover devices and to make the app's device discoverable by other devices. On older Android OS versions,
a dialog will not be displayed and will instead check if permissions BLUETOOTH
and BLUETOOTH_ADMIN
are defined in the app's manifest.
The given optional callback argument and returned Promise
will provide a success
property
indicating if permissions were granted or not.
A dialog will not be displayed if permissions have already been granted and will immediately invoke the optional callback and returned promise with a success result.
Parameters
Name | Type | Description |
---|---|---|
callback | Callback<Titanium.Android.RequestPermissionAccessResult> | Function to be invoked indicating if permissions were granted or not. |
Returns
Returns a Promise
whose resolved value is equivalent to that passed to the optional callback argument.
- Type
- Promise<Titanium.Android.RequestPermissionAccessResult>
# Constants
# ADVERT_DATA_KEY_IS_CONNECTABLE
A Boolean value that indicates whether the advertising event type is connectable.
The value for this key is an Number object. You can use this value to determine whether your app can currently connect to a peripheral.
# ADVERT_DATA_KEY_LOCAL_NAME
The local name of a peripheral.
The value associated with this key is an String.
# ADVERT_DATA_KEY_MANUFACTURER_DATA
The manufacturer data of a peripheral.
The value associated with this key is an TiBuffer object.
# ADVERT_DATA_KEY_OVERFLOW_SERVICE_UUIDS
An array of UUIDs found in the overflow area of the advertisement data.
The value associated with this key is an array of one or more String objects, representing Service UUIDs. Because data stored in this area results from not fitting in the main advertisement, UUIDs listed here are “best effort” and may not always be accurate. For details about the overflow area of advertisement data, see the startAdvertising(_😃 method in PeripheralManager.
# ADVERT_DATA_KEY_SERVICE_DATA
A dictionary that contains service-specific advertisement data.
The keys (Strings objects) represent Service UUIDs, and the values (TiBuffer objects) represent service-specific data.
# ADVERT_DATA_KEY_SERVICE_UUIDS
An array of service UUIDs.
The value associated with this key is an Array
# ADVERT_DATA_KEY_SOLICITED_SERVICE_UUIDS
An array of solicited service UUIDs.
The value associated with this key is an array of one or more String objects, representing Service UUIDs.
# ADVERT_DATA_KEY_TX_POWER_LEVEL
The transmit power of a peripheral.
The value associated with this key is an instance of Number. This key and value are available if the peripheral provides its transmitting power level in its advertising packet. You can calculate the path loss by comparing the RSSI value with the transmitting power level.
# ATT_ATTRIBUTE_NOT_FOUND_ERROR
The attribute wasn’t found within the specified attribute handle range.
# ATT_ATTRIBUTE_NOT_LONG_ERROR
The ATT read blob request can’t read or write the attribute.
# ATT_INSUFFICIENT_AUTHENTICATION_ERROR
Reading or writing the attribute’s value failed for lack of authentication.
# ATT_INSUFFICIENT_AUTHORIZATION_ERROR
Reading or writing the attribute’s value failed for lack of authorization.
# ATT_INSUFFICIENT_ENCRYPTION_ERROR
Reading or writing the attribute’s value failed for lack of encryption.
# ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR
The encryption key size used for encrypting this link is insufficient.
# ATT_INSUFFICIENT_RESOURCES_ERROR
Resources are insufficient to complete the ATT request.
# ATT_INVALID_ATTRIBUTE_VALUE_LENGTH_ERROR
The length of the attribute’s value is invalid for the intended operation.
# ATT_INVALID_HANDLE_ERROR
The attribute handle is invalid on this peripheral.
# ATT_INVALID_OFFSET_ERROR
The specified offset value was past the end of the attribute’s value.
# ATT_INVALID_PDU_ERROR
The attribute Protocol Data Unit (PDU) is invalid.
# ATT_PREPARE_QUEUE_FULL_ERROR
The prepare queue is full, as a result of there being too many write requests in the queue.
# ATT_READ_NOT_PERMITTED_ERROR
The permissions prohibit reading the attribute’s value.
# ATT_REQUEST_NOT_SUPPORTED_ERROR
The attribute server doesn’t support the request received from the client.
# ATT_UNLIKELY_ERROR
The ATT request encountered an unlikely error and wasn’t completed.
# ATT_UNSUPPORTED_GROUP_TYPE_ERROR
The attribute type isn’t a supported grouping attribute as defined by a higher-layer specification.
# ATT_WRITE_NOT_PERMITTED_ERROR
The permissions prohibit writing the attribute’s value.
# AUTHORISATION_STATUS_ALLOWED_ALWAYS
A state that indicates the user has authorized Bluetooth at any time.
# AUTHORISATION_STATUS_DENIED
A state that indicates the user explicitly denied Bluetooth access for this app.
# AUTHORISATION_STATUS_NOT_DETERMINED
A state that indicates the user has yet to authorize Bluetooth for this app.
# AUTHORISATION_STATUS_RESTRICTED
A state that indicates this app isn’t authorized to use Bluetooth.
# BEACON_PROXIMITY_FAR
current state of the device with reference to a region is far
# BEACON_PROXIMITY_IMMEDIATE
current state of the device with reference to a region is immediate
# BEACON_PROXIMITY_NEAR
current state of the device with reference to a region is near
# BEACON_PROXIMITY_UNKNOWN
current state of the device with reference to a region is unknown
# CBUUID_CHARACTERISTIC_AGGREGATE_FORMAT_STRING
The UUID for the Aggregate Format descriptor, as a string.
# CBUUID_CHARACTERISTIC_EXTENDED_PROPERTIES_STRING
The UUID for the Extended Properties descriptor, as a string. The corresponding value for this descriptor is an NSNumber object.
# CBUUID_CHARACTERISTIC_FORMAT_STRING
The UUID for the Presentation Format descriptor, as a string. The corresponding value for this descriptor is an NSData object.
# CBUUID_CHARACTERISTIC_USER_DESCRIPTION_STRING
The UUID for the User Description descriptor, as a string. The corresponding value for this descriptor is an NSString object.
# CBUUID_CLIENT_CHARACTERISTIC_CONFIGURATION_STRING
The UUID for the Client Configuration descriptor, as a string. In iOS, the corresponding value for this descriptor is an NSNumber object. In android, it is a 32 bit uuid.
# CBUUID_L2CAPPSM_CHARACTERISTIC_STRING
The PSM of an L2CAP channel associated with the GATT service containing this characteristic.This PSM is a little-endian UInt16. Servers can publish this characteristic with the UUID ABDD3056-28FA-441D-A470-55A75A52553A.
# CBUUID_SERVER_CHARACTERISTIC_CONFIGURATION_STRING
The UUID for the Server Configuration descriptor, as a string. The corresponding value for this descriptor is an NSNumber object.
# CHARACTERISTIC_PERMISSION_READ_ENCRYPTED
A permission that indicates only trusted devices can read the attribute’s value.
# CHARACTERISTIC_PERMISSION_READABLE
A permission that indicates a peripheral can read the attribute’s value.
# CHARACTERISTIC_PERMISSION_WRITE_ENCRYPTED
A permission that indicates only trusted devices can write the attribute’s value.
# CHARACTERISTIC_PERMISSION_WRITEABLE
A permission that indicates a peripheral can write the attribute’s value.
# CHARACTERISTIC_PROPERTIES_AUTHENTICATED_SIGNED_WRITES
A property that indicates the perhipheral allows signed writes of the characteristic’s value, without a response to indicate the write succeeded.
# CHARACTERISTIC_PROPERTIES_BROADCAST
A property that indicates the characteristic can broadcast its value using a characteristic configuration descriptor.
# CHARACTERISTIC_PROPERTIES_EXTENDED_PROPERTIES
A property that indicates the characteristic defines additional properties in the extended properties descriptor.A property that indicates the characteristic defines additional properties in the extended properties descriptor.
# CHARACTERISTIC_PROPERTIES_INDICATE
A property that indicates the peripheral permits notifications of the characteristic’s value, with a response from the central to indicate receipt of the notification.
# CHARACTERISTIC_PROPERTIES_INDICATE_ENCRYPTION_REQUIRED
A property that indicates only trusted devices can enable indications of the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_NOTIFY
A property that indicates the peripheral permits notifications of the characteristic’s value, without a response from the central to indicate receipt of the notification.
# CHARACTERISTIC_PROPERTIES_NOTIFY_ENCRYPTION_REQUIRED
A property that indicates that only trusted devices can enable notifications of the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_READ
A property that indicates a peripheral can read the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_WRITE
A property that indicates a peripheral can write the characteristic’s value, with a response to indicate that the write succeeded.
# CHARACTERISTIC_PROPERTIES_WRITE_WITHOUT_RESPONSE
A property that indicates a peripheral can write the characteristic's value, without a response to indicate that the write succeeded.
# CHARACTERISTIC_TYPE_WRITE_WITH_RESPONSE
Write a characteristic value, without any response from the peripheral to indicate whether the write was successful.
# CHARACTERISTIC_TYPE_WRITE_WITHOUT_RESPONSE
Write a characteristic value, with a response from the peripheral to indicate whether the write was successful.
# CONNECT_PERIPHERAL_OPTIONS_KEY_ENABLE_TRANSPORT_BRIDGING
An option to bridge classic Bluetooth technology profiles, if already connected over Bluetooth Low Energy.
options object key used in Modules.BLE.CentralManager.connectPeripheral. This option tells the system to connect non-GATT profiles on classic Bluetooth devices, if there is a low energy GATT connection to the same device. A true value instructs the system to bring up classic transport profiles when a low energy transport peripheral connects. A false value tells the system not to use the profiles.
# CONNECT_PERIPHERAL_OPTIONS_KEY_NOTIFY_ON_CONNECTION
A Boolean value that specifies whether the system should display an alert when connecting a peripheral in the background.
options object key used in Modules.BLE.CentralManager.connectPeripheral. The value for this key is an Boolean. This key is useful for apps that haven’t specified the bluetooth-central background mode and can’t display their own alert. If more than one app requests a notification for a given peripheral, the one that was most recently in the foreground receives the alert. If the key isn’t specified, the default value is false.
# CONNECT_PERIPHERAL_OPTIONS_KEY_NOTIFY_ON_DISCONNECTION
A Boolean value that specifies whether the system should display an alert when disconnecting a peripheral in the background.
options object key used in Modules.BLE.CentralManager.connectPeripheral. The value for this key is an Boolean. This key is useful for apps that haven’t specified the bluetooth-central background mode and can’t display their own alert. If more than one app requests a notification for a given peripheral, the one that was most recently in the foreground receives the alert. If the key isn’t specified, the default value is false.
# CONNECT_PERIPHERAL_OPTIONS_KEY_NOTIFY_ON_NOTIFICATION
A Boolean value that specifies whether the system should display an alert for any notification sent by a peripheral.
options object key used in Modules.BLE.CentralManager.connectPeripheral. If true, the system displays an alert for all notifications received from a given peripheral while the app is suspended. the default value is false.
# CONNECT_PERIPHERAL_OPTIONS_KEY_REQUIRES_ANCS
An option to require Apple Notification Center Service (ANCS) when connecting a device.
options object key used in Modules.BLE.CentralManager.connectPeripheral.
# CONNECT_PERIPHERAL_OPTIONS_KEY_START_DELAY
An option that indicates a delay before the system makes a connection.
options object key used in Modules.BLE.CentralManager.connectPeripheral. The corresponding value is an Number that indicates the duration of the delay in seconds.
# CONNECTION_EVENT_TYPE_PEER_CONNECTED
Peer connected event type. This is 'event' type value for CENTREL_MANAGER_EVENT_PERIPHERAL_CONNECTION_EVENT_DID_OCCUR event.
# CONNECTION_EVENT_TYPE_PEER_DISCONNECTED
Peer disconnect event type. This is 'event' type value for CENTREL_MANAGER_EVENT_PERIPHERAL_CONNECTION_EVENT_DID_OCCUR event.
# CONNECTION_PRIORITY_BALANCED
Connection parameter recommended by the Bluetooth SIG.
# CONNECTION_PRIORITY_HIGH
For a high priority, low latency connection.
# CONNECTION_PRIORITY_LOW_POWER
For a low power, reduced data rate connection.
# DESCRIPTOR_PERMISSION_READ_ENCRYPTED
An encrypted read permission for descriptor.
# DESCRIPTOR_PERMISSION_WRITE
A write permission for descriptor.
# DESCRIPTOR_PERMISSION_WRITE_ENCRYPTED
An encrypted write permission for descriptor.
# DISABLE_NOTIFICATION_VALUE
Value used to disable notifications or indications for a client configuration descriptor. You may pass this constant to the unsubscribeFromCharacteristic method.
# ENABLE_INDICATION_VALUE
Value used to enable indication for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.
# ENABLE_NOTIFICATION_VALUE
Value used to enable notification for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_ALWAYS
User has granted authorization to use their location only while they are using your app.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_WHEN_IN_USE
Write a characteristic value, with a response from the peripheral to indicate whether the write was successful.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_DENIED
User has explicitly denied authorization for this application, or location services are disabled in Settings.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED
User has not yet made a choice with regards to this application
# LOCATION_MANAGER_AUTHORIZATION_STATUS_RESTRICTED
This application is not authorized to use location services. Due to active restrictions on location services, the user cannot change this status, and may not have personally denied authorization
# MANAGER_STATE_POWERED_OFF
A state that indicates Bluetooth is currently powered off.
# MANAGER_STATE_POWERED_ON
A state that indicates Bluetooth is currently powered on and available to use.
# MANAGER_STATE_RESETTING
A state that indicates the connection with the system service was momentarily lost.
# MANAGER_STATE_TURNING_OFF
One of the possible values returned by the state property. This value indicates that the local Bluetooth adapter is turning off.
Listen for the didUpdateState event to be notified when the local Bluetooth adapter is turning off.
# MANAGER_STATE_TURNING_ON
One of the possible values returned by the state property. This value indicates that the local Bluetooth adapter is turning on.
Listen for the didUpdateState event to be notified when the local Bluetooth adapter is turning on.
# MANAGER_STATE_UNAUTHORIZED
A state that indicates the application isn’t authorized to use the Bluetooth low energy role.
# MANAGER_STATE_UNKNOWN
The Peripheral and Central manager’s state is unknown
# MANAGER_STATE_UNSUPPORTED
A state that indicates this device doesn’t support the Bluetooth low energy central or client role.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_HIGH
A latency setting that prioritizes extending battery life over rapid communication.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_LOW
A latency setting indicating that prioritizes rapid communication over battery life.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_MEDIUM
A latency setting that balances communication frequency and battery life.
# PERIPHERAL_STATE_CONNECTED
The peripheral is connected to the central manager.
# PERIPHERAL_STATE_CONNECTING
The peripheral is in the process of connecting to the central manager.
# PERIPHERAL_STATE_DISCONNECTED
The peripheral isn’t connected to the central manager.
# PERIPHERAL_STATE_DISCONNECTING
The peripheral is disconnecting from the central manager.
# REGION_STATE_INSIDE
The current state of the device with reference to a region is inside
# REGION_STATE_OUTSIDE
The current state of the device with reference to a region is outside
# REGION_STATE_UNKNOWN
The current state of the device with reference to a region is unknown