# Modules.BLE.Peripheral

A remote peripheral device.

Availability

1.0.0

Extends

Titanium.Proxy

# Overview

The CBPeripheral class represents remote peripheral devices that your app discovers with a central manager (an instance of CentralManager). In iOS, Peripherals use universally unique identifiers (UUIDs), to identify themselves. For Android, Peripherals use address to be uniqely identified. Peripherals may contain one or more services or provide useful information about their connected signal strength.

# Properties

# address

Availability

1.0.0

address :String

Once a peripheral has been connected at least once by the system, it is assigned a address (UUID). This address can be stored and later provided to the retrievePeripherals method.

# ancsAuthorized

Availability

1.0.0

ancsAuthorized :Boolean

A Boolean value that indicates if the remote device has authorization to receive data over ANCS protocol.

# canSendWriteWithoutResponse

Availability

1.0.0

canSendWriteWithoutResponse :Boolean

A Boolean value that indicates whether the remote device can send a write without a response.

# isConnected

Availability

1.0.0

isConnected :Boolean

Whether or not the peripheral is currently connected.

# name

Availability

1.0.0

name :String

The name of the peripheral.

# services

Availability

1.0.0

services :Array<Modules.BLE.Service>

A list of a peripheral’s discovered services.

# state

Availability

1.0.0

state :Number

The current connection state of the peripheral. Possible values defined by PERIPHERAL_STATE_* constants.

# Methods

# discoverCharacteristics

Availability

1.0.0

discoverCharacteristics(services[, characteristicUUIDs]) → void

Discovers the specified characteristic(s) of a service. The result of this operation is returned via the didDiscoverCharacteristics event. In android, all the characteristics have already been discovered, as part of the discoverServices operation. So, this method is kept in android to keep parity with the iOS platform.

Parameters

Name	Type	Description
`services`	Modules.BLE.Service	The service whose characteristics you want to discover.
`characteristicUUIDs`	Array<String>	An array of UUID objects that you are interested in. Each UUID identifies the characteristic you want to discover.

Returns

Type: void

# discoverDescriptorsForCharacteristic

Availability

1.0.0

discoverDescriptorsForCharacteristic(characteristic) → void

Discovers the descriptor(s) of a characteristic.The result of this operation is returned via the didDiscoverDescriptorsForCharacteristics event. In android, all the descriptors have already been discovered, as part of the discoverServices operation. So, this method is kept in android to keep parity with the iOS platform.

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.Characteristic	The characteristic whose descriptors you want to discover.

Returns

Type: void

# discoverIncludedServices

Availability

1.0.0

discoverIncludedServices(services[, includedServiceUUIDs]) → void

Discovers the specified included service(s) of a service.The result of this operation is returned via the didDiscoverIncludedServices event. In android, all the included services have already been discovered, as part of the discoverServices operation. So, this method is kept in android to keep parity with the iOS platform.

Parameters

Name	Type	Description
`services`	Modules.BLE.Service	The service whose characteristics you want to discover.
`includedServiceUUIDs`	Array<String>	An array of UUID objects that you are interested in. Each UUID identifies the included service you want to discover.

Returns

Type: void

# discoverServices

Availability

1.0.0

discoverServices([serviceUUIDs]) → void

Discovers available service(s) on the peripheral. The result of this operation is returned via the didDiscoverServices event.

Parameters

Name	Type	Description
`serviceUUIDs`	Array<String>	An array of UUID objects that you are interested in. Each UUID identifies the services you want to discover. In android, the behavior is discoverServices discovers all the available services irrespective of this parameter.

Returns

Type: void

# maximumWriteValueLength

Availability

1.0.0

maximumWriteValueLength(characteristicWriteType) → void

The maximum amount of data, in bytes, you can send to a characteristic in a single write type.

Parameters

Name	Type	Description
`characteristicWriteType`	Number	Values representing the possible write types to a characteristic’s value.

Returns

Type: void

# openL2CAPChannel

Availability

1.1.0

1.0.0

openL2CAPChannel(psmIdentifier[, encryptionRequired]) → void

Attempts to open an L2CAP channel to the peripheral using the supplied Protocol/Service Multiplexer (PSM).

Parameters

Name	Type	Description
`psmIdentifier`	Number	The PSM of the channel to open.
`encryptionRequired`	Boolean	The bool can be true if the service requires the link to be encrypted before a stream can be established. false if the service can be used over an unsecured link. This parameter is applicable in android only and the default value is false.

Returns

Type: void

# readRSSI

Availability

1.0.0

readRSSI() → void

Retrieves the current RSSI value for the peripheral while connected to the central manager.

Returns

Type: void

# readValueForCharacteristic

Availability

1.0.0

readValueForCharacteristic(characteristic) → void

Reads the value of a characteristic.The result of this operation is returned via the didUpdateValueForCharacteristic event.

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.Characteristic	The characteristic whose value you want to read.

Returns

Type: void

# readValueForDescriptor

Availability

1.0.0

