Modules.BLE.CentralManager

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

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

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

Properties

isScanning

1.0.0

1.0.0

1.0.0

Type: Boolean

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

peripherals

1.0.0

1.0.0

1.0.0

Type: Array<Modules.BLE.Peripheral>

All discovered peripherals

state

1.0.0

1.0.0

1.0.0

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

cancelPeripheralConnection

1.0.0

1.0.0

1.0.0

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	Summary	Optional
peripheral	Modules.BLE.Peripheral	peripheral object which connnection will be canceled	No

Returns: void

connectPeripheral

1.0.0

1.0.0

1.0.0

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	Summary	Optional
peripheral	Modules.BLE.Peripheral	peripheral object to connect	No
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_*	Yes

Returns: void

createPeripheral

1.0.0

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

Parameters:

Name	Type	Summary	Optional
address	String	address of the remote bluetooth device.	No

Returns: Modules.BLE.Peripheral

isAccessFineLocationPermissionGranted

1.0.0

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: Boolean — Returns true if the ACCESS_FINE_LOCATION permission is granted

registerForConnectionEvents

1.0.0

1.0.0

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	Summary	Optional
peripherals	Array<String>	A list of peripherals UUIDs.	Yes
services	Array<String>	A list of services UUIDs.	Yes

Returns: void

requestAccessFineLocationPermission

1.0.0

Request for the ACCESS_FINE_LOCATION.

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

retrieveConnectedPeripheralsWithServices

1.0.0

1.0.0

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

Parameters:

Name	Type	Summary	Optional
UUIDs	Array<String>	A list of service UUIDs.	No

Returns: Array<Modules.BLE.Peripheral>

retrievePeripheralsWithIdentifiers

1.0.0

1.0.0

Returns a list of known peripherals by their identifiers.

Parameters:

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

Returns: Array<Modules.BLE.Peripheral>

startScan

1.0.0

1.0.0

1.0.0

Starts scanning for peripherals.

Parameters:

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

Returns: void

stopScan

1.0.0

1.0.0

1.0.0

Stops scanning for peripherals.

Returns: void

Events

connectionEventDidOccur

1.0.0

1.0.0

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

Event Properties:

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

didConnectPeripheral

1.0.0

1.0.0

1.0.0

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

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

Event Properties:

Name	Type	Summary
peripheral	Modules.BLE.Peripheral	An object representing the peripheral that connected to the local central manager.

didDisconnectPeripheral

1.0.0

1.0.0

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.

Event Properties:

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

didDiscoverPeripheral

1.0.0

1.0.0

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

Event Properties:

Name	Type	Summary
peripheral	Modules.BLE.Peripheral	object of discovered peripheral

didFailToConnectPeripheral

1.0.0

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.

Event Properties:

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

didUpdateANCSAuthorization

1.0.0

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

Event Properties:

Name	Type	Summary
peripheral	Modules.BLE.Peripheral	object of peripheral which disconnected.

didUpdateState

1.0.0

1.0.0

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.

Event Properties:

Name	Type	Summary
state	Number	state of central manager

willRestoreState

1.0.0

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.

Event Properties:

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