CBPeripheral Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreBluetooth.framework
Availability
Available in iOS 5.0 and later.
Companion guide
Declared in
CBPeripheral.h
Related sample code

Overview

The CBPeripheral class represents remote peripheral devices that your app—by means of a central manager (an instance of CBCentralManager)—has discovered advertising or is currently connected to. Peripherals are identified by universally unique identifiers (UUIDs), represented by NSUUID objects. Peripherals may contain one or more services or provide useful information about their connected signal strength.

You use this class to discover, explore, and interact with the services available on a remote peripheral that supports Bluetooth low energy. A service encapsulates the way part of the device behaves. For example, one service of a heart rate monitor may be to expose heart rate data from the monitor’s heart rate sensor. Services themselves are made up of characteristics or included services (references to other services). Characteristics provide further details about a peripheral’s service. For example, the heart rate service just described may contain one characteristic that describes the intended body location of the device’s heart rate sensor and another characteristic that transmits heart rate measurement data. Finally, characteristics contain any number of descriptors that provide more information about the characteristic’s value, such as a human-readable description and a way to format the value.

Tasks

Identifying a Peripheral

Discovering Services

Discovering Characteristics and Characteristic Descriptors

Reading Characteristic and Characteristic Descriptor Values

Writing Characteristic and Characteristic Descriptor Values

Setting Notifications for a Characteristic’s Value

Monitoring a Peripheral’s Connection State

Accessing a Peripheral’s Received Signal Strength Indicator (RSSI) Data

Properties

delegate

The delegate object specified to receive peripheral events.

@property(weak, nonatomic) id<CBPeripheralDelegate> delegate
Discussion

For information about how to implement your peripheral delegate, see CBPeripheralDelegate Protocol Reference.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

identifier

The UUID associated with the peripheral. (read-only)

@property(readonly, nonatomic) NSUUID *identifier
Discussion

The first time a central manager discovers a peripheral, the system assigns the peripheral a UUID, represented by a new NSUUID object. Your app can store this UUID and later provide it to a central manager for use in retrieving this specific peripheral. Peripherals are identified by NSUUID UUIDs instead of by the CBUUID objects that identify a peripheral’s services, characteristics, and characteristic descriptors.

Availability
  • Available in iOS 7.0 and later.
Declared In
CBPeripheral.h

name

The name of the peripheral. (read-only)

@property(retain, readonly) NSString *name
Discussion

The value of this property is a string containing the device name of the peripheral. You can access this property to retrieve a human-readable name of the peripheral. There may be two types of names associated with a peripheral: one that the device advertises and another that the device publishes in its database as its Bluetooth low energy Generic Access Profile (GAP) device name. Although this property may contain either type of name, the GAP device name takes priority. This means that if a peripheral has both types of names associated with it, this property returns its GAP device name.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

RSSI

The RSSI, in decibels, of the peripheral. (read-only)

@property(retain, readonly) NSNumber *RSSI
Discussion

Returns a number, in decibels, that indicates the RSSI of the peripheral while it is currently connected to the central manager. You can use a connected peripheral’s RSSI property to determine the peripheral’s proximity. The default value of this property is nil and is set the first time you successfully call the readRSSI method.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

services

A list of services on the peripheral that have been discovered. (read-only)

@property(retain, readonly) NSArray *services
Discussion

Returns an array of services (represented by CBService objects) that were discovered on the peripheral through a successful call to the discoverServices: method. If you have yet to call the discoverServices: method to discover the services of the peripheral, or if there was an error in doing so, the value of this property is nil.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

state

The current connection state of the peripheral. (read-only)

@property(readonly) CBPeripheralState state
Discussion

The value of this property represents the current connection state of the peripheral. For a list of the possible values of this property, see “Peripheral State.”

Availability
  • Available in iOS 7.0 and later.
Declared In
CBPeripheral.h

Instance Methods

discoverCharacteristics:forService:

Discovers the specified characteristics of a service.

- (void)discoverCharacteristics:(NSArray *)characteristicUUIDs forService:(CBService *)service
Parameters
characteristicUUIDs

An array of CBUUID objects that you are interested in. Here, each CBUUID object represents a UUID that identifies the type of a characteristic you want to discover.

service

The service whose characteristics you want to discover.

Discussion

An array of CBUUID objects—representing characteristic UUIDs—can be provided in the characteristicUUIDs parameter. As a result, the peripheral returns only the characteristics of the service that your app is interested in (recommended). If the characteristicUUIDs parameter is nil, all the characteristics of the service are returned; setting the parameter to nil is considerably slower and is not recommended. When the peripheral discovers one or more characteristics of the specified service, it calls the peripheral:didDiscoverCharacteristicsForService:error: method of its delegate object. If the characteristics of a service are successfully discovered, you can access them through the service’s characteristics property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

