# Modules.BLE.CentralManager

An object that scans for, discovers, connects to, and manages peripherals.

Availability

1.0.0

Extends

Titanium.Proxy

# Overview

CentralManager objects manage discovered or connected remote peripheral devices (represented by Peripheral objects), including scanning for, discovering, and connecting to advertising peripherals.

# Properties

# apiName READONLY

Availability

3.2.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability

3.0.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# isScanning

Availability

1.0.0

isScanning :Boolean

A Boolean value that indicates whether the central is currently scanning.

# lifecycleContainer

Availability

3.6.0

lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# peripherals

Availability

1.0.0

peripherals :Array<Modules.BLE.Peripheral>

All discovered peripherals

# state READONLY

Availability

1.0.0

state :Number

State of the module's internal central manager. For android, it is the current state of the local Bluetooth adapter. Its value is one of the MANAGER_STATE_* constants.

# Methods

# addEventListener

Availability

1.0.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type: void

# applyProperties

Availability

3.0.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
`props`	Dictionary	A dictionary of properties to apply.

Returns

Type: void

# cancelPeripheralConnection

Availability

1.0.0

cancelPeripheralConnection(peripheral) → void

Cancels an active or pending connection to peripheral. Note that this is non-blocking, and any Peripheral commands that are still pending to peripheral may or may not complete.

Parameters

Name	Type	Description
`peripheral`	Modules.BLE.Peripheral	peripheral object which connnection will be canceled

Returns

Type: void

# connectPeripheral

Availability

1.0.0

connectPeripheral(peripheral[, options]) → void

Initiates a connection to peripheral. Connection attempts never time out and, depending on the outcome, will result in a call to either didConnectPeripheral or didFailToConnectPeripheral event. Pending attempts are cancelled automatically upon deallocation of peripheral, and explicitly via Modules.BLE.CentralManager.cancelPeripheralConnection}.

Parameters

Name	Type	Description
`peripheral`	Modules.BLE.Peripheral	peripheral object to connect
`options`	Object	This parameter is specific for the iphone, ipad platforms. An optional dictionary specifying connection behavior options. all available dictionary keys are defined as Modules.BLE.CONNECT_PERIPHERAL_OPTIONS_KEY_*

Returns

Type: void

# createPeripheral

Availability

1.0.0

createPeripheral(address) → Modules.BLE.Peripheral

Creates a Modules.BLE.Peripheral class object with the given address.

Parameters

Name	Type	Description
`address`	String	address of the remote bluetooth device.

Returns

Type: Modules.BLE.Peripheral

# fireEvent

Availability

1.0.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`event`	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type: void

# isAccessFineLocationPermissionGranted

Availability

1.0.0

isAccessFineLocationPermissionGranted() → Boolean

Determines whether the ACCESS_FINE_LOCATION permission is granted or not.

ACCESS_FINE_LOCATION permission is provided at runtime by the app user. To request this permission use requestAccessFineLocationPermission method

Returns

Returns true if the ACCESS_FINE_LOCATION permission is granted

Type: Boolean

# registerForConnectionEvents

Availability

1.0.0

registerForConnectionEvents([peripherals[, services]]) → void

Calls connectionEventDidOccur event when a connection event occurs matching any of the given options. Passing nil in the option parameter clears any prior registered matching options.

Parameters

Name	Type	Description
`peripherals`	Array<String>	A list of peripherals UUIDs.
`services`	Array<String>	A list of services UUIDs.

Returns

Type: void

# removeEventListener

Availability

