AccessorySetupKit

Privacy-preserving accessory discovery and setup for Bluetooth and Wi-Fi devices. Replaces broad Bluetooth/Wi-Fi permission prompts with a system-provided picker that grants per-accessory access with a single tap. Available iOS 18+ / Swift 6.3.

After setup, apps continue using CoreBluetooth and NetworkExtension for communication. AccessorySetupKit handles only the discovery and authorization step.

Contents

• Setup and Entitlements
• Discovery Descriptors
• Presenting the Picker
• Event Handling
• Bluetooth Accessories
• Wi-Fi Accessories
• Migration from CoreBluetooth
• Common Mistakes
• Review Checklist
• References

Setup and Entitlements

Info.plist Configuration

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

NSAccessorySetupSupports

[String]

Bluetooth

WiFi

NSAccessorySetupBluetoothServices

[String]

NSAccessorySetupBluetoothNames

[String]

NSAccessorySetupBluetoothCompanyIdentifiers

[Number]

The Bluetooth-specific keys must match the values used in

ASDiscoveryDescriptor

No Bluetooth Permission Required

When an app declares

NSAccessorySetupSupports

Bluetooth

CBCentralManager

poweredOn

Discovery Descriptors

ASDiscoveryDescriptor

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 requires

bluetoothCompanyIdentifier

bluetoothServiceUUID

• bluetoothNameSubstring

• bluetoothManufacturerDataBlob

  and

  bluetoothManufacturerDataMask

  (same length)

• bluetoothServiceDataBlob

  and

  bluetoothServiceDataMask

  (same length)

Wi-Fi Descriptor

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

Supply either

ssid

ssidPrefix

ssidPrefix

Bluetooth Range

Control the physical proximity required for discovery:

.default

.immediate

Support Options

Set

supportedOptions

descriptor.supportedOptions = [.bluetoothPairingLE, .bluetoothTransportBridging]

.bluetoothPairingLE

.bluetoothTransportBridging

.bluetoothHID

Presenting the Picker

Creating the Session

Create and activate an

ASAccessorySession

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
        default:
            break
        }
    }
}

Showing the Picker

Create

ASPickerDisplayItem

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 {
            print("Picker failed: \(error.localizedDescription)")
        }
    }
}

The picker runs in a separate system process. It shows each matching device as a separate item. When multiple devices match a given descriptor, the picker creates a horizontal carousel.

Setup Options

Configure picker behavior per display item:

var item = ASPickerDisplayItem(
    name: "My Accessory",
    productImage: image,
    descriptor: descriptor
)
item.setupOptions = [.rename, .confirmAuthorization]

.rename

.confirmAuthorization

.finishInApp

Product Images

The picker displays images in a 180x120 point container. Best practices:

• Use high-resolution images for all screen scale factors
• Use transparent backgrounds for correct light/dark mode appearance
• Adjust transparent borders as padding to control apparent accessory size
• Test in both light and dark mode

Event Handling

Event Types

The session delivers

ASAccessoryEvent

.activated

session.accessories

.accessoryAdded

.accessoryChanged

.accessoryRemoved

.invalidated

.migrationComplete

.pickerDidPresent

.pickerDidDismiss

.pickerSetupBridging

.pickerSetupPairing

.pickerSetupFailed

.pickerSetupRename

.accessoryDiscovered

Coordinating Picker Dismissal

When the user selects an accessory,

.accessoryAdded

.pickerDidDismiss

private var pendingAccessory: ASAccessory?

private func handleEvent(_ event: ASAccessoryEvent) {
    switch event.eventType {
    case .accessoryAdded:
        pendingAccessory = event.accessory
    case .pickerDidDismiss:
        if let accessory = pendingAccessory {
            pendingAccessory = nil
            beginCustomSetup(accessory)
        }
    default:
        break
    }
}

Bluetooth Accessories

After an accessory is added via the picker, use CoreBluetooth to communicate. The

bluetoothIdentifier

ASAccessory

CBPeripheral

import CoreBluetooth

func handleAccessoryAdded(_ accessory: ASAccessory) {
    guard let btIdentifier = accessory.bluetoothIdentifier else { return }

    // Create CBCentralManager — no Bluetooth permission prompt appears
    let centralManager = CBCentralManager(delegate: self, queue: nil)

    // After poweredOn, retrieve the peripheral
    let peripherals = centralManager.retrievePeripherals(
        withIdentifiers: [btIdentifier]
    )
    guard let peripheral = peripherals.first else { return }
    centralManager.connect(peripheral, options: nil)
}

Key points:

• CBCentralManager

  state reaches

  .poweredOn

  only when the app has paired accessories
• Scanning with

  scanForPeripherals(withServices:)

  returns only accessories paired through AccessorySetupKit
• No

  NSBluetoothAlwaysUsageDescription

  is needed when using AccessorySetupKit exclusively

Wi-Fi Accessories

For Wi-Fi accessories, the

ssid

ASAccessory

NEHotspotConfiguration

import NetworkExtension

