accessorysetupkit

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: 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 [Number] 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 at discovery time. 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 requires bluetoothCompanyIdentifier or bluetoothServiceUUID , plus at least one of: 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 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: 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 instances with a name, product image, and discovery descriptor, then pass them to the 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 { 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 ] Option Effect .rename Allow renaming the accessory during setup .confirmAuthorization Show authorization confirmation before setup .finishInApp Signal that setup continues in the app after pairing 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 objects through the event handler: Event When .activated Session is active, query session.accessories .accessoryAdded User selected an accessory in the picker .accessoryChanged Accessory properties updated (e.g., renamed) .accessoryRemoved Accessory removed from system .invalidated Session invalidated, create a new one .migrationComplete Migration of legacy accessories completed .pickerDidPresent Picker appeared on screen .pickerDidDismiss Picker dismissed .pickerSetupBridging Transport bridging setup in progress .pickerSetupPairing Bluetooth pairing in progress .pickerSetupFailed Setup failed .pickerSetupRename User is renaming the accessory .accessoryDiscovered New accessory found (custom filtering mode) Coordinating Picker Dismissal When the user selects an accessory, .accessoryAdded fires before .pickerDidDismiss . To show custom setup UI after the picker closes, store the accessory on the first event and act on it after dismissal: 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 on the ASAccessory maps to a 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 on the ASAccessory identifies the network. Use NEHotspotConfiguration from NetworkExtension to join it: 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 . This is a one-time operation that registers known accessories in the new system. 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