Core Bluetooth

Communicate with Bluetooth 4.0 low-energy devices.


The Core Bluetooth framework provides the classes needed for your apps to communicate with devices that are equipped with Bluetooth low energy wireless technology.

Do not subclass any of the classes of the Core Bluetooth framework. Overriding these classes is unsupported and results in undefined behavior.


Bluetooth Classic Connections

Using Core Bluetooth Classic

Use Core Bluetooth APIs to discover and communicate with a Bluetooth Classic device.


class CBATTRequest

The CBATTRequest class represents Attribute Protocol (ATT) read and write requests from remote central devices (represented by CBCentral objects). Remote centrals use these ATT requests to read and write characteristic values on local peripherals (represented by CBPeripheralManager objects). Local peripherals, on the other hand, use the properties of CBATTRequest objects to respond to the read and write requests appropriately, using the respond(to:withResult:) method of the CBPeripheralManager class.

class CBAttribute

CBAttribute is an abstract base class that defines behavior common to the collection of objects that represent aspects of services offered by a peripheral.

class CBCentral

The CBCentral class represents remote central devices that have connected to an app implementing the peripheral role on a local device. That is, when you are implementing the peripheral role using the CBPeripheralManager class, centrals that connect to your local peripheral are represented as CBCentral objects. Remote centrals are identified by universally unique identifiers (UUIDs), represented by NSUUID objects.

class CBCentralManager

CBCentralManager objects are used to manage discovered or connected remote peripheral devices (represented by CBPeripheral objects), including scanning for, discovering, and connecting to advertising peripherals.

class CBCharacteristic

CBCharacteristic and its subclass CBMutableCharacteristic represent further information about a peripheral’s service. CBCharacteristic objects in particular represent the characteristics of a remote peripheral’s service (remote peripheral devices are represented by CBPeripheral objects). A characteristic contains a single value and any number of descriptors describing that value. The properties of a characteristic determine how the value of the characteristic can be used and how the descriptors can be accessed.

class CBDescriptor

CBDescriptor and it subclass CBMutableDescriptor represent a descriptor of a peripheral’s characteristic. CBDescriptor objects in particular represent the descriptors of a remote peripheral’s characteristic (remote peripheral devices are represented by CBPeripheral objects). Descriptors provide further information about a characteristic’s value. For example, they may describe the value in human-readable form and describe how the value should be formatted for presentation purposes. Characteristic descriptors also indicate whether a characteristic’s value is configured on a server (a peripheral) to indicate or notify a client (a central) when the value of the characteristic changes.

class CBManager

The abstract base class for Core Bluetooth manager objects (central and peripheral).

class CBMutableCharacteristic

CBMutableCharacteristic objects represent the characteristics of a local peripheral’s service (local peripheral devices are represented by CBPeripheralManager objects). This class adds write access to many of the properties in the CBCharacteristic class it inherits from.

class CBMutableDescriptor

CBMutableDescriptor objects represent the descriptors of a local peripheral’s characteristic (local peripheral devices are represented by CBPeripheralManager objects).

class CBMutableService

The CBMutableService class adds write access to all of the properties in the CBService class it inherits from. You use this class to create a service or an included service on a local peripheral device (represented by a CBPeripheralManager object). After you create a service, you can add it to the peripheral’s local database using the add(_:) method of the CBPeripheralManager class. After you add a service to the peripheral’s local database, the service is cached and you can no longer make changes to it.

class CBPeer

The CBPeer class is an abstract base class that defines common behavior for objects representing remote devices. You typically do not create instances of either CBPeer or its concrete subclasses. Instead, the system creates them for you during the process of peer discovery.

class CBPeripheral

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.

class CBPeripheralManager

CBPeripheralManager objects are used to manage published services within the local peripheral device’s Generic Attribute Profile (GATT) database and to advertise these services to central devices (represented by CBCentral objects). While a service is in the database, it is visible to, and can be accessed by, any connected central. That said, if your app has not specified the bluetooth-peripheral background mode, the contents of its services become disabled when it is in the background or in a suspended state; any remote central trying to access the service’s characteristic value or characteristic descriptors receives an error.

class CBService

CBService and its subclass CBMutableService represent a peripheral’s service—a collection of data and associated behaviors for accomplishing a function or feature of a device (or portions of that device). CBService objects in particular represent services of a remote peripheral device (represented by a CBPeripheral object). Services are either primary or secondary and may contain a number of characteristics or included services (references to other services).

class CBUUID

Instances of the CBUUID class represent the 128-bit universally unique identifiers (UUIDs) of attributes used in Bluetooth low energy communication, such as a peripheral’s services, characteristics, and characteristic descriptors. This class provides a number of factory methods for dealing with long UUIDs when developing your app. For example, instead of passing around the string representation of a 128-bit Bluetooth low energy attribute in your code, you can create a CBUUID object that represents it, and pass that around instead.


protocol CBCentralManagerDelegate

The CBCentralManagerDelegate protocol defines the methods that a delegate of a CBCentralManager object must adopt. The optional methods of the protocol allow the delegate to monitor the discovery, connectivity, and retrieval of peripheral devices. The only required method of the protocol indicates the availability of the central manager, and is called when the central manager’s state is updated.

protocol CBPeripheralDelegate

The delegate of a CBPeripheral object must adopt the CBPeripheralDelegate protocol. The delegate uses this protocol’s methods to monitor the discovery, exploration, and interaction of a remote peripheral’s services and properties. There are no required methods in this protocol.

protocol CBPeripheralManagerDelegate

The delegate of a CBPeripheralManager object must adopt the CBPeripheralManagerDelegate protocol, a protocol consisting of numerous optional methods and one required method. The protocol’s optional methods are used by the delegate to verify publishing and advertising, and to monitor read, write, and subscription requests from remote central devices. The protocol’s required method, which indicates whether the peripheral manager is available, is called when the peripheral manager’s state is updated.



struct CBAttributePermissions

Values representing the read, write, and encryption permissions for a characteristic’s value.

struct CBCharacteristicProperties

Values representing the possible properties of a characteristic. Since characteristic properties can be combined, a characteristic may have multiple property values set.

See Also

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software