jordancoin/ios-skills-collection/dpearson2699-accessorysetupkit

Claude Code and agent skill by jordancoin/ios-skills-collection

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install jordancoin/ios-skills-collection/dpearson2699-accessorysetupkit

SKILL.md

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

Info.plist Configuration

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

KeyTypePurpose
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
swift
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
swift
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:

ValueBehavior
.defaultStandard Bluetooth range
.immediateOnly accessories in close physical proximity
Support Options

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

swift
descriptor.supportedOptions = [.bluetoothPairingLE, .bluetoothTransportBridging]
OptionPurpose
.bluetoothPairingLEBLE pairing support
.bluetoothTransportBridgingBluetooth transport bridging
.bluetoothHIDBluetooth HID device

Presenting the Picker

Creating the Session

Create and activate an ASAccessorySession to manage discovery lifecycle:

swift
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:

swift
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:

swift
var item = ASPickerDisplayItem(
name: "My Accessory",
productImage: image,
descriptor: descriptor
)
item.setupOptions = [.rename, .confirmAuthorization]
OptionEffect
.renameAllow renaming the accessory during setup
.confirmAuthorizationShow authorization confirmation before setup
.finishInAppSignal 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:

EventWhen
.activatedSession is active, query session.accessories
.accessoryAddedUser selected an accessory in the picker
.accessoryChangedAccessory properties updated (e.g., renamed)
.accessoryRemovedAccessory removed from system
.invalidatedSession invalidated, create a new one
.migrationCompleteMigration of legacy accessories completed
.pickerDidPresentPicker appeared on screen
.pickerDidDismissPicker dismissed
.pickerSetupBridgingTransport bridging setup in progress
.pickerSetupPairingBluetooth pairing in progress
.pickerSetupFailedSetup failed
.pickerSetupRenameUser is renaming the accessory
.accessoryDiscoveredNew 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:

swift
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.

swift
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:

swift
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.

swift
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.

swift
// 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

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
2
7-day trend score
5

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 19 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/jordancoin/ios-skills-collection/dpearson2699-accessorysetupkit/badge)](https://verified-skill.com/skills/jordancoin/ios-skills-collection/dpearson2699-accessorysetupkit)

Something wrong with this skill or its page? Tell us.