CBPeripheral Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreBluetooth.framework |
| Availability | Available in iOS 5.0 and later. |
| Declared in | CBPeripheral.h |
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 CFUUIDRef 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
-
isConnectedproperty
Accessing the Peripheral’s Received Signal Strength Indicator (RSSI) Data
-
– readRSSI -
RSSIproperty
Properties
delegate
The delegate object specified to receive peripheral events.
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.hisConnected
A Boolean value indicating whether the peripheral is currently connected to the central manager. (read-only)
Discussion
YES if the peripheral is currently connected to the central manager as a result of your successfully calling the connectPeripheral:options: method of the CBCentralManager class. NO if the peripheral is not currently connected to the central manager.
Availability
- Available in iOS 5.0 and later.
Declared In
CBPeripheral.hname
The name of the peripheral. (read-only)
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.
See Also
Declared In
CBPeripheral.hRSSI
The RSSI, in decibels, of the peripheral. (read-only)
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.hservices
A list of services on the peripheral that have been discovered. (read-only)
Discussion
Returns an array of services 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.hUUID
The UUID of the peripheral. (read-only)
Discussion
The first time a central connects to a peripheral, the system assigns the peripheral a UUID, represented by a new CFUUIDRef 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 standard CFUUIDRef UUIDs, instead of by the CBUUID objects that identify a peripheral’s services, characteristics, and characteristic descriptors.
Availability
- Available in iOS 5.0 and later.
Declared In
CBPeripheral.hInstance Methods
discoverCharacteristics:forService:
Discovers the specified characteristics of a service.
Parameters
- characteristicUUIDs
An array of
CBUUIDobjects that you are interested in. Here, eachCBUUIDobject 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.hdiscoverDescriptorsForCharacteristic:
Discovers the descriptors of a 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.hdiscoverIncludedServices:forService:
Discovers the specified included services of a service.
Parameters
- includedServiceUUIDs
An array of
CBUUIDobjects that you are interested in. Here, eachCBUUIDobject 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.hdiscoverServices:
Discovers the specified services of the peripheral.
Parameters
- serviceUUIDs
An array of
CBUUIDobjects that you are interested in. Here, eachCBUUIDobject 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.hreadRSSI
Retrieves the current RSSI value for the peripheral while it is connected to the central manager.
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.hreadValueForCharacteristic:
Retrieves the value of a specified 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.hreadValueForDescriptor:
Retrieves the value of a specified characteristic 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.hsetNotifyValue:forCharacteristic:
Sets notifications or indications for the value of a specified characteristic.
Parameters
- enabled
A Boolean value indicating whether you wish to receive notifications or indications whenever the characteristic’s value changes.
YESif you want to enable notifications or indications for the characteristic’s value.NOif 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.hwriteValue:forCharacteristic:type:
Writes the value of a characteristic.
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.hwriteValue:forDescriptor:
Writes the value of a characteristic 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.hConstants
Characteristic Write Types
Values representing the possible types of writes to a characteristic’s value.
typedef enum {
CBCharacteristicWriteWithResponse = 0,
CBCharacteristicWriteWithoutResponse,
} CBCharacteristicWriteType;
Constants
CBCharacteristicWriteWithResponseA 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.CBCharacteristicWriteWithoutResponseA 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.
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)