Logical Labs Bluetooth Low Energy Module for iOS

API Docs for: 1.2.7
Show:

Peripheral Class

Module: Readme

Representation of a remote peripheral.

You can't directly create Peripheral objects. Knowing the name and/or UUID of a peripheral is not sufficient to create a connection, especially because the UUID is a locally assigned artificial identifier, not something that globally identifies a peripheral (like for example a MAC address would).

You can use the retrievePeripheralsWithIdentifiers function to retrieve Peripheral objects that were previously created on the device. It is important to understand, however, that this function really just retrieves already existing objects, doesn't create new ones. So, for example, if you execute this function right after you reboot the phone then chances are you won't get anything back.

Methods

discoverCharacteristics

(
  • params
  • [param.UUIDs]
)
Void

Available since 1.0.0

Discovers the specified characteristic(s) of a service.

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

Parameters:

  • params Object

    An object with the following properties:

  • [param.UUIDs] Array of Strings optional

    An array of UUID strings, representing the characteristic types to be discovered. If not specified all characteristics of the service will be discovered, which is considerably slower and not recommended.

Returns:

Void:

discoverDescriptorsForCharacteristic

(
  • characteristic
)
Void

Available since 1.0.0

Discovers the descriptor(s) of a characteristic.

The result of this operation is returned via the Peripheral/discoveredDescriptorsForCharacteristics:event event.

Parameters:

Returns:

Void:

discoverIncludedServices

(
  • params
)
Void

Available since 1.0.0

Discovers the specified included service(s) of a service.

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

Parameters:

  • params Object

    An object with the following properties:

    • service Service

      A GATT service.

    • [serviceUUIDs] Array of Strings optional

      An array of UUID strings, representing the included service types to be discovered. If not specified, all included services will be discovered, which is considerably slower and not recommended.

Returns:

Void:

discoverServices

(
  • serviceUUIDStrings
)
Void

Available since 1.0.0

Discovers available service(s) on the peripheral.

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

Parameters:

  • serviceUUIDStrings Array of Strings

Returns:

Void:

readRSSI

() Void

Available since 1.0.0

Retrieves the current RSSI of the link.

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

Returns:

Void:

readValueForCharacteristic

(
  • characteristic
)
Void

Available since 1.0.0

Reads the value of a characteristic.

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

Parameters:

Returns:

Void:

readValueForDescriptor

(
  • descriptor
)
Void

Available since 1.0.0

Reads the value of a descriptor.

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

Parameters:

Returns:

Void:

subscribeToCharacteristic

(
  • characteristic
)
Void

Available since 1.0.0

Enables notifications/indications for a characteristic. If the characteristic allows both, notifications will be used.

Parameters:

Returns:

Void:

unsubscribeFromCharacteristic

(
  • characteristic
)
Void

Available since 1.0.0

Disables notifications/indications for a characteristic.

Parameters:

Returns:

Void:

writeValueForCharacteristic

(
  • params
)
Void

Available since 1.0.0

Writes a value to a characteristic.

Parameters:

Returns:

Void:

writeValueForDescriptor

(
  • params
)
Void

Available since 1.0.2

Writes the value of a descriptor.

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

Parameters:

  • params Object

Returns:

Void:

Properties

isConnected

Boolean read-only

Available since 1.0.0

Whether or not the peripheral is currently connected.

name

String read-only

Available since 1.0.0

The name of the peripheral.

RSSI

Number read-only

Available since 1.0.0

The most recently read RSSI, in decibels. Note that you need to call the readRSSI method to update this value, and the result of that operation is returned via the updatedRSSI event.

services

Array of Service objects read-only

Available since 1.0.0

A list of Service objects that have been discovered on the peripheral.

state

Number read-only

Available since 1.1.0

The current connection state of the peripheral. Possible values are PERIPHERAL_STATE_DISCONNECTED, PERIPHERAL_STATE_CONNECTING, and PERIPHERAL_STATE_CONNECTED.

UUID

String read-only

Available since 1.0.0

Once a peripheral has been connected at least once by the system, it is assigned a UUID. This UUID can be stored and later provided to the retrievePeripherals method.

Events

discoveredCharacteristics

Available since 1.0.0

This event returns the result of a call to the discoverCharacteristics method. If the characteristic(s) were read successfully, they can be retrieved via the service property's characteristics property.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • service Service

    The service for which the characteristics were discovered.

  • 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 present if an error occurred.

discoveredDescriptionForCharacteristics

Available since 1.0.0

This event returns the result of a call to the discoverDescriptorsForCharacteristic method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • characteristic Characteristic
  • 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 present if an error occurred.

discoveredIncludedServices

Available since 1.0.0

This event returns the result of a call to the discoverIncludedServices method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • 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 present if an error occurred.

discoveredServices

Available since 1.0.0

This event returns the result of a call to the discoverServices method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • 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 present if an error occurred.

invalidatedServices

Available since 1.0.0

This event is fired when the services of the peripheral change.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • services Array of Service objects

    The services that have been invalidated.

updatedName

Available since 1.0.0

This event is fired when the name of the peripheral changes.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

updatedNotificationStateForCharacteristics

Available since 1.0.0

This event returns the result of a call to the subscribeToCharacteristic or unsubscribeFromCharacteristic method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • characteristic Characteristic
  • 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 present if an error occurred.

updatedRSSI

Available since 1.0.0

This event returns the result of a call to the readRSSI method. The event handler function for this event can query the RSSI property of the peripheral object provided in the source property of the event object.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • 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 present if an error occurred.

updatedValueForCharacteristic

Available since 1.0.0

This event is fired after a call to the readValueForCharacteristic method, or upon receipt of a notification/indication.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • characteristic Characteristic
  • value TiBuffer

    The characteristic's value at the time the update was received. Note that due to the asynchronous nature of the Titanium messaging facility, the value of the characteristic may have been already updated again by the time the JavaScript code receives this event and consequently value and characteristic.value may be different!

  • 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 present if an error occurred.

updatedValueForDescriptor

Available since 1.0.0

This event returns the result of a call to the readValueForDescriptor method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • descriptor Descriptor

    The Descriptor object corresponding to the descriptor parameter of the delegate method.

  • 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 present if an error occurred.

wroteValueForCharacteristic

Available since 1.0.0

This event returns the result of a call to the writeValueForCharacteristic method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • characteristic Characteristic
  • 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 present if an error occurred.

wroteValueForDescriptor

Available since 1.0.0

This event returns the result of a call to the writeValueForDescriptor method.

Event Payload:

  • source Peripheral

    The peripheral sending the event.

  • descriptor Descriptor

    The object representing the descriptor that was changed.

  • 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 present if an error occurred.