Modules.BLE.PeripheralManager
An object that manages and advertises peripheral services exposed by this app.
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.
Extends: Titanium.Proxy · Since: 1.0.0 · Platforms: android, iphone, ipad
Properties #
isAdvertising#
Type: Boolean
Whether or not the the module's internal peripheral manager is currently advertising data.
peripheralManagerState#
Type: Number
State of the module's internal peripheral manager. Its value is one of the MANAGER_STATE_* constants.
restoredPeripheralManagerIdentifier#
Type: 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 #
Publishes a service and any of its associated characteristics and characteristic descriptors to the local GATT database.
| Name | Type | Summary | Optional |
|---|---|---|---|
characteristics | Array<Modules.BLE.Characteristic> | A list of characteristics of a service. | No |
uuid | String | The Bluetooth-specific UUID of the attribute. | No |
primary | Boolean | The type of the service (primary or secondary). | No |
Returns: Modules.BLE.Service — Object of service which is added.
closePeripheral #
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: void
publishL2CAPChannel #
Attempts to open an L2CAP channel to the peripheral using the supplied Protocol/Service Multiplexer (PSM).
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | No |
Returns: void
removeService #
Removes a specified published service from the local GATT database.
| Name | Type | Summary | Optional |
|---|---|---|---|
service | Modules.BLE.Service | Object of service you want to remove. | No |
Returns: void
respondToDescriptorRequest #
Used to respond to request(s) received via the didReceiveDescriptorReadRequest or didReceiveDescriptorWriteRequest event.
| Name | Type | Summary | Optional |
|---|---|---|---|
descriptorRequest | Modules.BLE.DescriptorRequest | The request to which the peripheral is responding. | No |
result | Number | The result code; see the ATT_ERROR* constants. | No |
Returns: void
respondToRequest #
Used to respond to request(s) received via the didReceiveReadRequest or didReceiveWriteRequests event.
| Name | Type | Summary | Optional |
|---|---|---|---|
request | Modules.BLE.Request | The request to which the peripheral is responding. | No |
result | Number | The result code; see the ATT_ERROR* constants. | No |
Returns: void
setDesiredConnectionLatency #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
latency | Number | The desired connection latency. see BLE.PERIPHERAL_MANAGER_CONNECTION_LATENCY_* | No |
central | Modules.BLE.Central | A connected central | No |
Returns: void
startAdvertising #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
localName | String, Boolean | The local name of a peripheral. This parameter is of type boolean in android | No |
serviceUUIDs | Array<String> | An array of service UUIDs. | No |
Returns: void
startAdvertisingBeaconRegion #
Instructs the module's internal peripheral manager to start advertising for beacon region.
Important: You must call the initPeripheralManager function first!
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | Yes |
beaconRegion | Modules.BLE.BeaconRegion | Object of Beacon Region. | No |
Returns: void
stopAdvertising #
Instructs the module's internal peripheral manager to stop advertising.
Returns: void
stopAdvertising #
Instructs the module's internal peripheral manager to stop advertising.
Returns: void
unpublishL2CAPChannel #
The service PSM to be removed from the system.
| Name | Type | Summary | Optional |
|---|---|---|---|
PSM | Number | The PSM of the channel along with we can close the particular channel. | No |
Returns: void
updateValue #
Instructs the module's internal peripheral manager to send an updated characteristic value to one or more centrals, via a notification or indication.
| Name | Type | Summary | Optional |
|---|---|---|---|
characteristic | Modules.BLE.MutableCharacteristic | The value of the characteristic. | No |
data | Titanium.Buffer | updated characteristic value. | No |
centrals | Array<Modules.BLE.Central> | The list of centrals that need to be updated. If not specified, all subscribed centrals will be updated. | No |
Returns: Boolean — 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.
Events #
didAddService #
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.
| Name | Type | Summary |
|---|---|---|
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 |
didOpenL2CAPChannel #
Tells the delegate that the peripheral manager opened an L2CAP channel.
| Name | Type | Summary |
|---|---|---|
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 |
didPublishL2CAPChannel #
Tells the delegate that the peripheral manager created a listener for incoming L2CAP channel connections.
| Name | Type | Summary |
|---|---|---|
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 |
didReceiveDescriptorReadRequest #
This event is fired when the module's internal peripheral manager receives a read request on descriptor.
| Name | Type | Summary |
|---|---|---|
descriptorRequest | Modules.BLE.DescriptorRequest | An object representing the descriptor request. |
didReceiveDescriptorWriteRequests #
This event is fired when the module's internal peripheral manager receives a write request on descriptor.
| Name | Type | Summary |
|---|---|---|
descriptorRequests | Modules.BLE.DescriptorRequest | An object representing the descriptor request. |
didReceiveReadRequest #
This event is fired when the module's internal peripheral manager receives a read request.
| Name | Type | Summary |
|---|---|---|
request | Modules.BLE.Request | An object representing the request. |
didReceiveWriteRequests #
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.
| Name | Type | Summary |
|---|---|---|
request | Array<Modules.BLE.Request> | request objects describing the incoming write request |
didStartAdvertising #
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.
| Name | Type | Summary |
|---|---|---|
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 |
didSubscribeToCharacteristic #
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.
| Name | Type | Summary |
|---|---|---|
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. |
didUnpublishL2CAPChannel #
Tells the delegate that the peripheral manager removed a published service from the local system.
| Name | Type | Summary |
|---|---|---|
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 |
didUnsubscribeFromCharacteristic #
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
| Name | Type | Summary |
|---|---|---|
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. |
didUpdateState #
Fired whenever the state of the module's internal peripheral manager changes.
| Name | Type | Summary |
|---|---|---|
state | Number | An integer describing the state of the module's internal peripheral manager. See the MANAGER_STATE_* constants. |
readyToUpdateSubscribers #
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.
willRestoreState #
Tells the delegate that the peripheral manager opened an L2CAP channel.
| Name | Type | Summary |
|---|---|---|
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 |