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. ios 18+ / swift 6.3.

after setup, apps continue using coreblutooth and networkextension for communication. accessorysetupkit handles only discovery and authorization.

intent

use this skill when building an ios app that needs to discover and pair bluetooth or wi-fi accessories without requesting blanket device permissions. the framework replaces system permission dialogs with a focused picker that appears only on user action, letting users grant per-accessory access in a single tap. ideal for apps managing smart home devices, audio peripherals, fitness trackers, or any accessory that needs pairing before ongoing communication.

inputs

framework requirements:

• ios 18 or later
• swift 6.3 or later
• accessorysetupkit framework imported

plist configuration (info.plist):

• NSAccessorySetupSupports [String array, required]: contains "Bluetooth" and/or "WiFi"
• NSAccessorySetupBluetoothServices [String array, conditional]: uuids of bluetooth services the app discovers. required if using service uuid matching
• NSAccessorySetupBluetoothNames [String array, conditional]: bluetooth device names or substrings to match. required if using name matching
• NSAccessorySetupBluetoothCompanyIdentifiers [Number array, conditional]: bluetooth company ids (manufacturer identifiers). required if using company id matching

all bluetooth values in descriptors must match corresponding plist declarations or the app crashes at discovery time.

external state (post-setup):

• coreblutooth cbperipheral objects (via bluetoothIdentifier from asaccessory)
• networkextension nehotspotconfigurationmanager (for wi-fi ssid connection)
• existing coreblutooth-paired peripherals (if migrating legacy accessories)

edge cases:

• rate limits: accessorysetupkit does not document rate limits on picker calls, but calling showPicker repeatedly without dismissal may queue or fail silently
• auth expiry: once an accessory is paired, no re-auth is needed unless the user removes it
• empty result sets: if no accessories match the descriptor criteria, the picker shows an empty or "no devices found" state
• network timeouts: wi-fi joining via networkextension can timeout if the network is unreachable
• session invalidation: once asaccessorysession receives .invalidated event, it cannot be reused

procedure

step 1: declare support in info.plist

input: target accessory types (bluetooth, wi-fi, or both)

add to info.plist:

<key>NSAccessorySetupSupports</key>
<array>
  <string>Bluetooth</string>
  <string>WiFi</string>
</array>

if discovering bluetooth devices, also add:

<key>NSAccessorySetupBluetoothServices</key>
<array>
  <string>ABCD1234-0000-1000-8000-00805F9B34FB</string>
</array>
<key>NSAccessorySetupBluetoothNames</key>
<array>
  <string>MyDevice</string>
</array>
<key>NSAccessorySetupBluetoothCompanyIdentifiers</key>
<array>
  <integer>76</integer>
</array>

output: info.plist updated with accessory setup keys.

step 2: create and activate asaccessorysession

input: main dispatch queue, event handler closure

import accessorysetupkit. create a session instance and activate it on the main thread:

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. Query session.accessories for previously paired devices.
            let paired = session.accessories
            break
        case .accessoryAdded:
            guard let accessory = event.accessory else { return }
            handleAccessoryAdded(accessory)
        case .accessoryChanged:
            // Accessory properties changed (e.g., renamed in settings)
            break
        case .accessoryRemoved:
            // User or app removed the accessory
            break
        case .invalidated:
            // Session is dead, cannot be reused
            break
        case .pickerDidPresent:
            // Picker appeared on screen
            break
        case .pickerDidDismiss:
            // Picker closed
            break
        case .pickerSetupPairing:
            // Bluetooth pairing in progress
            break
        case .pickerSetupBridging:
            // Transport bridging setup in progress
            break
        case .pickerSetupFailed:
            // Setup failed
            break
        case .pickerSetupRename:
            // User renaming accessory
            break
        case .migrationComplete:
            // Legacy accessory migration finished
            break
        case .accessoryDiscovered:
            // New accessory found (custom filtering mode only)
            break
        @unknown default:
            break
        }
    }
}

