home / skills / nonameplum / agent-skills / corebluetooth

corebluetooth skill

safe

This skill helps you implement Core Bluetooth central and peripheral workflows, ensuring poweredOn state, proper discovery, connection, and GATT operations.

npx playbooks add skill nonameplum/agent-skills --skill corebluetooth

Review the files below or copy the command above to add this skill to your agents.

Files (10)

SKILL.md

2.5 KB

---
name: corebluetooth
description: Apple Core Bluetooth framework for BLE and Bluetooth Classic. Use for central/peripheral workflows, scanning, connecting, advertising, GATT services/characteristics, read/write/notify, L2CAP, background processing or state restoration, and error handling across Apple platforms.
---

# Core Bluetooth

## What to open

- Use `corebluetooth/AboutCoreBluetooth.md` and `corebluetooth/CoreBluetoothOverview.md` for concepts and role orientation.
- Use `corebluetooth/PerformingCommonCentralRoleTasks.md` for step-by-step central workflows.
- Use `corebluetooth/PerformingCommonPeripheralRoleTasks.md` for step-by-step peripheral workflows.
- Use `corebluetooth/BestPracticesforInteractingwithaRemotePeripheralDevice.md` and `corebluetooth/BestPracticesforSettingUpYourLocalDeviceasaPeripheral.md` for pitfalls and best practices.
- Use `corebluetooth/CoreBluetoothBackgroundProcessingforiOSApps.md` for background modes and lifecycle constraints.
- Use `corebluetooth/BluetoothStateRestorationAppReaunchRules.md` for state restoration app relaunch rules.
- Use `corebluetooth/corebluetooth.md` for API quick maps and symbol lookup.

## Workflow

- Identify whether the app acts as a central, a peripheral, or both.
- Wait for the manager state to be `poweredOn` before issuing BLE operations.
- Follow the role checklist to keep discovery and connection order correct.
- Open the role task guide and best practices first; use the API reference for exact signatures.

## Central checklist

1. Create a `CBCentralManager` with a delegate and queue.
2. Handle `centralManagerDidUpdateState(_:)` and gate scanning on `.poweredOn`.
3. Scan with `scanForPeripherals(withServices:options:)` and stop when the target is found.
4. Connect, set the `CBPeripheral` delegate, and discover services and characteristics.
5. Read, write, or subscribe to characteristic notifications as needed.

## Peripheral checklist

1. Create a `CBPeripheralManager` with a delegate and queue.
2. Wait for the state to become `.poweredOn`.
3. Define services and characteristics, then add them to the manager.
4. Start advertising with service UUIDs and optional local name.
5. Respond to read and write requests; publish updates to subscribed centrals.

## Reminders

- Retain discovered `CBPeripheral` instances to keep them alive.
- Use notifications for streaming data; use write-without-response only when `canSendWriteWithoutResponse` is true.
- Use L2CAP only for use cases that do not fit GATT characteristics.

Overview

This skill documents Apple Core Bluetooth for building BLE and Bluetooth Classic features across Apple platforms using Swift. It summarizes central and peripheral workflows, background processing and state restoration rules, GATT operations, and L2CAP usage. The content focuses on practical checklists, common pitfalls, and mapping to Core Bluetooth APIs.

How this skill works

The skill explains how to create and manage CBCentralManager and CBPeripheralManager instances, wait for .poweredOn state, and perform scanning, connecting, advertising, and GATT discovery. It guides readers through handling delegates, retaining peripheral objects, subscribing to notifications, reading/writing characteristics, and choosing L2CAP when GATT is insufficient. It also covers background modes and state restoration behaviors for reliable lifecycle handling.

When to use it

When implementing a BLE central to discover and connect to remote peripherals.
When implementing a local peripheral to advertise services and accept central connections.
When you need reliable background scanning, connection restoration, or state preservation.
When streaming data via notifications or using write-without-response for low-latency transfers.
When L2CAP channels are required for custom high-throughput or non-GATT data flows.

Best practices

Gate all BLE operations on manager state .poweredOn and implement centralManagerDidUpdateState(_:).
Retain discovered CBPeripheral instances to avoid unexpected deallocation and lost connections.
Stop scanning as soon as the target peripheral is found to conserve power and CPU.
Set delegates early, discover services/characteristics in order, and handle asynchronous callbacks robustly.
Use notifications for streaming, write-without-response only when canSendWriteWithoutResponse is true.
Follow platform rules for background modes and implement state restoration to recover sessions.

Example use cases

A fitness app acting as a central to read heart rate and battery characteristics from strap sensors.
A hardware companion app advertising a custom service while acting as a peripheral for nearby controllers.
A background location tracker that restores BLE connections after an app relaunch.
A streaming audio or sensor pipeline using notifications for continuous data delivery.
A custom high-throughput link using L2CAP channels for non-GATT binary transport.

FAQ

Do I need to wait for manager state before scanning?

Yes. Always wait for .poweredOn in the manager delegate before calling scanForPeripherals.

When should I use L2CAP instead of GATT?

Use L2CAP when your data model requires higher throughput, larger packets, or a non-characteristic protocol that GATT cannot efficiently handle.