Starting Up a Central Manager

Because a CBCentralManager object is the Core Bluetooth object-oriented representation of a local central device, you allocate and initialize a central manager instance before you can perform any Bluetooth low energy transactions. You initialize your central manager by calling its initWithDelegate:queue:options: method:

    myCentralManager =

        [[CBCentralManager alloc] initWithDelegate:self queue:nil options:nil];

In this example, self is set as the delegate to receive any central role events. By specifying the dispatch queue as nil, the central manager dispatches central role events using the main queue.

When you create a central manager, the central manager calls the centralManagerDidUpdateState: method of its delegate object. You must implement this delegate method to ensure that Bluetooth low energy is supported and available to use on the central device. For more information about how to implement this delegate method, see CBCentralManagerDelegate Protocol Reference.

Discovering Peripheral Devices That Are Advertising

Once initialized, the central manager’s first task is peripheral discovery. As mentioned in Centrals Discover and Connect to Peripherals That Are Advertising, peripherals make their presence known by advertising. Your app discovers nearby peripheral devices that are advertising by calling the central manager’s scanForPeripheralsWithServices:options: method:

    [myCentralManager scanForPeripheralsWithServices:nil options:nil];

Every time the central manager discovers a peripheral, it calls the centralManager:didDiscoverPeripheral:advertisementData:RSSI: method of its delegate object. The newly discovered peripheral is returned as a CBPeripheral object. If you plan to connect to the discovered peripheral, keep a strong reference to it so the system does not deallocate it. The following example shows a scenario where you use a class property to maintain a reference to the discovered peripheral:

- (void)centralManager:(CBCentralManager *)central

 didDiscoverPeripheral:(CBPeripheral *)peripheral

     advertisementData:(NSDictionary *)advertisementData

                  RSSI:(NSNumber *)RSSI {

    NSLog(@"Discovered %@", peripheral.name);

    self.discoveredPeripheral = peripheral;

    ...

If you expect to connect to multiple devices, you might instead keep an NSArray of discovered peripherals. In any case, once you’ve found all the peripheral devices that you’re interested in connecting to, stop scanning for other devices in order to save power:

    [myCentralManager stopScan];

Connecting to a Peripheral Device After You’ve Discovered It

After you discover a peripheral device advertising services you are interested in, you request a connection to the peripheral by calling the central manager’s connectPeripheral:options: method, naming the discovered peripheral that you want to connect to:

    [myCentralManager connectPeripheral:peripheral options:nil];

If the connection request is successful, the central manager calls the centralManager:didConnectPeripheral: method of its delegate object. Before you start interacting with the peripheral, you set its delegate to ensure that the delegate receives the appropriate callbacks:

- (void)centralManager:(CBCentralManager *)central

  didConnectPeripheral:(CBPeripheral *)peripheral {

    NSLog(@"Peripheral connected");

    peripheral.delegate = self;

    ...

Discovering the Services of a Peripheral That You’re Connected To

After you have established a connection to a peripheral, you can explore its data. The first step in exploring what a peripheral has to offer is discovering its available services. Because there are size restrictions on the amount of data a peripheral can advertise, you may discover that a peripheral has more services than what it advertises (in its advertising packets). You can discover all of the services that a peripheral offers by calling the peripheral’s discoverServices: method, like this:

    [peripheral discoverServices:nil];

When the specified services are discovered, the peripheral (the CBPeripheral object you’re connected to) calls the peripheral:didDiscoverServices: method of its delegate object. Core Bluetooth creates an array of CBService objects—one for each service that is discovered on the peripheral. As the following shows, you can implement this delegate method to access the array of discovered services:

- (void)peripheral:(CBPeripheral *)peripheral

didDiscoverServices:(NSError *)error {

    for (CBService *service in peripheral.services) {

        NSLog(@"Discovered service %@", service);

        ...

    }

    ...

Discovering the Characteristics of a Service

When you find a service that you are interested in, the next step in exploring what a peripheral has to offer is discovering all of the service’s characteristics. Discovering all of the characteristics of a service is as simple as calling the peripheral’s discoverCharacteristics:forService: method, specifying the appropriate service, like this:

    NSLog(@"Discovering characteristics for service %@", interestingService);

    [peripheral discoverCharacteristics:nil forService:interestingService];

The peripheral calls the peripheral:didDiscoverCharacteristicsForService:error: method of its delegate object when the characteristics of the specified service are discovered. Core Bluetooth creates an array of CBCharacteristic objects—one for each characteristic that is discovered. The following example shows how you can implement this delegate method to simply log every characteristic that is discovered:

- (void)peripheral:(CBPeripheral *)peripheral

didDiscoverCharacteristicsForService:(CBService *)service

             error:(NSError *)error {

    for (CBCharacteristic *characteristic in service.characteristics) {

        NSLog(@"Discovered characteristic %@", characteristic);

        ...

    }

    ...

Retrieving the Value of a Characteristic

A characteristic contains a single value that represents information about a peripheral’s service. For example, a temperature measurement characteristic of a health thermometer service may have a value that indicates a temperature in Celsius. You can retrieve the value of a characteristic by reading it directly or by subscribing to it.

    NSLog(@"Reading value for characteristic %@", interestingCharacteristic);

    [peripheral readValueForCharacteristic:interestingCharacteristic];

- (void)peripheral:(CBPeripheral *)peripheral

didUpdateValueForCharacteristic:(CBCharacteristic *)characteristic

             error:(NSError *)error {

    NSData *data = characteristic.value;

    // parse the data as needed

    ...

    [peripheral setNotifyValue:YES forCharacteristic:interestingCharacteristic];

- (void)peripheral:(CBPeripheral *)peripheral

didUpdateNotificationStateForCharacteristic:(CBCharacteristic *)characteristic

             error:(NSError *)error {

    if (error) {

        NSLog(@"Error changing notification state: %@",

           [error localizedDescription]);

    }

    ...

Writing the Value of a Characteristic

Sometimes it makes sense to write the value of a characteristic. For example, if your app interacts with a Bluetooth low energy digital thermostat, you may want to provide the thermostat with a value at which to set the room’s temperature. If a characteristic’s value is writeable, you can write its value with data (an instance of NSData) by calling the peripheral’s writeValue:forCharacteristic:type: method, like this:

    NSLog(@"Writing value for characteristic %@", interestingCharacteristic);

    [peripheral writeValue:dataToWrite forCharacteristic:interestingCharacteristic

        type:CBCharacteristicWriteWithResponse];

When you write the value of a characteristic, you specify what type of write you want to perform. In the example above, the write type is CBCharacteristicWriteWithResponse, which instructs the peripheral to let your app know whether or not the write succeeds by calling the peripheral:didWriteValueForCharacteristic:error: method of its delegate object. You implement this delegate method to handle the error condition, as the following example shows:

- (void)peripheral:(CBPeripheral *)peripheral

didWriteValueForCharacteristic:(CBCharacteristic *)characteristic

             error:(NSError *)error {

    if (error) {

        NSLog(@"Error writing characteristic value: %@",

            [error localizedDescription]);

    }

    ...

If instead you specify the write type as CBCharacteristicWriteWithoutResponse, the write operation is performed as best-effort, and delivery is neither guaranteed nor reported. The peripheral does not call any delegate method. For more information about the write types that are supported in the Core Bluetooth framework, see the CBCharacteristicWriteType enumeration in CBPeripheral Class Reference.