Titanium Mobile # Modules.BLE
Add-on Bluetooth Low Energy module
1.0.0
1.0.0# Overview
Using Bluetooth Low Energy module is used to interact with Bluetooth Low Energy (BLE) devices.
Note: This feature requires a Pro or Enterprise subscription. More infos here!
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
# Methods
# createBeaconIdentityConstraint
1.1.0create 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
1.1.0create 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
1.1.0 1.0.0create 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
1.1.0 1.0.0create 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
1.1.0create a region manager to scan beacons.
Returns
# disable
1.0.0Disables 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
1.0.0Enables 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
# initCentralManager
1.0.0 1.0.0Initializes 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
1.1.0 1.0.0Initializes 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
1.1.0Determines 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
1.0.0Determines 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
1.0.0Determines if Bluetooth is currently enabled and ready for use.
Returns
Returns true if the local adapter is on.
- Type
- Boolean
# isSupported
1.0.0Determines 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
# requestPermissions
2.0.0Displays 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
1.0.0A 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
1.0.0The local name of a peripheral.
The value associated with this key is an String.
# ADVERT_DATA_KEY_MANUFACTURER_DATA
1.0.0The manufacturer data of a peripheral.
The value associated with this key is an TiBuffer object.
# ADVERT_DATA_KEY_OVERFLOW_SERVICE_UUIDS
1.0.0An 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
1.0.0A 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
1.0.0An array of service UUIDs.
The value associated with this key is an Array
# ADVERT_DATA_KEY_SOLICITED_SERVICE_UUIDS
1.0.0An 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
1.0.0The 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
1.0.0The attribute wasn’t found within the specified attribute handle range.
# ATT_ATTRIBUTE_NOT_LONG_ERROR
1.0.0The ATT read blob request can’t read or write the attribute.
# ATT_INSUFFICIENT_AUTHENTICATION_ERROR
1.1.0 1.0.0Reading or writing the attribute’s value failed for lack of authentication.
# ATT_INSUFFICIENT_AUTHORIZATION_ERROR
1.1.0 1.0.0Reading or writing the attribute’s value failed for lack of authorization.
# ATT_INSUFFICIENT_ENCRYPTION_ERROR
1.1.0 1.0.0Reading or writing the attribute’s value failed for lack of encryption.
# ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR
1.0.0The encryption key size used for encrypting this link is insufficient.
# ATT_INSUFFICIENT_RESOURCES_ERROR
1.0.0Resources are insufficient to complete the ATT request.
# ATT_INVALID_ATTRIBUTE_VALUE_LENGTH_ERROR
1.1.0 1.0.0The length of the attribute’s value is invalid for the intended operation.
# ATT_INVALID_HANDLE_ERROR
1.0.0The attribute handle is invalid on this peripheral.
# ATT_INVALID_OFFSET_ERROR
1.1.0 1.0.0The specified offset value was past the end of the attribute’s value.
# ATT_INVALID_PDU_ERROR
1.0.0The attribute Protocol Data Unit (PDU) is invalid.
# ATT_PREPARE_QUEUE_FULL_ERROR
1.0.0The prepare queue is full, as a result of there being too many write requests in the queue.
# ATT_READ_NOT_PERMITTED_ERROR
1.1.0 1.0.0The permissions prohibit reading the attribute’s value.
# ATT_REQUEST_NOT_SUPPORTED_ERROR
1.1.0 1.0.0The attribute server doesn’t support the request received from the client.
# ATT_UNLIKELY_ERROR
1.0.0The ATT request encountered an unlikely error and wasn’t completed.
# ATT_UNSUPPORTED_GROUP_TYPE_ERROR
1.0.0The attribute type isn’t a supported grouping attribute as defined by a higher-layer specification.
# ATT_WRITE_NOT_PERMITTED_ERROR
1.1.0 1.0.0The permissions prohibit writing the attribute’s value.
# AUTHORISATION_STATUS_ALLOWED_ALWAYS
1.0.0A state that indicates the user has authorized Bluetooth at any time.
# AUTHORISATION_STATUS_DENIED
1.0.0A state that indicates the user explicitly denied Bluetooth access for this app.
# AUTHORISATION_STATUS_NOT_DETERMINED
1.0.0A state that indicates the user has yet to authorize Bluetooth for this app.
# AUTHORISATION_STATUS_RESTRICTED
1.0.0A state that indicates this app isn’t authorized to use Bluetooth.
# BEACON_PROXIMITY_FAR
1.1.0current state of the device with reference to a region is far
# BEACON_PROXIMITY_IMMEDIATE
1.1.0current state of the device with reference to a region is immediate
# BEACON_PROXIMITY_NEAR
1.1.0current state of the device with reference to a region is near
# BEACON_PROXIMITY_UNKNOWN
1.1.0current state of the device with reference to a region is unknown
# CBUUID_CHARACTERISTIC_AGGREGATE_FORMAT_STRING
1.0.0The UUID for the Aggregate Format descriptor, as a string.
# CBUUID_CHARACTERISTIC_EXTENDED_PROPERTIES_STRING
1.0.0The UUID for the Extended Properties descriptor, as a string. The corresponding value for this descriptor is an NSNumber object.
# CBUUID_CHARACTERISTIC_FORMAT_STRING
1.0.0The UUID for the Presentation Format descriptor, as a string. The corresponding value for this descriptor is an NSData object.
# CBUUID_CHARACTERISTIC_USER_DESCRIPTION_STRING
1.0.0The UUID for the User Description descriptor, as a string. The corresponding value for this descriptor is an NSString object.
# CBUUID_CLIENT_CHARACTERISTIC_CONFIGURATION_STRING
1.1.0 1.0.0The 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
1.1.0 1.0.0The 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
1.0.0The UUID for the Server Configuration descriptor, as a string. The corresponding value for this descriptor is an NSNumber object.
# CHARACTERISTIC_PERMISSION_READ_ENCRYPTED
1.0.0 1.0.0A permission that indicates only trusted devices can read the attribute’s value.
# CHARACTERISTIC_PERMISSION_READABLE
1.0.0 1.0.0A permission that indicates a peripheral can read the attribute’s value.
# CHARACTERISTIC_PERMISSION_WRITE_ENCRYPTED
1.0.0 1.0.0A permission that indicates only trusted devices can write the attribute’s value.
# CHARACTERISTIC_PERMISSION_WRITEABLE
1.0.0 1.0.0A permission that indicates a peripheral can write the attribute’s value.
# CHARACTERISTIC_PROPERTIES_AUTHENTICATED_SIGNED_WRITES
1.0.0A property that indicates the perhipheral allows signed writes of the characteristic’s value, without a response to indicate the write succeeded.
# CHARACTERISTIC_PROPERTIES_BROADCAST
1.0.0 1.0.0A property that indicates the characteristic can broadcast its value using a characteristic configuration descriptor.
# CHARACTERISTIC_PROPERTIES_EXTENDED_PROPERTIES
1.0.0 1.0.0A 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
1.0.0 1.0.0A 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
1.0.0A property that indicates only trusted devices can enable indications of the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_NOTIFY
1.0.0 1.0.0A 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
1.0.0A property that indicates that only trusted devices can enable notifications of the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_READ
1.0.0 1.0.0A property that indicates a peripheral can read the characteristic’s value.
# CHARACTERISTIC_PROPERTIES_WRITE
1.0.0 1.0.0A 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
1.0.0 1.0.0A 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
1.0.0 1.0.0Write a characteristic value, without any response from the peripheral to indicate whether the write was successful.
# CHARACTERISTIC_TYPE_WRITE_WITHOUT_RESPONSE
1.0.0 1.0.0Write a characteristic value, with a response from the peripheral to indicate whether the write was successful.
# CONNECT_PERIPHERAL_OPTIONS_KEY_ENABLE_TRANSPORT_BRIDGING
1.0.0An 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
1.0.0A 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
1.0.0A 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
1.0.0A 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
1.0.0An 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
1.0.0An 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
1.0.0Peer connected event type. This is 'event' type value for CENTREL_MANAGER_EVENT_PERIPHERAL_CONNECTION_EVENT_DID_OCCUR event.
# CONNECTION_EVENT_TYPE_PEER_DISCONNECTED
1.0.0Peer disconnect event type. This is 'event' type value for CENTREL_MANAGER_EVENT_PERIPHERAL_CONNECTION_EVENT_DID_OCCUR event.
# CONNECTION_PRIORITY_BALANCED
1.0.0Connection parameter recommended by the Bluetooth SIG.
# CONNECTION_PRIORITY_HIGH
1.0.0For a high priority, low latency connection.
# CONNECTION_PRIORITY_LOW_POWER
1.0.0For a low power, reduced data rate connection.
# DESCRIPTOR_PERMISSION_READ
1.1.0A read permission for descriptor.
# DESCRIPTOR_PERMISSION_READ_ENCRYPTED
1.1.0An encrypted read permission for descriptor.
# DESCRIPTOR_PERMISSION_WRITE
1.1.0A write permission for descriptor.
# DESCRIPTOR_PERMISSION_WRITE_ENCRYPTED
1.1.0An encrypted write permission for descriptor.
# DISABLE_NOTIFICATION_VALUE
1.0.0Value used to disable notifications or indications for a client configuration descriptor. You may pass this constant to the unsubscribeFromCharacteristic method.
# ENABLE_INDICATION_VALUE
1.0.0Value used to enable indication for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.
# ENABLE_NOTIFICATION_VALUE
1.0.0Value used to enable notification for a client configuration descriptor. You may pass this constant to the subscribeToCharacteristic method.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_ALWAYS
1.1.0User has granted authorization to use their location only while they are using your app.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_WHEN_IN_USE
1.1.0Write a characteristic value, with a response from the peripheral to indicate whether the write was successful.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_DENIED
1.1.0User has explicitly denied authorization for this application, or location services are disabled in Settings.
# LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED
1.1.0User has not yet made a choice with regards to this application
# LOCATION_MANAGER_AUTHORIZATION_STATUS_RESTRICTED
1.1.0This 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
1.0.0 1.0.0A state that indicates Bluetooth is currently powered off.
# MANAGER_STATE_POWERED_ON
1.0.0 1.0.0A state that indicates Bluetooth is currently powered on and available to use.
# MANAGER_STATE_RESETTING
1.0.0A state that indicates the connection with the system service was momentarily lost.
# MANAGER_STATE_TURNING_OFF
1.0.0One 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
1.0.0One 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
1.0.0A state that indicates the application isn’t authorized to use the Bluetooth low energy role.
# MANAGER_STATE_UNKNOWN
1.0.0The Peripheral and Central manager’s state is unknown
# MANAGER_STATE_UNSUPPORTED
1.0.0A state that indicates this device doesn’t support the Bluetooth low energy central or client role.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_HIGH
1.0.0A latency setting that prioritizes extending battery life over rapid communication.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_LOW
1.0.0A latency setting indicating that prioritizes rapid communication over battery life.
# PERIPHERAL_MANAGER_CONNECTION_LATENCY_MEDIUM
1.0.0A latency setting that balances communication frequency and battery life.
# PERIPHERAL_STATE_CONNECTED
1.0.0The peripheral is connected to the central manager.
# PERIPHERAL_STATE_CONNECTING
1.0.0The peripheral is in the process of connecting to the central manager.
# PERIPHERAL_STATE_DISCONNECTED
1.0.0The peripheral isn’t connected to the central manager.
# PERIPHERAL_STATE_DISCONNECTING
1.0.0The peripheral is disconnecting from the central manager.
# REGION_STATE_INSIDE
1.1.0The current state of the device with reference to a region is inside
# REGION_STATE_OUTSIDE
1.1.0The current state of the device with reference to a region is outside
# REGION_STATE_UNKNOWN
1.1.0The current state of the device with reference to a region is unknown