Logical Labs Bluetooth Low Energy Module for iOS

API Docs for: 1.2.7
Show:

BluetoothLEModule Class

Module: Readme

Item Index

Methods

Properties

Constants

Events

Methods

addService

(
  • params
)
Void

Available since 1.0.0

Publishes a service and its associated characteristic(s) to the local database. If the service contains included services, they must be published first.

Parameters:

  • params Object

    An object with the following properties:

    • primary Boolean

      Defines whether the service is primary.

    • characteristics Array of Objects

      An array of objects describing the characteristics of the service using the following properties:

      • uuid String
        String representing the characteristic's UUID.
      • properties Number
        Integer representing the characteristic's properties; see the CHAR\_PROP\_* constants.
      • permissions Number
        Integer representing the characteristic's permissions; see the CHAR\_PERM\_* constants.
      • [data] TiBuffer optional
        A TiBuffer object, holding the value of the characteristic. Optional.

Returns:

Void:

cancelPeripheralConnection

(
  • peripheral:
)
Void

Available since 1.0.0

Cancels an active or pending connection to the specified peripheral. This command is non-blocking, and any commands that are still pending to the peripheral may or may not complete.

It extremely important to note that canceling a connection does not guarantee the immediate disconnection of the underlying physical link. This can be caused by a variety of different factors, including other application(s) that hold an outstanding connection to the peripheral. However, in this situation, you will still immediately receive a disconnectedPeripheral event.

Parameters:

Returns:

Void:

connectPeripheral

(
  • params
)
Void

Available since 1.0.0

Initiates a connection to the specified peripheral. Connection attempts never time out and, depending on the outcome, will result in a connectedPeripheral or failedToConnectPeripheral event.

Pending attempts are cancelled automatically upon deallocation of the peripheral, and explicitly via the cancelPeripheralConnection method.

Parameters:

  • params Object

    An object with the following properties:

    • peripheral: Peripheral

      The object representing the peripheral.

Returns:

Void:

createBeaconRegion

(
  • params
)
Void

Available since 1.1.0

Creates a BeaconRegion object that can be used to start advertising an iBeacon.

Parameters:

  • params Object

    An object with the following properties (see the properties of the BeaconRegion class for details):

    • identifier String

      A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application.

    • UUID String

      The UUID of the beacon.

    • [major] Number optional

      The major number of the beacon. If not specified, the major and minor numbers of the beacon are ignored.

    • [minor] Number optional

      The minor number of the beacon. If not specified, the minor number of the beacon is ignored.

    • [notifyEntryStateOnDisplay=false] Boolean optional

      When set to true, the beacon notifications will be sent only when the user turns on the display and the device is already inside the region.

Returns:

Void:

initCentralManager

(
  • [params]
)
Void

Available since 1.0.0

Initializes the module's internal central manager. This function must be called in an app that acts as a central before any other function can be used.

Parameters:

  • [params] Object optional

    An object with the following properties:

    • [showPowerAlert=true] Boolean optional

      Boolean indicating that the system should, if Bluetooth is powered off when the central is instantialized, display a warning dialog to the user. This parameter was introduced in version 1.1.0 of the module.

    • [restoreIdentifier] String optional

      A string containing a unique identifier for the central manager that is being instantiated. This identifier is used by the system to identify a specific central manager instance for restoration and, therefore, must remain the same for subsequent application executions in order for the manager to be restored. See also the centralWillRestoreState event. This parameter was introduced in version 1.1.0 of the module.

Returns:

Void:

initPeripheralManager

(
  • [params]
)
Void

Available since 1.0.0

Initializes the module's internal peripheral manager object. This function must be called in an app that acts as a peripheral before any other function can be used.