output: asaccessorysession activated, ready to receive events. session.accessories contains any previously paired accessories.

step 3: build discovery descriptors for each accessory type

input: accessory matching criteria (service uuids, names, company ids for bluetooth; ssid for wi-fi)

for bluetooth, create asdiscoverydescriptor with matching rules:

var btDescriptor = ASDiscoveryDescriptor()
btDescriptor.bluetoothServiceUUID = CBUUID(string: "ABCD1234-0000-1000-8000-00805F9B34FB")
btDescriptor.bluetoothNameSubstring = "MyDevice"
btDescriptor.bluetoothRange = .immediate  // .default or .immediate
btDescriptor.supportedOptions = [.bluetoothPairingLE]

a bluetooth descriptor requires either bluetoothCompanyIdentifier or bluetoothServiceUUID, plus at least one matching criterion: bluetoothNameSubstring, bluetoothManufacturerDataBlob with bluetoothManufacturerDataMask, or bluetoothServiceDataBlob with bluetoothServiceDataMask.

for wi-fi, create descriptor with ssid:

var wifiDescriptor = ASDiscoveryDescriptor()
wifiDescriptor.ssid = "MyAccessory-Network"
// OR
// wifiDescriptor.ssidPrefix = "MyAccessory-"

supply either ssid or ssidPrefix, not both.

output: asdiscoverydescriptor instances configured with matching rules that align with plist declarations.

step 4: create pickerdisplay items with images and descriptors

input: accessory name, product image (180x120 points), descriptor, setup options

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

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

product image best practices:

• use high-resolution images (3x for retina)
• transparent backgrounds for light/dark mode
• adjust transparent padding to control apparent size
• test in both light and dark mode

output: aspickerdisplayitem configured with display metadata.

step 5: present picker on user action

input: array of pickerdisplayitems, user tap event (do not auto-launch)

call showpicker only in response to explicit user interaction:

@IBAction func addAccessoryTapped(_ sender: UIButton) {
    session.showPicker(for: [item]) { error in
        if let error {
            print("picker failed: \(error.localizedDescription)")
        }
    }
}

the picker runs in a separate system process and shows each matching device as a carousel item.

output: picker ui appears on screen, system handles device discovery and user selection.

step 6: handle accessory added event

input: asaccessoryevent with eventtype .accessoryadded, asaccessory object

when user selects an accessory in the picker, .accessoryadded fires before .pickerdiddismiss. store the accessory to act on it after picker closes:

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
            setupAccessory(accessory)
        }
    default:
        break
    }
}

private func setupAccessory(_ accessory: ASAccessory) {
    if let btIdentifier = accessory.bluetoothIdentifier {
        connectBluetooth(btIdentifier)
    } else if let ssid = accessory.ssid {
        connectWiFi(ssid)
    }
}

output: accessory object retrieved and stored for post-picker processing.

step 7: connect bluetooth accessory

input: bluetoothidentifier from asaccessory, coreblutooth delegate

import coreblutooth. create cbcentralmanager (no permission prompt appears because accessory was paired via accessorysetupkit):