discoverDescriptorsForCharacteristic:

Discovers the descriptors of a characteristic.

- (void)discoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic
Parameters
characteristic

The characteristic whose descriptors you want to discover.

Discussion

When the peripheral discovers one or more descriptors of the specified characteristic, it calls the peripheral:didDiscoverDescriptorsForCharacteristic:error: method of its delegate object. If the descriptors of a characteristic are successfully discovered, you can access them through the characteristic’s descriptors property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

discoverIncludedServices:forService:

Discovers the specified included services of a service.

- (void)discoverIncludedServices:(NSArray *)includedServiceUUIDs forService:(CBService *)service
Parameters
includedServiceUUIDs

An array of CBUUID objects that you are interested in. Here, each CBUUID object represents a UUID that identifies the type of included service you want to discover.

service

The service whose included services you want to discover.

Discussion

You can provide an array of CBUUID objects—representing included service UUIDs—in the includedServiceUUIDs parameter. When you do, the peripheral returns only the included services of the service that your app is interested in (recommended). If the includedServicesUUIDs parameter is nil, all the included services of the service are returned; setting the parameter to nil is considerably slower and is not recommended. When the peripheral discovers one or more included services of the specified service, it calls the peripheral:didDiscoverIncludedServicesForService:error: method of its delegate object. If the included services of a service are successfully discovered, you can access them through the service's includedServices property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

discoverServices:

Discovers the specified services of the peripheral.

- (void)discoverServices:(NSArray *)serviceUUIDs
Parameters
serviceUUIDs

An array of CBUUID objects that you are interested in. Here, each CBUUID object represents a UUID that identifies the type of service you want to discover.

Discussion

You can provide an array of CBUUID objects—representing service UUIDs—in the serviceUUIDs parameter. When you do, the peripheral returns only the services of the peripheral that your app is interested in (recommended). If the servicesUUIDs parameter is nil, all the available services of the peripheral are returned; setting the parameter to nil is considerably slower and is not recommended. When the peripheral discovers one or more services, it calls the peripheral:didDiscoverServices: method of its delegate object. If the services of the peripheral are successfully discovered, you can access them through the peripheral’s services property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

readRSSI

Retrieves the current RSSI value for the peripheral while it is connected to the central manager.

- (void)readRSSI
Discussion

When you call this method to retrieve the RSSI of the peripheral while it is currently connected to the central manager, the peripheral calls the peripheralDidUpdateRSSI:error: method of its delegate object. If the RSSI value of the peripheral is successfully retrieved, you can access it through the peripheral’s RSSI property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

readValueForCharacteristic:

Retrieves the value of a specified characteristic.

- (void)readValueForCharacteristic:(CBCharacteristic *)characteristic
Parameters
characteristic

The characteristic whose value you want to read.

Discussion

When you call this method to read the value of a characteristic, the peripheral calls the peripheral:didUpdateValueForCharacteristic:error: method of its delegate object. If the value of the characteristic is successfully retrieved, you can access it through the characteristic’s value property.

Not all characteristics are guaranteed to have a readable value. You can determine whether a characteristic’s value is readable by accessing the relevant properties of the CBCharacteristicProperties enumeration, which are detailed in CBCharacteristic Class Reference.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

readValueForDescriptor:

Retrieves the value of a specified characteristic descriptor.

- (void)readValueForDescriptor:(CBDescriptor *)descriptor
Parameters
descriptor

The characteristic descriptor whose value you want to read.

Discussion

When you call this method to read the value of a characteristic descriptor, the peripheral calls the peripheral:didUpdateValueForDescriptor:error: method of its delegate object. If the value of the characteristic descriptor is successfully retrieved, you can access it through the characteristic descriptor’s value property.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

setNotifyValue:forCharacteristic:

Sets notifications or indications for the value of a specified characteristic.

- (void)setNotifyValue:(BOOL)enabled forCharacteristic:(CBCharacteristic *)characteristic
Parameters
enabled

A Boolean value indicating whether you wish to receive notifications or indications whenever the characteristic’s value changes. YES if you want to enable notifications or indications for the characteristic’s value. NO if you do not want to receive notifications or indications whenever the characteristic’s value changes.

characteristic

The specified characteristic.

Discussion