Parameters:

  • [params] Object optional

    An object with the following properties:

    • [showPowerAlert=true] Boolean optional

      Boolean indicating that the system should, if Bluetooth is powered off when the peripheral is instantialized, display a warning dialog to the user. This parameter was introduced in version 1.1.0 of the module.

    • [restoreIdentifier] String optional

      A string containing a unique identifier for the peripheral manager that is being instantiated. This identifier is used by the system to identify a specific peripheral manager instance for restoration and, therefore, must remain the same for subsequent application executions in order for the manager to be restored. See also the peripheralWillRestoreState event. This parameter was introduced in version 1.1.0 of the module.

Returns:

Void:

releaseCentralManager

() Void

Available since 1.0.0

Releases the module's internal central manager. This frees up the related resources, and effectively (after a time-out) tears down the connection on the peripheral side as well.

Returns:

Void:

releasePeripheralManager

() Void

Available since 1.0.0

Releases the module's internal peripheral manager object. This frees up the related resources, and effectively (after a time-out) tears down the connection on the central side as well.

Returns:

Void:

removeAllServices

() Void

Available since 1.0.0

Removes all published services from the local database.

Returns:

Void:

removeService

(
  • service
)
Void

Available since 1.0.0

Removes a published service from the local database. If the service is included by other service(s), they must be removed first.

Parameters:

Returns:

Void:

requestAlwaysAuthorization

() Void

Available since 1.2.7

When the current authorization status is LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationAlwaysUsageDescription key in your app’s Info.plist file. The presence of that key is required when calling this method.

After the status is determined, the app will receive an locationManagerAuthorizationChanged event.

If the current authorization status is anything other than LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this function does nothing.

Important: You must call this function or the requestWhenInUseAuthorization function prior to using beacon services.

Requesting “Always” authorization is discouraged by Apple because of the potential negative impacts to user privacy. You should request this level of authorization only when doing so offers a genuine benefit to the user.

Returns:

Void:

requestRegionState

(
  • params
)
Void

Available since 1.2.4

Retrieves the state of a region asynchronously.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

requestWhenInUseAuthorization

() Void

Available since 1.2.7

When the current authorization status is LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationWhenInUseUsageDescription key in your app’s Info.plist file. The presence of that key is required when calling this method.

After the status is determined, the app will receive an locationManagerAuthorizationChanged event.

If the current authorization status is anything other than LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this function does nothing.

Important: You must call this function or the requestAlwaysAuthorization function prior to using beacon services.

If the user grants “when-in-use” authorization to your app, your app can range beacons but not monitor beacon regions.

Returns:

Void:

respondToRequest

(
  • params
)
Void

Available since 1.0.0

Used to respond to request(s) received via the receivedReadRequest or receivedWriteRequests event.

Parameters:

  • params Object

    An object with the following properties:

    • request Request

      The request to which the peripheral is responding.

    • result Number

      The result code; see the ATT_* constants.

Returns:

Void:

retrieveConnectedPeripherals

() Void deprecated