readValueForDescriptor(descriptor) → void

Reads the value of a descriptor. The result of this operation is returned via the didUpdateValueForDescriptor event.

Parameters

Name	Type	Description
`descriptor`	Modules.BLE.Descriptor	The characteristic descriptor whose value you want to read.

Returns

Type: void

# requestConnectionPriority

Availability

1.0.0

requestConnectionPriority(connectionPriority) → void

Request the specific connection priority. This method will send connection parameter update request to the remote device.

Parameters

Name	Type	Description
`connectionPriority`	Number	Connection priority to set. Must be one of CONNECTION_PRIORITY_HIGH, CONNECTION_PRIORITY_BALANCED and CONNECTION_PRIORITY_LOW_POWER.

Returns

Type: void

# subscribeToCharacteristic

Availability

1.0.0

subscribeToCharacteristic(characteristic[, descriptorUUID="00002902-0000-1000-8000-00805f9b34fb"[, descriptorValue=ENABLE_NOTIFICATION_VALUE]]) → void

Enables notifications/indications for a characteristic. If the characteristic allows both, notifications will be used.

In Android, subscribing to a characteristic is a two step process in which, first the setCharacteristicNotification() is called which enables the notification locally(on Android device), followed by writing on the descriptor, which is optional. If the second paramater(descriptorUUID) not provided, then writing on the descriptor would not be done. Reference (https://developer.android.com/guide/topics/connectivity/bluetooth-le#notification)

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.Characteristic	The characteristic whose value you want to read.
`descriptorUUID="00002902-0000-1000-8000-00805f9b34fb"`	String	The UUID of the configuration descriptor of the characteristic. The module will attempt to write descriptorValue to this descriptor. If you do not want the module to do this, set this parameter to an empty string. This parameter is only for Android.
`descriptorValue=ENABLE_NOTIFICATION_VALUE`	Titanium.Buffer	The value to be written to the configuration descriptor. This parameter is only for Android.

Returns

Type: void

# unsubscribeFromCharacteristic

Availability

1.0.0

unsubscribeFromCharacteristic(characteristic[, descriptorUUID="00002902-0000-1000-8000-00805f9b34fb"[, descriptorValue=DISABLE_NOTIFICATION_VALUE]]) → void

Disables notifications/indications for a characteristic.

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.Characteristic	The characteristic whose value you want to read.
`descriptorUUID="00002902-0000-1000-8000-00805f9b34fb"`	String	The UUID of the configuration descriptor of the characteristic. The module will attempt to write descriptorValue to this descriptor. If you do not want the module to do this, set this parameter to an empty string. This parameter is only for Android.
`descriptorValue=DISABLE_NOTIFICATION_VALUE`	Titanium.Buffer	The value to be written to the configuration descriptor. This parameter is only for Android.

Returns

Type: void

# writeValueForCharacteristic

Availability

1.0.0

writeValueForCharacteristic(characteristic, data, characteristicWriteType) → void

Writes a value to a characteristic.

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.Characteristic	The characteristic whose value you want to write.
`data`	Titanium.Buffer	The new value of the characteristic.
`characteristicWriteType`	Number	The type of write to be executed. See CHARACTERISTIC_TYPE_WRITE_WITH_RESPONSE and CHARACTERISTIC_TYPE_WRITE_WITHOUT_RESPONSE.

Returns

Type: void

# writeValueForDescriptor

Availability

1.0.0

writeValueForDescriptor(descriptor, data) → void

Writes the value of a descriptor. The result of this operation is returned via the didWriteValueForDescriptor event.

Writes the value of a characteristic descriptor. This method copies the data passed into the data parameter, and you can dispose of it after the method returns. Note (iOS): You can’t use this method to write the value of a client configuration descriptor (represented by the BLE.CBUUID_CLIENT_CHARACTERISTIC_CONFIGURATION_STRING constant), which describes the configuration of notification or indications for a characteristic’s value. If you want to manage notifications or indications for a characteristic’s value, you must use the subscribeToCharacteristic({characteristic:}) and unsubscribeFromCharacteristic({characteristic:}) method instead. Another Note (iOS): Once published, you can’t update the value dynamically. Reference (https://developer.apple.com/documentation/corebluetooth/cbmutabledescriptor/1518999-init)

Parameters

Name	Type	Description
`descriptor`	Modules.BLE.Descriptor	The descriptor whose value you want to write.
`data`	Titanium.Buffer	The new value of the characteristic.

Returns

Type: void

# Events

# didDiscoverCharacteristics

Availability

1.0.0

This event returns the result of a call to the discoverCharacteristics method. If the characteristic(s) were read successfully, they can be retrieved via the service property's characteristics property.

Core Bluetooth invokes this method when your app calls the discoverCharacteristics method. If the peripheral successfully discovers the characteristics of the specified service, you can access them through the service’s characteristics property.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
service	Modules.BLE.Service	The service to which the characteristics belong.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didDiscoverDescriptorsForCharacteristics

Availability

1.0.0

This event returns the result of a call to the discoverDescriptorsForCharacteristic method.

Core Bluetooth invokes this method when your app calls the discoverDescriptors method. If the peripheral successfully discovers the descriptors of the specified characteristic, you can access them through the characteristic’s descriptors property.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
characteristic	Modules.BLE.Characteristic	The service to which the characteristics belong.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didDiscoverIncludedServices

Availability

1.0.0

This event returns the result of a call to the discoverIncludedServices method.

Core Bluetooth invokes this method when your app calls the discoverIncludedServices method. If the peripheral successfully discovers services, you can access them through the service’s includedServices property.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didDiscoverServices

Availability

1.0.0

Discovers the specified services of the peripheral.

Core Bluetooth invokes this method when your app calls the discoverServices method. If the peripheral successfully discovers services, you can access them through the peripheral’s services property.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didModifyServices

Availability

1.0.0

This event is fired when the services of the peripheral change.

Core Bluetooth invokes this method whenever one or more services of a peripheral change. The invalidatedServices parameter includes any changed services that you previously discovered; you can no longer use these services. You can use the discoverServices method to discover any new services that the peripheral added to its database. Use this same method to find out whether any of the invalidated services that you were using (and want to continue using) now have a different location in the peripheral’s database.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
services	Array<Modules.BLE.Service>	The services that have been invalidated.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didUpdateName

Availability

1.0.0

This event is fired when the name of the peripheral changes.

Core Bluetooth invokes this method whenever the peripheral’s Generic Access Profile (GAP) device name changes. Since a peripheral device can change its GAP device name, you can implement this method if your app needs to display the current name of the peripheral device.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didUpdateNotificationStateForCharacteristics

Availability

1.0.0

This event returns the result of a call to the subscribeToCharacteristic or unsubscribeFromCharacteristic method.

Core Bluetooth invokes this method when your app calls the subscribeToCharacteristic or unsubscribeFromCharacteristic method.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
characteristic	Modules.BLE.Characteristic	The characteristic to subscribe.
isSubscribed	Boolean	A Boolean value that specifies whether the didUpdateNotificationStateForCharacteristics event is for subscribe or unsubscribe operation. true, if subscribe and false otherwise.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didReadRSSI

Availability

1.0.0

This event returns the result of a call to the readRSSI method.

Core Bluetooth invokes this method when your app calls the readRSSI() method, while the peripheral is connected to the central manager. If successful, the error parameter is nil and the parameter RSSI reports the peripheral’s signal strength, in decibels. If unsuccessful, the error parameter returns the cause of the failure.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
rssi	Number	value last read
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didUpdateValueForCharacteristic

Availability

1.0.0

This event is fired after a call to the readValueForCharacteristic method, or upon receipt of a notification/indication.

Core Bluetooth invokes this method when your app calls the readValueForCharacteristic method. A peripheral also invokes this method to notify your app of a change to the value of the characteristic for which the app previously enabled notifications by calling subscribeToCharacteristic or unsubscribeFromCharacteristic method.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
characteristic	Modules.BLE.Characteristic	The characteristic containing the value.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didUpdateValueForDescriptor

Availability

1.0.0

This event returns the result of a call to the readValueForDescriptor method.

Core Bluetooth invokes this method when your app calls the readValueForDescriptor method.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
descriptor	Modules.BLE.Descriptor	The characteristic descriptor containing the value.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didWriteValueForCharacteristic

Availability

1.0.0

This event returns the result of a call to the writeValueForCharacteristic method.

Core Bluetooth invokes this method only when your app calls the writeValueForCharacteristic method with the BLE.CHARACTERISTIC_WRYTE_TYPE_WITH_RESPOSNE constant specified as the write type.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
characteristic	Modules.BLE.Characteristic	The characteristic containing the value.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didWriteValueForDescriptor

Availability

1.0.0

This event returns the result of a call to the writeValueForDescriptor method.

Core Bluetooth invokes this method when your app calls the writeValueForDescriptor method.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral sending the event.
descriptor	Modules.BLE.Descriptor	The object representing the descriptor that was changed.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# peripheralIsReadyToSendWriteWithoutResponse

Availability

1.0.0

Tells the delegate that a peripheral is again ready to send characteristic updates.

The peripheral calls this delegate method after a failed call to writeValueForCharacteristic, once peripheral is ready to send characteristic value updates.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral sending the event.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didOpenChannel

Availability

1.1.0

1.0.0

This method delivers the result of a previous call to openL2CAPChannel.

Delivers the result of an attempt to open an L2CAP channel.

Properties

Name	Type	Description
sourcePeripheral	Modules.BLE.Peripheral	The peripheral sending the event.
channel	Modules.BLE.L2CAPChannel	A live L2CAP connection to a remote device.
errorCode	String	The error code; only present if an error occurred.
errorDomain	String	The error domain; only present if an error occurred.
errorDescription	String	The error description; only peresent if an error occurred.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.