SuperAPI AI Directory

core-bluetooth

General & other

View repository

Updated 10-16 05:52

About this skill

Core Bluetooth

Implement Bluetooth Low Energy (BLE) communication on iOS using CBCentralManager (connecting to accessories) and CBPeripheralManager (advertising as an accessory). Targets Swift 6.3 / iOS 26+.

Contents

  • Permissions and Background Modes
  • Central vs Peripheral Roles
  • Core Communication Contract
  • State Restoration and MTU
  • Route by Task
  • Common Mistakes
  • Review Checklist
  • References

Permissions and Background Modes

Declare NSBluetoothAlwaysUsageDescription in Info.plist. For background execution, enable capabilities in Signing & Capabilities > Background Modes:

  • Uses Bluetooth LE accessories: Central role in background (bluetooth-central)
  • Acts as a Bluetooth LE accessory: Peripheral role in background (bluetooth-peripheral)
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app requires Bluetooth to connect to external fitness sensors.</string>
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

Central vs Peripheral Roles

Feature Central (CBCentralManager) Peripheral (CBPeripheralManager)
Primary Task Scans, connects, and consumes GATT services Publishes services, advertises, responds to requests
Discovery scanForPeripherals(withServices:options:) startAdvertising(_:)
Data Read/Write readValue(for:) / writeValue(_:for:type:) respond(to:withResult:)
Updates Subscribes with setNotifyValue(true, for:) updateValue(_:for:onSubscribedCentrals:)
Queue Dedicated serial DispatchQueue Dedicated serial DispatchQueue

Core Communication Contract

  1. Wait for .poweredOn: Never call scan, connect, or advertise until centralManagerDidUpdateState(_:) reports .poweredOn.
  2. Retain discovered peripherals: You must store a strong reference to CBPeripheral instances returned in didDiscover. If released, connection drops immediately.
  3. Scan with service UUIDs: In background mode, scanning without explicit CBUUID filters is disabled by iOS to preserve battery.
  4. Discover narrowly: Pass specific [CBUUID] arrays to discoverServices and discoverCharacteristics rather than nil to avoid slow full-GATT enumeration.
  5. Honor write types: Use .withResponse for acknowledged writes (peripheral(_:didWriteValueFor:error:)); use .withoutResponse only when canSendWriteWithoutResponse is verified.

State Restoration and MTU

  • State Restoration: Pass CBCentralManagerOptionRestoreIdentifierKey during manager initialization to allow iOS to relaunch the app in the background when a Bluetooth event occurs. Handle restoration in centralManager(_:willRestoreState:).
  • MTU & Packet Sizing: Check peripheral.maximumWriteValueLength(for:) before sending large payloads. The default BLE MTU is 23 bytes (20 payload bytes). Do not assume 512-byte MTU without checking.

Route by Task

Common Mistakes

  • Initiating Bluetooth scanning before centralManagerDidUpdateState(_:) transitions to .poweredOn.
  • Failing to retain the CBPeripheral reference during connection, leading to silent drops.
  • Scanning without explicit service CBUUIDs in background mode (system ignores unfiltered background scans).
  • Ignoring canSendWriteWithoutResponse, causing silent packet drops during burst writes.
  • Performing heavy parsing or UI operations on the Core Bluetooth dispatch queue.

Review Checklist

  • NSBluetoothAlwaysUsageDescription provided in Info.plist
  • Required UIBackgroundModes configured (bluetooth-central / bluetooth-peripheral)
  • State checked for .poweredOn before issuing commands
  • Connected peripherals strongly referenced by the manager
  • Service and characteristic discovery scoped to specific [CBUUID]
  • Write type matches characteristic properties (.withResponse vs .withoutResponse)
  • State restoration identifier configured and handled in willRestoreState
  • Core Bluetooth delegate runs on a dedicated serial queue, with UI updates dispatched to @MainActor
  • Maximum packet size validated with maximumWriteValueLength

References