func handleWiFiAccessoryAdded(_ accessory: ASAccessory) {
    guard let ssid = accessory.ssid else { return }

    let configuration = NEHotspotConfiguration(ssid: ssid)
    NEHotspotConfigurationManager.shared.apply(configuration) { error in
        if let error {
            print("Wi-Fi join failed: \(error.localizedDescription)")
        }
    }
}

Because the accessory was discovered through AccessorySetupKit, joining the network does not trigger the standard Wi-Fi access prompt.

Migration from CoreBluetooth

Apps with existing CoreBluetooth-authorized accessories can migrate them to AccessorySetupKit using

ASMigrationDisplayItem

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

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

    let migrationItem = ASMigrationDisplayItem(
        name: "My Accessory",
        productImage: image,
        descriptor: descriptor
    )
    // Set the peripheral identifier from CoreBluetooth
    migrationItem.peripheralIdentifier = existingPeripheralUUID

    // For Wi-Fi accessories:
    // migrationItem.hotspotSSID = "MyAccessory-WiFi"

    session.showPicker(for: [migrationItem]) { error in
        if let error {
            print("Migration failed: \(error.localizedDescription)")
        }
    }
}

Migration rules:

• If

  showPicker

  contains only migration items, the system shows an informational page instead of a discovery picker
• If migration items are mixed with regular display items, migration happens only when a new accessory is discovered and set up
• Do not initialize

  CBCentralManager

  before migration completes — doing so causes an error and the picker fails to appear
• The session receives

  .migrationComplete

  when migration finishes

Common Mistakes

DON'T: Omit Info.plist keys for Bluetooth discovery

The app crashes if it uses identifiers, names, or services in descriptors that are not declared in Info.plist.

// WRONG — service UUID not in NSAccessorySetupBluetoothServices
var descriptor = ASDiscoveryDescriptor()
descriptor.bluetoothServiceUUID = CBUUID(string: "UNDECLARED-UUID")
session.showPicker(for: [item]) { _ in }  // Crash

// CORRECT — declare all UUIDs in Info.plist first
// Info.plist: NSAccessorySetupBluetoothServices = ["ABCD1234-..."]
var descriptor = ASDiscoveryDescriptor()
descriptor.bluetoothServiceUUID = CBUUID(string: "ABCD1234-...")

DON'T: Set both ssid and ssidPrefix

// WRONG — crashes at runtime
var descriptor = ASDiscoveryDescriptor()
descriptor.ssid = "MyNetwork"
descriptor.ssidPrefix = "My"  // Cannot set both

// CORRECT — use one or the other
var descriptor = ASDiscoveryDescriptor()
descriptor.ssid = "MyNetwork"

DON'T: Initialize CBCentralManager before migration

// WRONG — migration fails, picker does not appear
let central = CBCentralManager(delegate: self, queue: nil)
session.showPicker(for: [migrationItem]) { error in
    // error is non-nil
}

// CORRECT — wait for .migrationComplete before using CoreBluetooth
session.activate(on: .main) { event in
    if event.eventType == .migrationComplete {
        let central = CBCentralManager(delegate: self, queue: nil)
    }
}

DON'T: Show the picker without user intent

// WRONG — picker appears unexpectedly on app launch
override func viewDidLoad() {
    super.viewDidLoad()
    session.showPicker(for: items) { _ in }
}

// CORRECT — bind picker to a user action
@IBAction func addAccessoryTapped(_ sender: UIButton) {
    session.showPicker(for: items) { _ in }
}

DON'T: Reuse an invalidated session

// WRONG — session is dead after invalidation
session.showPicker(for: items) { _ in }  // No effect

// CORRECT — create a new session
let newSession = ASAccessorySession()
newSession.activate(on: .main) { event in
    // Handle events
}

Review Checklist

• NSAccessorySetupSupports

  added to Info.plist with

  Bluetooth

  and/or

  WiFi

• Bluetooth-specific plist keys (

  NSAccessorySetupBluetoothServices

  ,

  NSAccessorySetupBluetoothNames

  ,

  NSAccessorySetupBluetoothCompanyIdentifiers

  ) match descriptor values
• Session activated before calling

  showPicker

• Event handler uses

  [weak self]

  to avoid retain cycles
• All

  ASAccessoryEventType

  cases handled, including

  @unknown default

• Product images use transparent backgrounds and appropriate resolution

• ssid

  and

  ssidPrefix

  are never set simultaneously on a descriptor
• Picker presentation tied to explicit user action, not automatic

• CBCentralManager

  not initialized until after migration completes (if migrating)

• bluetoothIdentifier

  or

  ssid

  from

  ASAccessory

  used to connect post-setup
• Invalidated sessions replaced with new instances
• Accessory removal events handled to clean up app state

References

• Extended patterns (custom filtering, batch setup, removal handling, error recovery): references/accessorysetupkit-patterns.md
• AccessorySetupKit framework
• ASAccessorySession
• ASDiscoveryDescriptor
• ASPickerDisplayItem
• ASAccessory
• ASAccessoryEvent
• ASMigrationDisplayItem
• Discovering and configuring accessories
• Setting up and authorizing a Bluetooth accessory
• Meet AccessorySetupKit — WWDC24