Modules.BLE.Peripheral

A remote peripheral device.

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.

Extends: Titanium.Proxy · Since: 1.0.0 · Platforms: android, iphone, ipad

Properties

address

1.0.0

1.0.0

1.0.0

Type: 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

1.0.0

1.0.0

Type: Boolean

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

canSendWriteWithoutResponse

1.0.0

1.0.0

Type: Boolean

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

isConnected

1.0.0

1.0.0

1.0.0

Type: Boolean

Whether or not the peripheral is currently connected.

name

1.0.0

1.0.0

1.0.0

Type: String

The name of the peripheral.

services

1.0.0

1.0.0

1.0.0

Type: Array<Modules.BLE.Service>

A list of a peripheral’s discovered services.

state

1.0.0

1.0.0

Type: Number

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

Methods

discoverCharacteristics

1.0.0

1.0.0

1.0.0

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	Summary	Optional
services	Modules.BLE.Service	The service whose characteristics you want to discover.	No
characteristicUUIDs	Array<String>	An array of UUID objects that you are interested in. Each UUID identifies the characteristic you want to discover.	Yes

Returns: void

discoverDescriptorsForCharacteristic

1.0.0

1.0.0

1.0.0

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	Summary	Optional
characteristic	Modules.BLE.Characteristic	The characteristic whose descriptors you want to discover.	No

Returns: void

discoverIncludedServices

1.0.0

1.0.0

1.0.0

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	Summary	Optional
services	Modules.BLE.Service	The service whose characteristics you want to discover.	No
includedServiceUUIDs	Array<String>	An array of UUID objects that you are interested in. Each UUID identifies the included service you want to discover.	Yes

Returns: void

discoverServices

1.0.0

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
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.	Yes

Returns: void

maximumWriteValueLength

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
characteristicWriteType	Number	Values representing the possible write types to a characteristic’s value.	No

Returns: void

openL2CAPChannel

1.1.0

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
psmIdentifier	Number	The PSM of the channel to open.	No
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.	Yes

Returns: void

readRSSI

1.0.0

1.0.0

1.0.0

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

Returns: void

readValueForCharacteristic

1.0.0

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
characteristic	Modules.BLE.Characteristic	The characteristic whose value you want to read.	No

Returns: void

readValueForDescriptor

1.0.0

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
descriptor	Modules.BLE.Descriptor	The characteristic descriptor whose value you want to read.	No

Returns: void

requestConnectionPriority

1.0.0

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

Parameters:

Name	Type	Summary	Optional
connectionPriority	Number	Connection priority to set. Must be one of CONNECTION_PRIORITY_HIGH, CONNECTION_PRIORITY_BALANCED and CONNECTION_PRIORITY_LOW_POWER.	No

Returns: void

subscribeToCharacteristic

1.0.0

1.0.0

1.0.0

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	Summary	Optional
characteristic	Modules.BLE.Characteristic	The characteristic whose value you want to read.	No
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.	Yes
descriptorValue=ENABLE_NOTIFICATION_VALUE	Titanium.Buffer	The value to be written to the configuration descriptor. This parameter is only for Android.	Yes

Returns: void

unsubscribeFromCharacteristic

1.0.0

1.0.0

1.0.0

Disables notifications/indications for a characteristic.

Parameters:

Name	Type	Summary	Optional
characteristic	Modules.BLE.Characteristic	The characteristic whose value you want to read.	No
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.	Yes
descriptorValue=DISABLE_NOTIFICATION_VALUE	Titanium.Buffer	The value to be written to the configuration descriptor. This parameter is only for Android.	Yes

Returns: void

writeValueForCharacteristic

1.0.0

1.0.0

1.0.0

Writes a value to a characteristic.

Parameters:

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

Returns: void

writeValueForDescriptor

1.0.0

1.0.0

1.0.0

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	Summary	Optional
descriptor	Modules.BLE.Descriptor	The descriptor whose value you want to write.	No
data	Titanium.Buffer	The new value of the characteristic.	No

Returns: void

Events

didDiscoverCharacteristics

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didDiscoverDescriptorsForCharacteristics

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didDiscoverIncludedServices

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didDiscoverServices

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didModifyServices

1.0.0

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.

Event Properties:

Name	Type	Summary
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.
services	Array<Modules.BLE.Service>	The services that have been invalidated.

didOpenChannel

1.1.0

1.0.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.

Event Properties:

Name	Type	Summary
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.

didReadRSSI

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didUpdateName

1.0.0

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.

Event Properties:

Name	Type	Summary
sourcePeripheral	Modules.BLE.Peripheral	The peripheral providing this information.

didUpdateNotificationStateForCharacteristics

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didUpdateValueForCharacteristic

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didUpdateValueForDescriptor

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didWriteValueForCharacteristic

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

didWriteValueForDescriptor

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
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.

peripheralIsReadyToSendWriteWithoutResponse

1.0.0

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.

Event Properties:

Name	Type	Summary
sourcePeripheral	Modules.BLE.Peripheral	The peripheral sending the event.