/accessorysetupkit

name: accessorysetupkit
description: "Discover and configure Bluetooth and Wi-Fi accessories using AccessorySetupKit. Use when presenting a privacy-preserving accessory picker, defining discovery descriptors for BLE or Wi-Fi devices, handling accessory session events, migrating from CoreBluetooth permission-based scanning, or setting up accessories without requiring broad Bluetooth permissions."

AccessorySetupKit

Use the iOS 18+ system picker for privacy-preserving Bluetooth/Wi-Fi accessory discovery and authorization, then hand off communication to CoreBluetooth or NetworkExtension.

Contents

• [Setup and Entitlements](#setup-and-entitlements)
• [Discovery Descriptors](#discovery-descriptors)
• [Presenting the Picker](#presenting-the-picker)
• [Event Handling](#event-handling)
• [Bluetooth Accessories](#bluetooth-accessories)
• [Wi-Fi Accessories](#wi-fi-accessories)
• [Migration from CoreBluetooth](#migration-from-corebluetooth)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Setup and Entitlements

Info.plist Configuration

Add these keys to the app's Info.plist:

| Key | Type | Purpose | |---|---|---| | `NSAccessorySetupSupports` | `[String]` | Required. Array containing `Bluetooth` and/or `WiFi` | | `NSAccessorySetupBluetoothServices` | `[String]` | Service UUIDs the app discovers (Bluetooth) | | `NSAccessorySetupBluetoothNames` | `[String]` | Bluetooth names or substrings to match | | `NSAccessorySetupBluetoothCompanyIdentifiers` | `[String]` | Two-byte Bluetooth company identifiers |

The Bluetooth-specific keys must match the values used in `ASDiscoveryDescriptor`. If the app uses identifiers, names, or services not declared in Info.plist, the app crashes during AccessorySetupKit discovery. For Wi-Fi accessories, include `WiFi` in `NSAccessorySetupSupports` and match the descriptor's SSID rule.

No Bluetooth Permission Required

When an app declares `NSAccessorySetupSupports` with `Bluetooth`, creating a `CBCentralManager` no longer triggers the system Bluetooth permission dialog. The central manager's state transitions to `poweredOn` only when the app has at least one paired accessory via AccessorySetupKit.

Discovery Descriptors

`ASDiscoveryDescriptor` defines the matching criteria for finding accessories. The system matches scanned results against all rules in the descriptor to filter for the target accessory.

Bluetooth Descriptor

import AccessorySetupKit
import CoreBluetooth

var descriptor = ASDiscoveryDescriptor()
descriptor.bluetoothServiceUUID = CBUUID(string: "12345678-1234-1234-1234-123456789ABC")
descriptor.bluetoothNameSubstring = "MyDevice"
descriptor.bluetoothRange = .immediate  // Only nearby devices

A Bluetooth descriptor needs at least one of `bluetoothCompanyIdentifier` or `bluetoothServiceUUID`. Add narrower matchers as needed:

• `bluetoothNameSubstring` with a company identifier or service UUID
• `bluetoothManufacturerDataBlob` and `bluetoothManufacturerDataMask` with a

company identifier; blob and mask must have the same length

• `bluetoothServiceDataBlob` and `bluetoothServiceDataMask` with a service UUID;

blob and mask must have the same length

Wi-Fi Descriptor

var descriptor = ASDiscoveryDescriptor()
descriptor.ssid = "MyAccessory-Network"
// OR use a prefix:
// descriptor.ssidPrefix = "MyAccessory-"

Supply either `ssid` or `ssidPrefix`, not both. The app crashes if both are set. The `ssidPrefix` must have a non-zero length.

Bluetooth Range

Control the physical proximity required for discovery:

| Value | Behavior | |---|---| | `.default` | Standard Bluetooth range | | `.immediate` | Only accessories in close physical proximity |

Support Options

Set `supportedOptions` on the descriptor to declare the accessory's capabilities:

descriptor.supportedOptions = [.bluetoothPairingLE, .bluetoothTransportBridging]

| Option | Purpose | |---|---| | `.bluetoothPairingLE` | BLE pairing support | | `.bluetoothTransportBridging` | Bluetooth transport bridging | | `.bluetoothHID` | Bluetooth HID device |

Presenting the Picker

Creating the Session

Create and activate an `ASAccessorySession` to manage discovery lifecycle. Wait for `.activated` before reading `session.accessories` or presenting the picker:

import AccessorySetupKit

final class AccessoryManager {
    private let session = ASAccessorySession()

    func start() {
        session.activate(on: .main) { [weak self] event in
            self?.handleEvent(event)
        }
    }

    private func handleEvent(_ event: ASAccessoryEvent) {
        switch event.eventType {
        case .activated:
            // Session ready. Check session.accessories for previously paired devices.
            break
        case .accessoryAdded:
            guard let accessory = event.accessory else { return }
            handleAccessoryAdded(accessory)
        case .accessoryChanged:
            // Accessory properties changed (e.g., display name updated in Settings)
            break
        case .accessoryRemoved:
            // Accessory removed by user or app
            break
        case .invalidated:
            // Session invalidated, cannot be reused
            break
        @unknown default:
            break
        }
    }
}

Showing the Picker

Create `ASPickerDisplayItem` instances with a name, product image, and discovery descriptor, then pass them to the activated session:

func showAccessoryPicker() {
    var descriptor = ASDiscoveryDescriptor()
    descriptor.bluetoothServiceUUID = CBUUID(string: "ABCD1234-0000-1000-8000-00805F9B34FB")

    guard let image = UIImage(named: "my-accessory") else { return }

    let item = ASPickerDisplayItem(
        name: "My Bluetooth Accessory",
        productImage: image,
        descriptor: descriptor
    )

    session.showPicker(for: [item]) { error in
        if let error {