1.0.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`.

Returns

Type: void

# requestAccessFineLocationPermission

Availability

1.0.0

requestAccessFineLocationPermission() → void

Request for the ACCESS_FINE_LOCATION.

This permission is necessary for the Bluetooth device to scan the nearby BLE devices or other Bluetooth operations.

Returns

Type: void

# retrieveConnectedPeripheralsWithServices

Availability

1.0.0

retrieveConnectedPeripheralsWithServices(UUIDs) → Array<Modules.BLE.Peripheral>

Returns a list of the peripherals connected to the system whose services match a given set of criteria.

Parameters

Name	Type	Description
`UUIDs`	Array<String>	A list of service UUIDs.

Returns

Type: Array<Modules.BLE.Peripheral>

# retrievePeripheralsWithIdentifiers

Availability

1.0.0

retrievePeripheralsWithIdentifiers(UUIDs) → Array<Modules.BLE.Peripheral>

Returns a list of known peripherals by their identifiers.

Parameters

Name	Type	Description
`UUIDs`	Array<String>	A list of peripheral identifiers from which Peripheral objects can be retrieved.

Returns

Type: Array<Modules.BLE.Peripheral>

# startScan

Availability

1.0.0

startScan([services[, options]]) → void

Starts scanning for peripherals.

Parameters

Name	Type	Description
`services`	Array<String>	The UUIDs of services.
`options`	Modules.BLE.CentralScanOptions	Key/value pairs specifying options for the scan.

Returns

Type: void

# stopScan

Availability

1.0.0

stopScan() → void

Stops scanning for peripherals.

Returns

Type: void

# Events

# didUpdateState

Availability

1.0.0

A event called when centrel manager state updated

Invoked whenever the central manager's state has been updated. Commands should only be issued when the state is Modules.BLE.MANAGER_STATE_POWERED_ON. A state below Modules.BLE.MANAGER_STATE_POWERED_ON implies that scanning has stopped and any connected peripherals have been disconnected. If the state moves below Modules.BLE.MANAGER_STATE_POWERED_OFF, all Peripheral objects obtained from this central manager become invalid and must be retrieved or discovered again.

Properties

Name	Type	Description
state	Number	state of central manager
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

A event called when centrel manager will restore state

For apps that opt-in to state preservation and restoration, this is the first event invoked when your app is relaunched into the background to complete some Bluetooth-related task. Use this method to synchronize your app's state with the state of the Bluetooth system.

Properties

Name	Type	Description
peripherals	Array<Modules.BLE.Peripheral>	The array contains all of the peripherals connected to the central manager (or had a pending connection) at the time the system terminated the app.
services	Array<Modules.BLE.Service>	an NSArray of service UUIDs containing all the services the central manager was scanning for at the time the system terminated the app.
options	Array<Modules.BLE.Service>	The dictionary contains all of the peripheral scan options in use by the central manager when the system terminated the app.
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.

# didDiscoverPeripheral

Availability

1.0.0

A event called when centrel manager discover peripheral

This method is invoked while scanning, upon the discovery of peripheral by central. A discovered peripheral must be retained in order to use it; otherwise, it is assumed to not be of interest and will be cleaned up by the central manager. For a list of discovered peripherals, see peripherals property

Properties

Name	Type	Description
peripheral	Modules.BLE.Peripheral	object of discovered peripheral
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.

# didConnectPeripheral

Availability

1.0.0

This event is called when a connection initiated by connectPeripheral has succeeded.

Properties

Name	Type	Description
peripheral	Modules.BLE.Peripheral	An object representing the peripheral that connected to the local central manager.
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.

# didFailToConnectPeripheral

Availability

1.0.0

This event is called when a connection initiated by connectPeripheral has failed.

This event is called when a connection initiated by connectPeripheral has failed to complete. As connection attempts do not timeout, the failure of a connection is atypical and usually indicative of a transient issue.

Properties

Name	Type	Description
peripheral	Modules.BLE.Peripheral	An object representing the peripheral that failed to connect.
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.

# didDisconnectPeripheral

Availability

1.0.0

This event is called when a peripheral disconnected.

This event is called upon the disconnection of a peripheral that was connected by connectPeripheral If the disconnection was not initiated by cancelPeripheralConnection, the cause will be detailed in the error parameter. Once this method has been called, no more event will be invoked on peripheral.

Properties

Name	Type	Description
peripheral	Modules.BLE.Peripheral	An object representing the peripheral that disconnected.
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.

# connectionEventDidOccur

Availability

1.0.0

This method is called upon the connection or disconnection of a peripheral that matches any of the options provided in registerForConnectionEventsWithOptions

Properties

Name	Type	Description
event	Number	event value will be Moduels.BLE.CONNECTION_EVENT_TYPE_PEER_DISCONNECTED or Moduels.BLE.CONNECTION_EVENT_TYPE_PEER_CONNECTED
peripheral	Modules.BLE.Peripheral	object of peripheral.
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.

# didUpdateANCSAuthorization

Availability

1.0.0

This event is called when the authorization status changes for a peripheral connected with connectPeripheral with option Modules.BLE.CONNECT_PERIPHERAL_OPTIONS_KEY_REQUIRES_ANCS

Properties

Name	Type	Description
peripheral	Modules.BLE.Peripheral	object of peripheral which disconnected.
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.