# Modules.BLE.PeripheralManager

An object that manages and advertises peripheral services exposed by this app.

Availability

1.0.0

Extends

Titanium.Proxy

# Overview

Core Bluetooth uses PeripheralManager objects to manage published services within the local peripheral’s Generic Attribute Profile (GATT) database and to advertise these services to central devices (represented by Central objects). While a service is in the database, any connected central can see and connect to it. That said, if your app hasn’t specified the bluetooth-peripheral background mode, the contents of its services become disabled when it’s in the background or in a suspended state. In this scenario, any remote central trying to access the service’s characteristic value or characteristic descriptors receives an error.

# Properties

# isAdvertising

Availability

1.1.0

1.0.0

isAdvertising :Boolean

Whether or not the the module's internal peripheral manager is currently advertising data.

# peripheralManagerState

Availability

1.1.0

1.0.0

peripheralManagerState :Number

State of the module's internal peripheral manager. Its value is one of the MANAGER_STATE_* constants.

# restoredPeripheralManagerIdentifier

Availability

1.0.0

restoredPeripheralManagerIdentifier :String

string the restoration identifier for a peripheral manager object. this is the same string you assigned to the restoreIdentifier parameter of the initPeripheralManager function.

# Methods

# addService

Availability

1.1.0

1.0.0

addService(characteristics, uuid, primary) → Modules.BLE.Service

Publishes a service and any of its associated characteristics and characteristic descriptors to the local GATT database.

Parameters

Name	Type	Description
`characteristics`	Array<Modules.BLE.Characteristic>	A list of characteristics of a service.
`uuid`	String	The Bluetooth-specific UUID of the attribute.
`primary`	Boolean	The type of the service (primary or secondary).

Returns

Object of service which is added.

Type: Modules.BLE.Service

# closePeripheral

Availability

1.1.0

closePeripheral() → void

This method closes the peripheral.

This method, when called terminate the ongoing advertisement process if any and closes the peripheral. Application should call this method, soon after it is done with the peripheral operations.

Returns

Type: void

# publishL2CAPChannel

Availability

1.1.0

1.0.0

publishL2CAPChannel(encryptionRequired) → void

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

Parameters

