iOS Developer Library

Developer

CoreBluetooth Framework Reference CBPeripheral Class Reference

Options
Deployment Target:

On This Page
Language:

CBPeripheral

Inherits From


Conforms To


Import Statement


Swift

import CoreBluetooth

Objective-C

@import CoreBluetooth;

Availability


Available in iOS 5.0 and later

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.

  • UUID UUID Available in iOS 5.0 through iOS 7.1 Property

    The UUID of the peripheral. (read-only)

    Deprecation Statement

    Use the identifier property instead.

    Declaration

    Objective-C

    @property(readonly, nonatomic) CFUUIDRef UUID

    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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Availability

    Available in iOS 5.0 through iOS 7.1

    Deprecated in iOS 7.0

  • identifier identifier Available in iOS 7.0 through iOS 7.1 Property

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Availability

    Available in iOS 7.0 through iOS 7.1

  • name name Property

    The name of the peripheral. (read-only)

    Declaration

    Swift

    var name: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • delegate delegate Property

    The delegate object specified to receive peripheral events.

    Declaration

    Swift

    weak var delegate: CBPeripheralDelegate!

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Discovers the specified services of the peripheral.

    Declaration

    Swift

    func discoverServices(_ serviceUUIDs: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Discovers the specified included services of a service.

    Declaration

    Swift

    func discoverIncludedServices(_ includedServiceUUIDs: [AnyObject]!, forService service: CBService!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • services services Property

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

    Declaration

    Swift

    var services: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Discovers the specified characteristics of a service.

    Declaration

    Swift

    func discoverCharacteristics(_ characteristicUUIDs: [AnyObject]!, forService service: CBService!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Discovers the descriptors of a characteristic.

    Declaration

    Swift

    func discoverDescriptorsForCharacteristic(_ characteristic: CBCharacteristic!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Retrieves the value of a specified characteristic.

    Declaration

    Swift

    func readValueForCharacteristic(_ characteristic: CBCharacteristic!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Retrieves the value of a specified characteristic descriptor.

    Declaration

    Swift

    func readValueForDescriptor(_ descriptor: CBDescriptor!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Writes the value of a characteristic.

    Declaration

    Swift

    func writeValue(_ data: NSData!, forCharacteristic characteristic: CBCharacteristic!, type type: CBCharacteristicWriteType)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Writes the value of a characteristic descriptor.

    Declaration

    Swift

    func writeValue(_ data: NSData!, forDescriptor descriptor: CBDescriptor!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setNotifyValue(_ enabled: Bool, forCharacteristic characteristic: CBCharacteristic!)

    Objective-C

    - (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. YEStrue if you want to enable notifications or indications for the characteristic’s value. NOfalse 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 NOfalse.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • isConnected isConnected (iOS 7.0) Property

    A Boolean value indicating whether the peripheral is currently connected to the central manager. (read-only)

    Deprecation Statement

    Use the state property instead.

    Declaration

    Objective-C

    @property(readonly) BOOL isConnected

    Discussion

    YEStrue 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. NOfalse if the peripheral is not currently connected to the central manager.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 7.0

  • state state Property

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

    Declaration

    Swift

    var state: CBPeripheralState { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    func readRSSI()

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • RSSI RSSI (iOS 8.0) Property

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

    Declaration

    Swift

    var RSSI: NSNumber! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 8.0

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

    Declaration

    Swift

    enum CBCharacteristicWriteType : Int { case WithResponse case WithoutResponse }

    Objective-C

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

    Constants

    • WithResponse

      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

    • WithoutResponse

      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

    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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later

  • Values representing the current connection state of the peripheral.

    Declaration

    Swift

    enum CBPeripheralState : Int { case Disconnected case Connecting case Connected }

    Objective-C

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

    Constants

    • Disconnected

      CBPeripheralStateDisconnected

      The peripheral is currently not connected to the central manager.

      Available in iOS 7.0 and later

    • Connecting

      CBPeripheralStateConnecting

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

      Available in iOS 7.0 and later

    • Connected

      CBPeripheralStateConnected

      The peripheral is currently connected to the central manager.

      Available in iOS 7.0 and later

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later