When you enable notifications for characteristic’s value, the peripheral calls the peripheral:didUpdateNotificationStateForCharacteristic:error: method of its delegate object to notify your app when the characteristic’s value changes. Because it is the peripheral that chooses when to send an update, your app should be prepared to handle them as long as notifications or indications remain enabled. If the specified characteristic is configured to allow both notifications and indications, calling this method enables notifications only. You can disable notifications and indications for a characteristic’s value by calling this method with the enabled parameter set to NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

writeValue:forCharacteristic:type:

Writes the value of a characteristic.

- (void)writeValue:(NSData *)data forCharacteristic:(CBCharacteristic *)characteristic type:(CBCharacteristicWriteType)type
Parameters
data

The value to be written.

characteristic

The characteristic whose value is to be written.

type

The type of write to be executed. For a list of the possible types of writes to a characteristic’s value, see “Characteristic Write Types.”

Discussion

When you call this method to write the value of a characteristic, the peripheral calls the peripheral:didWriteValueForCharacteristic:error: method of its delegate object only if you specified the write type as CBCharacteristicWriteWithResponse. The response you receive through the peripheral:didWriteValueForCharacteristic:error: delegate method indicates whether the write was successful; if the write failed, it details the cause of the failure in an error. If you specify the write type as CBCharacteristicWriteWithoutResponse and the write does not succeed, you are not notified nor do you receive an error indicating the cause of the failure. The data passed into the data parameter is copied, and you can dispose of it after the method returns.

Characteristics may allow only certain type of writes to be performed on their value. To determine which types of writes are permitted to a characteristic’s value, you access the relevant properties of the CBCharacteristicProperties enumeration, which are detailed in CBCharacteristic Class Reference.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

writeValue:forDescriptor:

Writes the value of a characteristic descriptor.

- (void)writeValue:(NSData *)data forDescriptor:(CBDescriptor *)descriptor
Parameters
data

The value to be written.

descriptor

The descriptor whose value is to be written.

Discussion

When you call this method to write the value of a characteristic descriptor, the peripheral calls the peripheral:didWriteValueForDescriptor:error: method of its delegate object. The data passed into the data parameter is copied, and you can dispose of it after the method returns.

You cannot use this method to write the value of a client configuration descriptor (represented by the CBUUIDClientCharacteristicConfigurationString constant), which describes how notification or indications are configured for a characteristic’s value with respect to a client. If you want to manage notifications or indications for a characteristic’s value, you must use the setNotifyValue:forCharacteristic: method instead.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBPeripheral.h

Constants

Characteristic Write Types

Values representing the possible types of writes to a characteristic’s value.

typedef enum {
   CBCharacteristicWriteWithResponse = 0,
   CBCharacteristicWriteWithoutResponse,
} CBCharacteristicWriteType;
Constants
CBCharacteristicWriteWithResponse

A characteristic value is to be written, with a response from the peripheral to indicate whether the write was successful.

If the write is unsuccessful, the peripheral responds with an error detailing the cause of the failure.

Available in iOS 5.0 and later.

Declared in CBPeripheral.h.

CBCharacteristicWriteWithoutResponse

A characteristic value is to be written, without any response from the peripheral to indicate whether the write was successful.

You will not be notified if writing to a characteristic value fails.

Available in iOS 5.0 and later.

Declared in CBPeripheral.h.

Discussion

Characteristic write types have corresponding restrictions on the length of the data that you can write to a characteristic’s value. For the CBCharacteristicWriteWithResponse write type, the restrictions are defined in the Bluetooth 4.0 specification, Volume 3, Part G, Sections 4.9.3–4. For the CBCharacteristicWriteWithoutResponse write type, the restrictions are defined in the Bluetooth 4.0 specification, Volume 3, Part G, Sections 4.9.1–2. In general, when you write with a response, you can write a characteristic value that is longer than what is permitted when you write without a response.

Peripheral State

Values representing the current connection state of the peripheral.

typedef enum {
   CBPeripheralStateDisconnected = 0,
   CBPeripheralStateConnecting,
   CBPeripheralStateConnected,
} CBPeripheralState;
Constants
CBPeripheralStateDisconnected

The peripheral is currently not connected to the central manager.

Available in iOS 7.0 and later.

Declared in CBPeripheral.h.

CBPeripheralStateConnecting

The peripheral is currently in the process of connecting to the central manager.

Available in iOS 7.0 and later.

Declared in CBPeripheral.h.

CBPeripheralStateConnected

The peripheral is currently connected to the central manager.

Available in iOS 7.0 and later.

Declared in CBPeripheral.h.