Deprecated: Use {{#crossLink "BluetoothLEModule/retrieveConnectedPeripheralsWithServices:method"}} {{/crossLink}} instead.

Available since 1.0.0

Retrieves all peripherals that are connected to the system. Note that this set can include peripherals which were connected by other applications, which will need to be connected locally via connectPeripheral method.

The result of this operation is returned via the retrievedConnectedPeripherals event.

Returns:

Void:

retrieveConnectedPeripheralsWithServices

(
  • params
)
Void

Available since 1.1.0

Retrieves all peripherals that are connected to the system and implement any of the services listed in serviceUUIDs. Note that this set can include peripherals which were connected by other applications, which will need to be connected locally via connectPeripheral method.

The result of this operation is returned via the retrievedConnectedPeripherals event.

Parameters:

  • params Object
    • serviceUUIDs Array of Strings

Returns:

Void:

retrieveMonitoredRegions

() Void

Available since 1.2.5

Retrieves the currently monitored beacon regions. Note that this function will initialize the location manager if it's not already initialized. Thus this function, unlike the monitoredRegions property, is guaranteed to return the correct result in every case. In particular, this function is a key component of the restoration process that needs to take place when the app is restarted into the background in response to a beacon related event.

Important: Call this function after you attached the appropriate event handlers for the enteredRegion, exitedRegion, and regionStateUpdated events. If the app was restarted due to a beacon related event, that event will be fired immediately after this function is called.

Async function; returns the results in a retrievedMonitoredRegions event.

Returns:

Void:

retrievePeripherals

(
  • params
)
Void deprecated

Deprecated: Use retrievePeripheralsWithIdentifiers instead.

Available since 1.0.0

Attempts to retrieve the Peripheral object(s) that correspond to the specified UUIDs.

The result of this operation is returned via the retrievedPeripherals event.

Parameters:

  • params Object

    An object with the following properties:

    • UUIDs Array of Strings

      UUIDs of peripherals to retrieve.

Returns:

Void:

retrievePeripheralsWithIdentifiers

(
  • params
)
Array of Peripherals

Available since 1.1.0

Attempts to retrieve the Peripheral object(s) that correspond to the specified UUIDs.

Parameters:

  • params Object

    An object with the following properties:

    • UUIDs Array of Strings

      UUIDs of peripherals to retrieve.

Returns:

Array of Peripherals:

setDesiredConnectionLatency

(
  • params
)
Void

Available since 1.0.0

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:

  • params Object

    An object with the following properties:

    • latency Number

      The desired connection latency.

    • central Central

      A connected central

Returns:

Void:

startAdvertising

(
  • [params]
)
Void

Available since 1.0.0

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

Important: You must call the initPeripheralManager function first!

Note: In the Beacons module, this function can only be used to advertise beacon regions.

Supported advertising data types are ADVERT_DATA_KEY_LOCAL_NAME and ADVERT_DATA_KEY_SERVICE_UUIDS. 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.

Parameters:

  • [params] Object optional

    Object containing the data to be advertised.

    • ADVERT_DATA_KEY_LOCAL_NAME String

      Local name. Note that ADVERT_DATA_KEY_LOCAL_NAME is the constant whose value (!) is to be used as the key, like so: params[BluetoothLE.ADVERT_DATA_KEY_LOCAL_NAME] = ...

    • ADVERT_DATA_KEY_SERVICE_UUIDS Array of Strings

      Service UUIDs. Note that ADVERT_DATA_KEY_SERVICE_UUIDS is the constant whose value (!) is to be used as the key, like so: params[BluetoothLE.ADVERT_DATA_KEY_SERVICE_UUIDS] = ...

    • beaconRegion BeaconRegion

      An object created using the createBeaconRegion method. If this parameter is present, other parameters except measuredPower are ignored.

    • [measuredPower] Number optional

      The received signal strength indicator (RSSI) value (measured in decibels) for the device. This value represents the measured strength of the beacon from one meter away and is used during ranging. If not specified, the default value for the device will be used.

Returns:

Void:

startRangingBeacons

(
  • params
)
Void

Available since 1.1.0

Starts the delivery of notifications for beacons in the specified region.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

startRegionMonitoring

(
  • params
)
Void

Available since 1.1.0

Starts monitoring the specified region.

You must call this method once for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. Note that "identifier" literally means the identifier property, not the UUID! The regions you add using this method are stored in the monitoredRegions property.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

startScan

(
  • params
)
Void

Available since 1.0.0

Starts scanning for peripherals. If the UUIDs parameter is not specified, all discovered peripherals will be returned, regardless of their supported services (not recommended). If the central is already scanning with different service UUIDs or options, the provided parameters will replace them.

The result of this operation is returned via the discoveredPeripheral event.

Applications are allowed to scan while backgrounded, with two caveats: the scan must specify one or more service UUIDs, and the CENTRAL_MANAGER_SCAN_OPTION_KEY_ALLOW_DUPLICATES scan option will be ignored.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

stopAdvertising

() Void

Available since 1.0.0

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

Returns:

Void:

stopRangingBeacons

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions.

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

stopRegionMonitoring

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions.

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

stopScan

() Void

Available since 1.0.0

Stops scanning for peripherals.

Returns:

Void:

updateValue

(
  • params
)
Boolean

Available since 1.0.0

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

Parameters:

  • params Object

    An object with the following properties:

    • characteristic Characteristic
    • data TiBuffer

      The value of the characteristic.

    • [centrals] Array of Central objects optional

      The list of centrals that need to be updated. If not specified, all subscribed centrals will be updated.

Returns:

Boolean:

True if the update could be sent, or false if the underlying transmit queue is full. 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.

Properties

backgroundDataAuthorizationStatus

Number read-only

Available since 1.1.0

The current authorization status for sharing data while backgrounded. You can use it to detect restricted access and hide UI instead of prompting for access. Possible values are the BACKGROUND_DATA_AUTHORIZATION_STATUS_* constants.

centralManagerState

Number read-only

Available since 1.0.0

State of the module's internal central manager. Its value is one of the CENTRAL_MANAGER_STATE_* constants.

filterDuplicateBeacons

Boolean

Available since 1.1.2

Determines whether the beacons included with the rangedBeacons event will be filtered for duplicates. Defaults to false. A beacon is considered a duplicate of another if their UUID, major, and minor numbers are all the same.

isAdvertising

Boolean read-only

Available since 1.0.0

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

locationManagerAuthorizationStatus

Number read-only

Available since 1.1.2

Authorization status of the Location Manager for this app. Its value is one of the LOCATION_MANAGER_AUTHORIZATION_STATUS_* constants.

monitoredRegions

Array of BeaconRegions read-only

Available since 1.1.0

The beacon regions monitored by all location manager objects. Note that this property will be undefined when the app is restarted into the background. Use the retrieveMonitoredRegions function to retrieve the list of monitored regions in that case.

peripheralManagerState

Number read-only

Available since 1.0.0

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

rangedRegions

Array of BeaconRegions read-only

Available since 1.1.2

The regions currently being tracked using ranging.

restoredCentralManagerIdentifiers

Array of Strings read-only

Available since 1.2.5

Each string in the array represents the restoration identifier for a central manager object. This is the same string you assigned to the restoreIdentifier parameter of the {{#crossLink "BluetoothLEModule/initCentralManager:method}}{{/crossLink}} function.

restoredPeripheralManagerIdentifiers

Array of Strings read-only

Available since 1.2.5

Each string in the array represents the restoration identifier for a peripheral manager object. This is the same string you assigned to the restoreIdentifier parameter of the {{#crossLink "BluetoothLEModule/initPeripheralManager:method}}{{/crossLink}} function.

wasLocationLaunch

Boolean read-only

Available since 1.2.5

True if the application was launched due to a location event. In the context of this module, a "location event" is an event related to beacons. Note however that other type of location events might also trigger the app to be launched.

Constants

ADVERT_DATA_KEY_IS_CONNECTABLE

String

Available since 1.1.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is a Boolean indicating whether or not the advertising event type was connectable. This can be used to determine whether or not a peripheral is connectable in that instant.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_LOCAL_NAME

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is a string, representing the local name of a peripheral.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_MANUFACTURER_DATA

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is a TiBuffer, representing the manufacturing data of the peripheral.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_OVERFLOW_SERVICE_UUIDS

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is an array of strings representing service UUIDs that were found in the "overflow" area of the advertising data. Due to the nature of the data stored in this area, UUIDs listed here are "best effort" and may not always be accurate.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_SERVICE_DATA

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is an object containing service specific advertisement data. The property names of the object are service UUIDs, and the values of the properties are TiBuffer objects.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_SERVICE_UUIDS

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is an array of strings representing service UUIDs.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_SOLICITED_SERVICE_UUIDS

String

Available since 1.1.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is a list of one or more Strings, representing service UUIDs.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ADVERT_DATA_KEY_TX_POWER_LEVEL

String

Available since 1.0.0

The Bluetooth Low Energy specification defines several fields that may be present in the advertisement data. The ADVERT_DATA_* constants can be used as keys to define the value of these fields when advertising using the startAdvertising method, or to access the values when advertising data is received in the discoveredPeripheral event.

The value associated with this particular key is a number, representing the transmit power of a peripheral.

Note that iOS version 7.0 only supports the ADVERT_DATA_KEY_SERVICE_UUIDS and ADVERT_DATA_KEY_LOCAL_NAME fields as parameters to the startAdvertising method.

ALREADY_ADVERTISING_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_ATTRIBUTE_NOT_FOUND_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_ATTRIBUTE_NOT_LONG_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_ERROR_DOMAIN

String

Available since 1.0.0

One of the possible values of the errorDomain property of an event in case an error occurs.

ATT_INSUFFICIENT_AUTHENTICATION_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INSUFFICIENT_AUTHORIZATION_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INSUFFICIENT_ENCRYPTION_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INSUFFICIENT_RESOURCES_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INVALID_ATTRIBUTE_VALUE_LENGTH_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INVALID_HANDLE_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INVALID_OFFSET_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_INVALID_PDU_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_PREPARE_QUEUE_FULL_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_READ_NOT_PERMITTED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_REQUEST_NOT_SUPPORTED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_SUCCESS

Number

Available since 1.0.0

Constants to be used for the result parameter of the respondToRequest to indicate success.

ATT_UNLIKELY_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_UNSUPPORTED_GROUP_TYPE_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ATT_WRITE_NOT_PERMITTED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

BACKGROUND_DATA_AUTHORIZATION_STATUS_AUTHORIZED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has authorized this application to share data while backgrounded.

BACKGROUND_DATA_AUTHORIZATION_STATUS_DENIED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has explicitly denied this application from sharing data while backgrounded.

BACKGROUND_DATA_AUTHORIZATION_STATUS_NOT_DETERMINED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has not yet made a choice with regards to this application.

BACKGROUND_DATA_AUTHORIZATION_STATUS_RESTRICTED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. This application is not authorized to share data while backgrounded. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

BEACON_PROXIMITY_FAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_IMMEDIATE

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_NEAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_UNKNOWN

Number

Available since 1.1.0

One of the possible values of the proximity property.

CENTRAL_MANAGER_SCAN_OPTION_KEY_ALLOW_DUPLICATES

String

Available since 1.0.0

Use this constant as a key in the options parameter of the startScan. The value associated with this key is a number, indicating whether the scan should run without duplicate filtering. By default, multiple discoveries of the same peripheral are coalesced into a single discovery event. Disabling this filtering can have an adverse effect on battery life and should only be used if necessary.

CENTRAL_MANAGER_STATE_POWERED_OFF

Number

Available since 1.0.0

Bluetooth is currently powered off.

CENTRAL_MANAGER_STATE_POWERED_ON

Number

Available since 1.0.0

Bluetooth is currently powered on and available to use.

CENTRAL_MANAGER_STATE_RESETTING

Number

Available since 1.0.0

The connection with the system service was momentarily lost, update imminent.

CENTRAL_MANAGER_STATE_UNAUTHORIZED

Number

Available since 1.0.0

The application is not authorized to use the Bluetooth Low Energy Central role.

CENTRAL_MANAGER_STATE_UNINITIALIZED

Number

Available since 1.0.0

This state is reported when the central manager object maintained by the module does not (yet) exist, i.e. before initCentralManager is called or after releaseCentralManager is called.

CENTRAL_MANAGER_STATE_UNKNOWN

Number

Available since 1.0.0

State unknown, update imminent.

CENTRAL_MANAGER_STATE_UNSUPPORTED

Number

Available since 1.0.0

The platform doesn't support the Bluetooth Low Energy Central role.

CHAR_PERM_NONE

Number

Available since 1.0.0

Characteristic has no permissions.

CHAR_PERM_READ_ENCRYPTED

Number

Available since 1.0.0

Characteristic is readable by trusted devices.

CHAR_PERM_READABLE

Number

Available since 1.0.0

Characteristic is readable.

CHAR_PERM_WRITE_ENCRYPTED

Number

Available since 1.0.0

Characteristic is writeable by trusted devices.

CHAR_PERM_WRITEABLE

Number

Available since 1.0.0

Characteristic is writeable.

CHAR_PROP_BROADCAST

Number

Available since 1.0.0

Permits broadcasts of the characteristic value using a characteristic configuration descriptor. Not allowed for local characteristics.

CHAR_PROP_EXTENDED_PROPERTIES

Number

Available since 1.0.0

If set, additional characteristic properties are defined in the characteristic extended properties descriptor. Not allowed for local characteristics

CHAR_PROP_INDICATE

Number

Available since 1.0.0

Permits indications of the characteristic value.

CHAR_PROP_INDICATE_ENCRYPTION_REQUIRED

Number

Available since 1.0.0

If set, only trusted devices can enable indications of the characteristic value.

CHAR_PROP_NOTIFY

Number

Available since 1.0.0

Permits notifications of the characteristic value, without a response.

CHAR_PROP_NOTIFY_ENCRYPTION_REQUIRED

Number

Available since 1.0.0

If set, only trusted devices can enable notifications of the characteristic value.

CHAR_PROP_READ

Number

Available since 1.0.0

Permits reads of the characteristic value.

CHAR_PROP_SIGNED_WRITES

Number

Available since 1.0.0

Permits signed writes of the characteristic value.

CHAR_PROP_WRITE

Number

Available since 1.0.0

Permits writes of the characteristic value.

CHAR_PROP_WRITE_WITHOUT_RESPONSE

Number

Available since 1.0.0

Permits writes of the characteristic value, without a response.

CHARACTERISTIC_TYPE_WRITE_WITH_RESPONSE

Number

Available since 1.0.0

Use this constant for the type parameter of the writeValueForCharacteristic method. It specifies that the write to be performed requires a response.

CHARACTERISTIC_TYPE_WRITE_WITHOUT_RESPONSE

Number

Available since 1.0.0

Use this constant for the type parameter of the writeValueForCharacteristic method. It specifies that the write to be performed does not require a response.

CONNECTION_TIMEOUT_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

ERROR_DOMAIN

String

Available since 1.0.0

One of the possible values of the errorDomain property of an event in case an error occurs.

INVALID_HANDLE_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

INVALID_PARAMETERS_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. User has authorized this application to share data while backgrounded.

LOCATION_MANAGER_AUTHORIZATION_STATUS_DENIED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user explicitly denied the use of location services for this application or location services are currently disabled in Settings.

LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user has not yet made a choice regarding whether this application can use location services.

LOCATION_MANAGER_AUTHORIZATION_STATUS_RESTRICTED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

NOT_CONNECTED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

OPERATION_CANCELLED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

OUT_OF_SPACE_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

PERIPHERAL_DISCONNECTED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

PERIPHERAL_MANAGER_CONNECTION_LATENCY_HIGH

Number

Available since 1.0.0

Prioritizes extending battery life over rapid communication.

PERIPHERAL_MANAGER_CONNECTION_LATENCY_LOW

Number

Available since 1.0.0

Prioritizes rapid communication over battery life.

PERIPHERAL_MANAGER_CONNECTION_LATENCY_MEDIUM

Number

Available since 1.0.0

A balance between communication frequency and battery life.

PERIPHERAL_MANAGER_STATE_POWERED_OFF

Number

Available since 1.0.0

Bluetooth is currently powered off.

PERIPHERAL_MANAGER_STATE_POWERED_ON

Number

Available since 1.0.0

Bluetooth is currently powered on and available to use.

PERIPHERAL_MANAGER_STATE_RESETTING

Number

Available since 1.0.0

The connection with the system service was momentarily lost, update imminent.

PERIPHERAL_MANAGER_STATE_UNAUTHORIZED

Number

Available since 1.0.0

The application is not authorized to use the Bluetooth Low Energy Peripheral role.

PERIPHERAL_MANAGER_STATE_UNINITIALIZED

Number

Available since 1.0.0

This state is reported when the peripheral manager object maintained by the module does not (yet) exist, i.e. before initPeripheralManager is called or after releasePeripheralManager is called.

PERIPHERAL_MANAGER_STATE_UNKNOWN

Number

Available since 1.0.0

State unknown, update imminent.

PERIPHERAL_MANAGER_STATE_UNSUPPORTED

Number

Available since 1.0.0

The platform doesn't support the Bluetooth Low Energy Peripheral role.

PERIPHERAL_STATE_CONNECTED

Number

Available since 1.1.0

One of the possible values of the state property of a peripheral object.

PERIPHERAL_STATE_CONNECTING

Number

Available since 1.1.0

One of the possible values of the state property of a peripheral object.

PERIPHERAL_STATE_DISCONNECTED

Number

Available since 1.1.0

One of the possible values of the state property of a peripheral object.

REGION_STATE_INSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_OUTSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_UNKOWN

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

UNKNOWN_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

UUID_NOT_ALLOWED_ERROR

Number

Available since 1.0.0

One of the possible values of the errorCode property of an event in case an error occurs.

Events

addedService

Available since 1.0.0

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

Event Payload:

  • service Service

    An object representing the service that was added.

  • errorCode Number

    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

centralManagerStateChange

Available since 1.0.0

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

Event Payload:

  • state Number

    An integer describing the state of the module's internal central manager. See the CENTRAL_MANAGER_STATE_* constants.

centralSubscribed

Available since 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.

Event Payload:

  • central Central

    An object representing the central that subscribed.

  • characteristic Characteristic

    An object representintg the characteristic to which the central subscribed.

centralUnsubscribed

Available since 1.0.0

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

Event Payload:

  • central Central

    An object representing the central that unsubscribed.

  • characteristic Characteristic

    An object representintg the characteristic from which the central unsubscribed.

centralWillRestoreState

Available since 1.1.0

Note: This event is currently not being fired, due to a limitation in Titanium. See the "iOS to iOS" sample app for a potential workaround.

Fired when iOS relaunches the app into the background (after iOS terminated it to free up resources) to complete some Bluetooth-related task. Use this event to synchronize your app's state with the state of the Bluetooth system.

See also the restoreIdentifier parameter of the initCentralManager method.

Event Payload:

  • peripherals Array of Peripherals

    An array of Peripheral objects containing all peripherals that were connected or pending connection at the time the application was terminated by the system. When possible, all known information for each peripheral will be restored, including any discovered services, characteristics and descriptors, as well as characteristic notification states.

  • serviceUUIDs Array of Strings

    An array of strings holding the UUIDs of the service(s) being scanned for at the time the application was terminated by the system.

  • scanOptions Object

    An object (dictionary) containing the scan options at the time the application was terminated by the system.

connectedPeripheral

Available since 1.0.0

This event is fired when a connection initiated by the connectPeripheral method has succeeded.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that connected to the local central manager.

disconnectedPeripheral

Available since 1.0.0

Fired when a peripheral disconnects from the local central manager.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that disconnected.

  • errorCode Number

    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

discoveredPeripheral

Available since 1.0.0

Fired when a peripheral is discovered.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that was discovered by the local central manager.

  • RSSI Number

    The current RSSI of the peripheral, in dBm. A value of 127 is reserved and indicates the RSSI was not available.

  • advertisementData Object

    An object holding the advertisement data (see the ADVERT_DATA_KEY_* constants).

enteredRegion

Available since 1.1.0

This event is fired when the user enters a monitored region.

Note: In our testing we found this event to be unreliable. This seems to be a problem with the native SDK. We recommend to use the regionStateUpdated event instead.

Event Payload:

exitedRegion

Available since 1.1.0

This event is fired when the user exits a monitored region.

Note: In our testing we found this event to be unreliable. This seems to be a problem with the native SDK. We recommend to use the regionStateUpdated event instead.

Event Payload:

failedToConnectPeripheral

Available since 1.0.0

This event is fired when a connection initiated by the connectPeripheral method fails.

Event Payload:

  • peripheral Peripheral

    An object representing the peripheral that failed to connect.

  • errorCode Number

    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

locationManagerAuthorizationChanged

Available since 1.1.2

This event is fired when the authorization status of the Location Manager changes.

Event Payload:

  • status Number

    The status code; one of the LOCATION_MANAGER_AUTHORIZATION_STATUS_* constants.

moduleReady

Available since 1.2.0

This event is fired when the module is ready. On iOS, this is a formality; On Android, you need to wait for this event before calling any methods on the module.

peripheralManagerStateChange

Available since 1.0.0

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

Event Payload:

  • state Number

    An integer describing the state of the module's internal peripheral manager. See the PERIPHERAL_MANAGER_STATE_* constants.

peripheralWillRestoreState

Available since 1.1.0

Note: This event is currently not being fired, due to a limitation in Titanium. See the "iOS to iOS" sample app for a potential workaround.

Fired when iOS relaunches the app into the background (after iOS terminated it to free up resources) to complete some Bluetooth-related task. Use this event to synchronize your app's state with the state of the Bluetooth system.

See also the restoreIdentifier parameter of the initPeripheralManager method.

Event Payload:

  • services Array of Services

    An array of Service objects containing all services that were published to the local database at the time the application was terminated by the system. All the information about a service is restored, including any included services, characteristics, characteristic descriptors, and subscribed centrals.

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

proximityChange

Available since 1.1.2

Use this event to determine which beacons have changed their proximity since the last update. This event is fired whenever the rangedBeacons event is fired, provided that the proximity of any of the ranged beacons has changed since the last rangedBeacons event.

Event Payload:

  • beacons Array of Beacons

    An array of Beacon objects representing the beacons that changed their proximity since the last update.

rangedBeacons

Available since 1.1.0

Use this event to determine which beacons are in range.

See also the filterDuplicateBeacons property.

Event Payload:

  • beacons Array of Beacons

    An array of Beacon objects representing the beacons currently in range. You can use the information in these objects to determine the range of each beacon and its identifying information.

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

readyToUpdateSubscribers

Available since 1.0.0

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.

receivedReadRequest

Available since 1.0.0

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

Event Payload:

  • request Request

    An object representing the request.

receivedWriteRequests

Available since 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.

Event Payload:

  • requests Array of Request objects

    Request objects describing the incoming write requests.

regionStateUpdated

Available since 1.1.0

This event is fired when the state of a monitored region is updated.

Event Payload:

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

  • state Number

    One of the REGION_STATE_* constants.

retrievedConnectedPeripherals

Available since 1.0.0

This event returns the result of the retrieveConnectedPeripherals method.

Event Payload:

  • service Service

    A Service object representing the service that was added.

  • errorCode Number

    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

retrievedMonitoredRegions

Available since 1.2.5

Returns the result of the retrieveMonitoredRegions function.

Event Payload:

  • beaconRegions Array of BeaconRegions

    An array of BeaconRegion objects, representing the currently monitored beacon regions.

retrievedPeripherals

Available since 1.0.0

This event returns the result of the retrievePeripherals method.

Event Payload:

  • peripherals Array of Peripheral objects

startedAdvertising

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.

Event Payload:

  • errorCode Number

    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