Core Bluetooth

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

Build direct Bluetooth Low Energy workflows with Core Bluetooth. Use when implementing BLE central or peripheral GATT communication, scanning or connecting with CBCentralManager, discovering services and characteristics, reading/writing/subscribing with CBPeripheral, publishing local services with CBPeripheralManager, handling Bluetooth authorization, background BLE modes, state restoration, write flow control, or CBUUID-based workflows. For privacy-preserving accessory setup/picker flows, use accessorysetupkit first and return here for post-setup GATT communication.

Instructions onlySoftware Development
AI-generated overview

Guides implementing Core Bluetooth BLE central and peripheral workflows in Apple apps.

What it does
Provides a structured reference for building Bluetooth Low Energy features with Core Bluetooth: creating a CBCentralManager, scanning, connecting, discovering services and characteristics, and reading, writing or subscribing to values. It also covers the peripheral role with CBPeripheralManager, background BLE modes, state restoration, common mistakes and a review checklist. Code examples are in Swift, with extended patterns in a bundled reference file.
When to use it
Use when implementing or reviewing BLE GATT communication in an Apple app, whether acting as central or peripheral. Also useful for handling Bluetooth authorization, background scanning or advertising, state restoration, and write flow control. For privacy-preserving accessory setup flows, the document says to use accessorysetupkit first and return here for post-setup GATT communication.
Requirements
No scripts; instructions and code examples only. Requires an Apple platform project using the Core Bluetooth framework, Info.plist keys such as NSBluetoothAlwaysUsageDescription, and optional UIBackgroundModes entries. No credentials or network access needed.

Core Bluetooth

Scan for, connect to, and exchange data with Bluetooth Low Energy (BLE) devices. Covers the central role (scanning and connecting to peripherals), the peripheral role (advertising services), background modes, and state restoration. Use accessorysetupkit for privacy-preserving accessory discovery and setup; use this skill for direct Core Bluetooth GATT communication.

Contents

Setup

Info.plist Keys

KeyPurpose
NSBluetoothAlwaysUsageDescriptionRequired. Explains why the app uses Bluetooth
UIBackgroundModes with bluetooth-centralBackground scanning and connecting
UIBackgroundModes with bluetooth-peripheralBackground advertising

Bluetooth Authorization

Core Bluetooth has no explicit permission request API. Add NSBluetoothAlwaysUsageDescription, create the manager when the app is ready for Bluetooth access, then check manager.authorization and manager.state. Treat .denied and .restricted as terminal until the user changes Settings; wait for .poweredOn before scanning, connecting, advertising, or publishing services.

Central Role: Scanning

Creating the Central Manager

Always wait for the poweredOn state before scanning.

swift
import CoreBluetooth
final class BluetoothManager: NSObject, CBCentralManagerDelegate {    private var centralManager: CBCentralManager!    private var discoveredPeripheral: CBPeripheral?
    override init() {        super.init()        centralManager = CBCentralManager(delegate: self, queue: nil)    }
    func centralManagerDidUpdateState(_ central: CBCentralManager) {        guard central.state == .poweredOn else { return }        startScanning()    }}

Scanning for Peripherals

Scan for specific service UUIDs to save power. Pass nil to discover all peripherals (not recommended in production).

