playbooks

home / skills / nonameplum / agent-skills / accessory-setup-kit

accessory-setup-kit skill

/accessory-setup-kit

This skill helps you configure and discover Bluetooth, Wi-Fi, or Wi-Fi Aware accessories using AccessorySetupKit, including migration, renaming, and custom

npx playbooks add skill nonameplum/agent-skills --skill accessory-setup-kit

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.3 KB
---
name: accessory-setup-kit
description: AccessorySetupKit for privacy-preserving discovery and setup of Bluetooth, Wi-Fi, or Wi-Fi Aware accessories. Use for discovery sessions, picker-based authorization, migration, accessory renaming or removal, custom filtering, and required Info.plist declarations.
---

# AccessorySetupKit

## What to open

- Use `accessory-setup-kit/accessorysetupkit.md` for all API details and key names.
- Use `accessory-setup-kit/AccessorySetupKitEverythingBLEDevelopersNeedToKnow.md` for BLE-specific behavior notes and real-world details.
- Search within it for: "Discovering and configuring accessories", `ASAccessorySession`, `ASDiscoveryDescriptor`, `ASPickerDisplayItem`, `ASMigrationDisplayItem`, `ASPickerDisplaySettings`, and `ASAccessoryEventType`.

## Workflow

- Identify whether the accessory uses Bluetooth, Wi-Fi, or Wi-Fi Aware and set up matching discovery properties.
- Declare required Info.plist keys for AccessorySetupKit and any Bluetooth identifiers.
- Create and activate `ASAccessorySession`, then handle events on the provided queue.
- Present a picker with `ASPickerDisplayItem` items that match the accessories you support.
- Handle `.accessoryAdded` to connect to the selected device; handle `.accessoryRemoved` and `.accessoryChanged` as needed.

## Picker guidance

- A display item must include a descriptor with a Bluetooth identifier or Wi-Fi SSID/SSID prefix.
- For Bluetooth filters, provide at least a service UUID or company identifier, and optionally a name substring or manufacturer/service data mask pair.
- To do custom filtering, enable `filterDiscoveryResults` and handle `.accessoryDiscovered` by creating `ASDiscoveredDisplayItem` entries, then call `updatePicker(showing:completionHandler:)`.
- If custom filtering needs unlimited time, set `discoveryTimeout = .unbounded` and finish discovery with `finishPickerDiscovery(completionHandler:)`.

## Migration and post-setup

- Use `ASMigrationDisplayItem` to migrate previously-configured accessories into AccessorySetupKit.
- Use setup and rename options on picker items when the user should rename or finish setup in-app.

## Reminders

- Keep discovery descriptors specific to avoid broad Bluetooth access.
- For Wi-Fi Aware, set Wi-Fi Aware properties on `ASDiscoveryDescriptor` before discovery.
- Use the session event stream to keep app state in sync with user actions.

Overview

This skill documents AccessorySetupKit for privacy-preserving discovery and setup of Bluetooth, Wi‑Fi, and Wi‑Fi Aware accessories. It explains session lifecycle, picker-based authorization, migration helpers, custom filtering, and required Info.plist declarations. Use it to implement secure accessory discovery, present system pickers, and keep app state synchronized with user actions.

How this skill works

Create and activate an ASAccessorySession configured for the transport (Bluetooth, Wi‑Fi, or Wi‑Fi Aware) and handle events on the session queue. Build ASPickerDisplayItem or ASMigrationDisplayItem entries with ASDiscoveryDescriptor details (Bluetooth identifiers or Wi‑Fi SSIDs) and present the system picker; handle accessoryAdded, accessoryRemoved, accessoryChanged, and accessoryDiscovered events to drive UI and connections. For custom filtering, enable filterDiscoveryResults, respond to accessoryDiscovered by providing ASDiscoveredDisplayItem objects, and control discovery timeout or finish discovery explicitly.

When to use it

  • Discover and pair nearby Bluetooth accessories that require limited, privacy-preserving scan access.
  • Present a Wi‑Fi-based accessory picker that filters by SSID or SSID prefix.
  • Perform migrations of previously configured accessories into the AccessorySetupKit flow.
  • Implement custom discovery logic when built-in filters are insufficient.
  • Support Wi‑Fi Aware accessories that need special discovery properties set before scanning.

Best practices

  • Keep discovery descriptors as specific as possible to minimize Bluetooth access scope.
  • Declare all required Info.plist keys for AccessorySetupKit and any Bluetooth identifiers before attempting discovery.
  • Provide at least one Bluetooth service UUID or company identifier for Bluetooth filters; optionally add name substrings or manufacturer/service data masks.
  • Use the session event stream to update app state for accessoryAdded, removed, and changed events.
  • If unlimited custom discovery is required, set discoveryTimeout = .unbounded and call finishPickerDiscovery when done.

Example use cases

  • Show a picker to let users authorize and connect a BLE smart lock advertising a known service UUID and name substring.
  • Discover smart plugs on the local Wi‑Fi by matching SSID prefixes and present them in a system picker.
  • Migrate legacy accessories into a new app flow using ASMigrationDisplayItem to preserve user data and settings.
  • Implement a custom scanning UI that filters manufacturer data, creates ASDiscoveredDisplayItem entries, and updates the picker dynamically.
  • Handle accessoryRemoved and accessoryChanged events to reflect accessory state and renaming inside the app.

FAQ

What must I include in Info.plist?

Declare AccessorySetupKit usage keys and any Bluetooth identifiers (UUIDs, company IDs) required for discovery before activating a session.

How do I handle unlimited discovery time?

Set discoveryTimeout = .unbounded on the picker and call finishPickerDiscovery(completionHandler:) when you want discovery to stop.