# Core Bluetooth

Build direct Bluetooth Low Energy workflows with Core Bluetooth.

- Repository: https://github.com/dpearson2699/swift-ios-skills (1266 stars)
- Category: Writing
- License: see repository
- Last updated: 2026-07-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dpearson2699/swift-ios-skills --skill core-bluetooth -g -a claude-code -y`
Codex: `npx skills add dpearson2699/swift-ios-skills --skill core-bluetooth -g -a codex -y`
Cursor: `npx skills add dpearson2699/swift-ios-skills --skill core-bluetooth -g -a cursor -y`
Gemini CLI: `npx skills add dpearson2699/swift-ios-skills --skill core-bluetooth -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dpearson2699/swift-ios-skills`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](#setup)
- [Central Role: Scanning](#central-role-scanning)
- [Central Role: Connecting](#central-role-connecting)
- [Discovering Services and Characteristics](#discovering-services-and-characteristics)
- [Reading, Writing, and Notifications](#reading-writing-and-notifications)
- [Peripheral Role: Advertising](#peripheral-role-advertising)
- [Background BLE](#background-ble)
- [State Restoration](#state-restoration)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Setup

### Info.plist Keys

| Key | Purpose |
|---|---|
| `NSBluetoothAlwaysUsageDescription` | Required. Explains why the app uses Bluetooth |
| `UIBackgroundModes` with `bluetooth-central` | Background scanning and connecting |
| `UIBackgroundModes` with `bluetooth-peripheral` | Background 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?

The rest: https://github.com/dpearson2699/swift-ios-skills/blob/HEAD/skills/core-bluetooth/SKILL.md