swift
let heartRateServiceUUID = CBUUID(string: "180D")
func startScanning() {    centralManager.scanForPeripherals(        withServices: [heartRateServiceUUID],        options: [CBCentralManagerScanOptionAllowDuplicatesKey: false]    )}
func centralManager(    _ central: CBCentralManager,    didDiscover peripheral: CBPeripheral,    advertisementData: [String: Any],    rssi RSSI: NSNumber) {    guard RSSI.intValue > -70 else { return } // Filter weak signals
    // IMPORTANT: Retain the peripheral -- it will be deallocated otherwise    discoveredPeripheral = peripheral    centralManager.stopScan()    centralManager.connect(peripheral, options: nil)}

Central Role: Connecting

swift
func centralManager(    _ central: CBCentralManager,    didConnect peripheral: CBPeripheral) {    peripheral.delegate = self    peripheral.discoverServices([heartRateServiceUUID])}
func centralManager(    _ central: CBCentralManager,    didDisconnectPeripheral peripheral: CBPeripheral,    timestamp: CFAbsoluteTime,    isReconnecting: Bool,    error: Error?) {    if isReconnecting {        // System is automatically reconnecting        return    }    // Handle disconnection -- optionally reconnect    discoveredPeripheral = nil}

Discovering Services and Characteristics

Implement CBPeripheralDelegate to walk the service/characteristic tree.

swift
extension BluetoothManager: CBPeripheralDelegate {    func peripheral(        _ peripheral: CBPeripheral,        didDiscoverServices error: Error?    ) {        guard let services = peripheral.services else { return }        for service in services {            peripheral.discoverCharacteristics(nil, for: service)        }    }
    func peripheral(        _ peripheral: CBPeripheral,        didDiscoverCharacteristicsFor service: CBService,        error: Error?    ) {        guard let characteristics = service.characteristics else { return }        for characteristic in characteristics {            if characteristic.properties.contains(.notify) {                peripheral.setNotifyValue(true, for: characteristic)            }            if characteristic.properties.contains(.read) {                peripheral.readValue(for: characteristic)            }        }    }}

Reading, Writing, and Notifications

Reading a Value

swift
func peripheral(    _ peripheral: CBPeripheral,    didUpdateValueFor characteristic: CBCharacteristic,    error: Error?) {    guard let data = characteristic.value else { return }
    switch characteristic.uuid {    case CBUUID(string: "2A37"):        if let heartRate = parseHeartRate(data) {            print("Heart rate: \(heartRate) bpm")        }    case CBUUID(string: "2A19"):        let batteryLevel = data.first.map { Int($0) } ?? 0        print("Battery: \(batteryLevel)%")    default:        break    }}
private func parseHeartRate(_ data: Data) -> Int? {    guard data.count >= 2 else { return nil }    let flags = data[0]    let is16Bit = (flags & 0x01) != 0    if is16Bit {        guard data.count >= 3 else { return nil }        return Int(data[1]) | (Int(data[2]) << 8)    } else {        return Int(data[1])    }}

Writing a Value

swift
func writeValue(_ data: Data, to characteristic: CBCharacteristic,                on peripheral: CBPeripheral,                preferResponse: Bool = true) {    let type: CBCharacteristicWriteType    if preferResponse, characteristic.properties.contains(.write) {        type = .withResponse    } else if characteristic.properties.contains(.writeWithoutResponse),              peripheral.canSendWriteWithoutResponse {        type = .withoutResponse    } else if characteristic.properties.contains(.write) {        type = .withResponse    } else {        return    }
    guard data.count <= peripheral.maximumWriteValueLength(for: type) else { return }    peripheral.writeValue(data, for: characteristic, type: type)}
// Confirmation callback for .withResponse writes.func peripheral(    _ peripheral: CBPeripheral,    didWriteValueFor characteristic: CBCharacteristic,    error: Error?) {    if let error {        print("Write failed: \(error.localizedDescription)")    }}
// Resume queued .withoutResponse writes here.func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {}

Subscribing to Notifications

swift
// Subscribeperipheral.setNotifyValue(true, for: characteristic)
// Unsubscribeperipheral.setNotifyValue(false, for: characteristic)
// Confirmationfunc peripheral(    _ peripheral: CBPeripheral,    didUpdateNotificationStateFor characteristic: CBCharacteristic,    error: Error?) {    if characteristic.isNotifying {        print("Now receiving notifications for \(characteristic.uuid)")    }}

Peripheral Role: Advertising

Publish services from the local device using CBPeripheralManager.

swift
final class BLEPeripheralManager: NSObject, CBPeripheralManagerDelegate {    private var peripheralManager: CBPeripheralManager!    private let serviceUUID = CBUUID(string: "12345678-1234-1234-1234-123456789ABC")    private let charUUID = CBUUID(string: "12345678-1234-1234-1234-123456789ABD")
    override init() {        super.init()        peripheralManager = CBPeripheralManager(delegate: self, queue: nil)    }
    func peripheralManagerDidUpdateState(_ peripheral: CBPeripheralManager) {        guard peripheral.state == .poweredOn else { return }        setupService()    }
    private func setupService() {        let characteristic = CBMutableCharacteristic(            type: charUUID,            properties: [.read, .notify],            value: nil,            permissions: [.readable]        )
        let service = CBMutableService(type: serviceUUID, primary: true)        service.characteristics = [characteristic]        peripheralManager.add(service)    }
    func peripheralManager(        _ peripheral: CBPeripheralManager,        didAdd service: CBService,        error: Error?    ) {        guard error == nil else { return }        peripheralManager.startAdvertising([            CBAdvertisementDataServiceUUIDsKey: [serviceUUID],            CBAdvertisementDataLocalNameKey: "MyDevice"        ])    }}

Background BLE

Background Central Mode

Add bluetooth-central to UIBackgroundModes. In the background:

  • Scanning must specify one or more service UUIDs; nil scans are foreground-only
  • Scan options, including CBCentralManagerScanOptionAllowDuplicatesKey, have no effect

Background Peripheral Mode

Add bluetooth-peripheral to UIBackgroundModes. In the background:

  • Without this mode, published service contents are disabled while suspended
  • The local name is not advertised
  • Service UUIDs move to the overflow area and require explicit service scans

State Restoration

State restoration allows the system to re-create your central or peripheral manager after your app is terminated and relaunched for a BLE event.

Central Manager State Restoration

swift
// 1. Create with a restoration identifiercentralManager = CBCentralManager(    delegate: self,    queue: nil,    options: [CBCentralManagerOptionRestoreIdentifierKey: "myCentral"])
// 2. Implement the restoration delegate methodfunc centralManager(    _ central: CBCentralManager,    willRestoreState dict: [String: Any]) {    if let peripherals = dict[CBCentralManagerRestoredStatePeripheralsKey]        as? [CBPeripheral] {        for peripheral in peripherals {            // Re-assign delegate and retain            peripheral.delegate = self            discoveredPeripheral = peripheral        }    }    let restoredServices = dict[CBCentralManagerRestoredStateScanServicesKey]        as? [CBUUID]    let restoredOptions = dict[CBCentralManagerRestoredStateScanOptionsKey]        as? [String: Any]    // Resume scanning with restoredServices/restoredOptions if still needed.}

Peripheral Manager State Restoration

swift
peripheralManager = CBPeripheralManager(    delegate: self,    queue: nil,    options: [CBPeripheralManagerOptionRestoreIdentifierKey: "myPeripheral"])
func peripheralManager(    _ peripheral: CBPeripheralManager,    willRestoreState dict: [String: Any]) {    let services = dict[CBPeripheralManagerRestoredStateServicesKey]        as? [CBMutableService]    let advertisement = dict[CBPeripheralManagerRestoredStateAdvertisementDataKey]        as? [String: Any]    // Reconnect app state to restored services/advertisement as needed.}

Common Mistakes

MistakeFix
Scan/connect before .poweredOnStart BLE work from centralManagerDidUpdateState.
Discovered peripheral is not retainedHold a strong reference through connection and discovery.
Production scan passes nil servicesFilter by the service UUIDs the feature needs.
Service discovery begins before didConnectAdvance only from delegate callbacks and handle failure/disconnect paths.
Writes ignore characteristic properties or payload limitsSelect the supported write type, respect maximumWriteValueLength, and gate .withoutResponse on canSendWriteWithoutResponse.

Review Checklist

  • NSBluetoothAlwaysUsageDescription added to Info.plist
  • All BLE operations gated on centralManagerDidUpdateState returning .poweredOn
  • Discovered peripherals retained with a strong reference
  • Scanning uses specific service UUIDs (not nil) in production
  • CBPeripheralDelegate set before calling discoverServices
  • Characteristic properties checked before read/write/notify
  • Write payloads stay within maximumWriteValueLength(for:)
  • .withoutResponse writes honor canSendWriteWithoutResponse
  • Background mode (bluetooth-central or bluetooth-peripheral) added if needed
  • State restoration identifier set if app needs relaunch-on-BLE-event support
  • willRestoreState delegate method implemented when using state restoration
  • Scanning stopped after discovering the target peripheral
  • Disconnection handled with optional automatic reconnect logic
  • Write type matches characteristic properties (.withResponse vs .withoutResponse)

References

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/core-bluetoothat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago
Core Bluetooth Agent Skill | SourceWeft