Name	Type	Description
`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.

Returns

Type: void

# removeAllServices

Availability

1.1.0

1.0.0

removeAllServices() → void

Removes all published services from the local GATT database.

Returns

Type: void

# removeService

Availability

1.1.0

1.0.0

removeService(service) → void

Removes a specified published service from the local GATT database.

Parameters

Name	Type	Description
`service`	Modules.BLE.Service	Object of service you want to remove.

Returns

Type: void

# respondToDescriptorRequest

Availability

1.1.0

respondToDescriptorRequest(descriptorRequest, result) → void

Used to respond to request(s) received via the didReceiveDescriptorReadRequest or didReceiveDescriptorWriteRequest event.

Parameters

Name	Type	Description
`descriptorRequest`	Modules.BLE.DescriptorRequest	The request to which the peripheral is responding.
`result`	Number	The result code; see the ATT_ERROR* constants.

Returns

Type: void

# respondToRequest

Availability

1.1.0

1.0.0

respondToRequest(request, result) → void

Used to respond to request(s) received via the didReceiveReadRequest or didReceiveWriteRequests event.

Parameters

Name	Type	Description
`request`	Modules.BLE.Request	The request to which the peripheral is responding.
`result`	Number	The result code; see the ATT_ERROR* constants.

Returns

Type: void

# setDesiredConnectionLatency

Availability

1.0.0

setDesiredConnectionLatency(latency, central) → void

Sets the desired connection latency for an existing connection on the module's internal peripheral manager.

Connection latency changes are not guaranteed, so the resultant latency may vary. If a desired latency is not set, the latency chosen by the central at the time of connection establishment will be used. Typically, it is not necessary to change the latency.

Parameters

Name	Type	Description
`latency`	Number	The desired connection latency. see BLE.PERIPHERAL_MANAGER_CONNECTION_LATENCY_*
`central`	Modules.BLE.Central	A connected central

Returns

Type: void

# startAdvertising

Availability

1.1.0

1.0.0

startAdvertising(localName, serviceUUIDs) → void

Instructs the module's internal peripheral manager to start advertising.

Important: You must call the initPeripheralManager function first! Supported advertising data types are localName and serviceUUIDs. When in the foreground, an application can utilize up to 28 bytes of space in the initial advertisement data for any combination of the supported advertising data types. If this space is used up, there are an additional 10 bytes of space in the scan response that can be used only for the local name. Note that these sizes do not include the 2 bytes of header information that are required for each new data type. Any service UUIDs that do not fit in the allotted space will be added to a special " overflow" area, and can only be discovered by an iOS device that is explicitly scanning for them. While an application is in the background, the local name will not be used and all service UUIDs will be placed in the "overflow" area. In Android, Before starting the advertisement, user must add the service first. If this is not the case, then this method will not work as expected.

Parameters

Name	Type	Description
`localName`	String \| Boolean	The local name of a peripheral. This parameter is of type boolean in android
`serviceUUIDs`	Array<String>	An array of service UUIDs.

Returns

Type: void

# startAdvertisingBeaconRegion

Availability

1.1.0

startAdvertisingBeaconRegion([measurePower, beaconRegion]) → void

Instructs the module's internal peripheral manager to start advertising for beacon region.

Important: You must call the initPeripheralManager function first!

Parameters

Name	Type	Description
`measurePower`	Number	This is the RSSI of the device observed from one meter in its intended environment.This value is optional, but should be specified to achieve the best ranging performance. If not specified, it will default to a pre-determined value for the device.
`beaconRegion`	Modules.BLE.BeaconRegion	Object of Beacon Region.

Returns

Type: void

# stopAdvertising

Availability

1.1.0

1.0.0

stopAdvertising() → void

Instructs the module's internal peripheral manager to stop advertising.

Returns

Type: void

# stopAdvertising

Availability

1.0.0

stopAdvertising() → void

Instructs the module's internal peripheral manager to stop advertising.

Returns

Type: void

# unpublishL2CAPChannel

Availability

1.1.0

1.0.0

unpublishL2CAPChannel(PSM) → void

The service PSM to be removed from the system.

Parameters

Name	Type	Description
`PSM`	Number	The PSM of the channel along with we can close the particular channel.

Returns

Type: void

# updateValue

Availability

1.1.0

1.0.0

updateValue(characteristic, data, centrals) → Boolean

Instructs the module's internal peripheral manager to send an updated characteristic value to one or more centrals, via a notification or indication.

Parameters

Name	Type	Description
`characteristic`	Modules.BLE.MutableCharacteristic	The value of the characteristic.
`data`	Titanium.Buffer	updated characteristic value.
`centrals`	Array<Modules.BLE.Central>	The list of centrals that need to be updated. If not specified, all subscribed centrals will be updated.

Returns

True if the update could be sent, otherwise false. In iOS, if false was returned, the readyToUpdateSubscribers event will be fired once space has become available, and the update should be re-sent if so desired. In Android, if there are multiple centrals need to be updated, then for any of the central, if the update could not be sent, it returns false.

Type: Boolean

# Events

# didUpdateState

Availability

1.1.0

1.0.0

Fired whenever the state of the module's internal peripheral manager changes.

Properties

Name	Type	Description
state	Number	An integer describing the state of the module's internal peripheral manager. See the MANAGER_STATE_* constants.
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.

# didPublishL2CAPChannel

Availability

1.1.0

1.0.0

Tells the delegate that the peripheral manager created a listener for incoming L2CAP channel connections.

Properties

Name	Type	Description
psm	Number	The Protocol/Service Multiplexer (PSM) of the published channel.
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
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.

# didUnpublishL2CAPChannel

Availability

1.1.0

1.0.0

Tells the delegate that the peripheral manager removed a published service from the local system.

Properties

Name	Type	Description
psm	Number	The Protocol/Service Multiplexer (PSM) of the published channel.
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
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.

# didOpenL2CAPChannel

Availability

1.1.0

1.0.0

Tells the delegate that the peripheral manager opened an L2CAP channel.

Properties

Name	Type	Description
channel	Modules.BLE.L2CAPChannel	The channel opened by the manager.
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
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.

# willRestoreState

Availability

1.0.0

Tells the delegate that the peripheral manager opened an L2CAP channel.

Properties

Name	Type	Description
advertisementData	Object	An object (dictionary) containing the data being advertised at the time the application was terminated by the system. See the startAdvertising method for more detail.
services	Array<String>	Array of uuids of Services
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.

# didStartAdvertising

Availability

1.1.0

1.0.0

This event returns the result of a startAdvertising call. If advertisement could not be started, the cause will be detailed in the errorCode, errorDomain, and errorDescription properties.

Properties

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

# didAddService

Availability

1.1.0

1.0.0

This event returns the result of a addService call. If service could not be added, the cause will be detailed in the errorCode, errorDomain, and errorDescription properties.

Properties

Name	Type	Description
service	Modules.BLE.Service	An object representing the service that was added.
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
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.

# didSubscribeToCharacteristic

Availability

1.1.0

1.0.0

This event is fired when a central configures a characteristic to notify or indicate. It should be used as a cue to start sending updates as the characteristic value changes.

In Android, this event is fired by writing on the Client Configuration UUID (00002902-0000-1000-8000-00805f9b34fb) descriptor for given characteristic by central with descriptor values,BLE.ENABLE_NOTIFICATION_VALUE or BLE.ENABLE_INDICATION_VALUE.

Properties

Name	Type	Description
central	Modules.BLE.Central	An object representing the central that subscribed.
characteristic	Modules.BLE.Characteristic	An object representintg the characteristic to which the central subscribed.
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.

# didUnsubscribeFromCharacteristic

Availability

1.1.0

1.0.0

This event is fired when a central removes notifications/indications from a characteristic.

In Android, this event is fired by writing on the Client Configuration UUID (00002902-0000-1000-8000-00805f9b34fb) descriptor for given characteristic by central with value BLE.DISABLE_NOTIFICATION_VALUE

Properties

Name	Type	Description
central	Modules.BLE.Central	An object representing the central that unsubscribed.
characteristic	Modules.BLE.Characteristic	An object representintg the characteristic from which the central unsubscribed.
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.

# didReceiveReadRequest

Availability

1.1.0

1.0.0

This event is fired when the module's internal peripheral manager receives a read request.

Properties

Name	Type	Description
request	Modules.BLE.Request	An object representing the request.
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.

# didReceiveWriteRequests

Availability

1.1.0

1.0.0

This event is fired when the module's internal peripheral manager receives a write request for one or more characteristics.

For every invocation of this method, respondToRequest should be called exactly once. If the requests parameter contains multiple requests, they must be treated as an atomic unit. If the execution of one of the requests would cause a failure, the request and error reason should be provided and none of the requests should be executed.

Properties

Name	Type	Description
request	Array<Modules.BLE.Request>	request objects describing the incoming write request
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.

# didReceiveDescriptorReadRequest

Availability

1.1.0

This event is fired when the module's internal peripheral manager receives a read request on descriptor.

Properties

Name	Type	Description
descriptorRequest	Modules.BLE.DescriptorRequest	An object representing the descriptor request.
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.

# didReceiveDescriptorWriteRequests

Availability

1.1.0

This event is fired when the module's internal peripheral manager receives a write request on descriptor.

Properties

Name	Type	Description
descriptorRequests	Modules.BLE.DescriptorRequest	An object representing the descriptor request.
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.

# readyToUpdateSubscribers

Availability

1.0.0

This event is fired when the module's internal peripheral manager receives a write request for one or more characteristics.This event is fired after a failed call to updateValue, when the module's internal peripheral manager is again ready to send characteristic value updates.