func connectBluetooth(_ btIdentifier: UUID) {
    let centralManager = CBCentralManager(delegate: self, queue: nil)
    
    // After state transitions to .poweredOn:
    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 at least one paired accessory via accessorysetupkit
• scanforperipherals(withservices:) returns only accessories paired through accessorysetupkit
• nsbluetoothawaysusagedescription is not needed

output: cbcentralmanager initialized, peripheral connected, communication ready via coreblutooth delegates.

step 8: connect wi-fi accessory

input: ssid from asaccessory

import networkextension. join the wi-fi network (no prompt appears because accessory was discovered via accessorysetupkit):

func connectWiFi(_ ssid: String) {
    let configuration = NEHotspotConfiguration(ssid: ssid)
    NEHotspotConfigurationManager.shared.apply(configuration) { error in
        if let error {
            print("wi-fi join failed: \(error.localizedDescription)")
        }
    }
}

output: wi-fi network joined via networkextension, device connected to accessory network.

step 9: handle accessory removal

input: asaccessoryevent with eventtype .accessoryremoved

when user removes an accessory (from settings or via app), .accessoryremoved fires:

case .accessoryRemoved:
    guard let accessory = event.accessory else { return }
    print("removed: \(accessory.name)")
    // clean up app state: disconnect coreblutooth, remove ui elements, etc.

output: app cleaned up, resources released.

step 10 (optional): migrate legacy coreblutooth accessories

input: existing cbperipheral uuid and ssid (if wi-fi), migration display items

if the app already has coreblutooth-authorized accessories, migrate them once:

func migrateExistingAccessories(_ peripheralUUID: UUID, ssid: String?) {
    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
    )
    migrationItem.peripheralIdentifier = peripheralUUID
    if let ssid = ssid {
        migrationItem.hotspotSSID = ssid
    }

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

critical: do not initialize cbcentralmanager before migration completes. wait for .migrationcomplete event:

case .migrationComplete:
    let central = CBCentralManager(delegate: self, queue: nil)

output: legacy accessories registered in accessorysetupkit system.

decision points

if migrating legacy accessories: do not initialize cbcentralmanager until .migrationcomplete event fires. initializing before migration causes an error and the picker fails.

if using bluetooth: check that all service uuids, names, and company identifiers used in descriptors are declared in info.plist. omitting them causes a crash at discovery time.

if using wi-fi: set either ssid or ssidPrefix on the descriptor, not both. setting both crashes at runtime.

if showing multiple accessory types in one picker call: mix aspickerdisplayitem and asmigrationdisplayitem in the same array only if you want migration to occur alongside discovery. if the array contains only migration items, the system shows an informational page instead of a discovery picker.

if the picker fails: check the error in the completion handler. common causes are: (1) descriptor values not in plist, (2) session invalidated, (3) cbcentralmanager already initialized (migration case), (4) no user-triggered action.

if no accessories match the descriptor: the picker displays an empty or "no devices found" state. this is expected behavior, not an error.

if an accessory is removed: handle the .accessoryremoved event to clean up app state (disconnect peripheral, remove ui references, release resources). failure to do so can lead to stale object references.

if the session is invalidated: create a new asaccessorysession instance. do not attempt to reuse an invalidated session.

output contract

success is indicated by:

1. info.plist: nsaccessoryssetupssupports array present with "Bluetooth" and/or "WiFi". all bluetooth descriptor values declared in corresponding plist keys.

2. session lifecycle: asaccessorysession activated on main thread, event handler receives .activated event. session.accessories contains list of previously paired accessories.

3. picker presentation: aspickerdisplayitem instances created with valid name, image, and descriptor. showpicker called only after session activation and only on user action. picker appears on screen and handles device discovery.

4. accessory pairing: user selects device in picker. .accessoryadded event fires with asaccessory object containing bluetoothidentifier (for bt) or ssid (for wi-fi).

5. post-setup communication: cbperipheral retrieved via bluetoothidentifier and connected. or nehotspotconfiguration applied with ssid and joined successfully.

6. data persisted: session.accessories reflects newly paired accessory. removal events update app state.

outcome signal

the skill has worked when:

• picker appears on screen only after user taps the "add accessory" button or similar action
• user selects an accessory and picker closes without system permission prompts
• app receives .accessoryadded event with a valid asaccessory object containing a bluetoothidentifier or ssid
• for bluetooth: cbcentralmanager successfully retrieves the paired peripheral and establishes connection without requesting nsbluetoothawaysusagedescription
• for wi-fi: nehotspotconfigurationmanager joins the network without triggering wi-fi access prompts
• session.accessories is populated with the newly paired device
• removing the accessory from settings triggers .accessoryremoved event in the session handler