Find Device Overview

Use the Find APIs either to make a connected device present its locate-device indication or to respond when that device asks your app to locate the iPhone.

These are opposite directions and use different APIs:

Flow	Initiator	App responsibility	Completion signal
Locate device	Host app	Start or stop the connected device's firmware-defined indication through DeviceFindAPI.	The command completion reports acceptance. A supported device may later emit deviceDidReportFound.
Locate iPhone	Connected device	Start or stop an iPhone-side sound, vibration, or UI in response to delegate callbacks.	After the user finds the iPhone, report resolution through FindPhoneStateReportingAPI.

Available Features

📄️Find Device

Start the finding operation on a connected AIBuds device

📄️Stop Find Device

Stop the finding operation on a connected AIBuds device

📄️Report iPhone Found

Report that a device-originated find-iPhone request has been resolved

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Implement AIBuds Find Workflow skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/implement-aibuds-find-workflow. Use it to implement Implement AIBuds Find Workflow in this iOS project and verify the result.

View official skill↗

Getting Started

To use the find device feature, follow these steps:

1. Connect to the Device — Establish a usable connection with the target AIBuds device.
2. Choose the Direction — Decide whether the app is locating the device or responding to a device-originated find-iPhone request.
3. Check Protocol and Capability Support — Use DeviceFindAPI for locate-device commands, then require supportsFindDevice == true; use FindPhoneStateReportingAPI to report that the phone was found.
4. Handle the Correct Terminal Signal — Do not interpret command acceptance as proof that the physical device or phone has been found.

Key Concepts

Locate the Device

• Find Device: Requests the connected device to start its locate indication.
• Stop Find Device: Requests the connected device to stop that indication.
• Device Found Event: deviceDidReportFound(_:) is a separate device-originated terminal event when supported.

DeviceFindAPI operates on the already-connected device. Before presenting its controls or sending a command, check supportsFindDevice. The property defaults to false when the connected device does not report this capability. This API does not perform Bluetooth discovery or scan for nearby devices.

Locate the Phone

• deviceDidRequestStartFindingPhone(_:) asks the app to start its own iPhone-side alert.
• deviceDidRequestStopFindingPhone(_:) asks the app to stop that alert.
• After the user locates the iPhone, call notifyPhoneFound(_:) to report resolution to the requesting device.

Protocol Reference

The locate-device commands are accessed through DeviceFindAPI:

Swift

Swift

guard let device = device as? DeviceFindAPI else {
    print("Device does not support DeviceFindAPI")
    return
}
guard device.supportsFindDevice else {
    print("Connected device does not support find-device commands")
    return
}

Objective-C

Objective-C

id<AIBudsDeviceFindAPI> device = (id<AIBudsDeviceFindAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceFindAPI)]) {
    NSLog(@"Device does not support AIBudsDeviceFindAPI");
    return;
}
if (!device.supportsFindDevice) {
    NSLog(@"Connected device does not support find-device commands");
    return;
}

The opposite find-iPhone flow uses FindPhoneStateReportingAPI after a device-originated request:

Swift

Swift

guard let reporter = device as? FindPhoneStateReportingAPI else {
    print("Device cannot receive an iPhone-found report")
    return
}

Objective-C

Objective-C

id<AIBudsFindPhoneStateReportingAPI> reporter =
    (id<AIBudsFindPhoneStateReportingAPI>)self.device;
if (![reporter conformsToProtocol:@protocol(AIBudsFindPhoneStateReportingAPI)]) {
    NSLog(@"Device cannot receive an iPhone-found report");
    return;
}

Best Practices

1. Keep the Directions Separate: Do not use DeviceFindAPI to implement an iPhone-side alert.
2. Check Protocol and Capability Support: Verify the protocol required by the selected flow and require supportsFindDevice before exposing locate-device controls.
3. Distinguish Acceptance from Resolution: A successful completion confirms command processing, not that the target was physically located.
4. Provide a Stop Path: Let users stop the active device or phone indication.
5. Update UI on the Main Queue: Dispatch UIKit changes made from callbacks to the main queue.

Notes

• Locate-device commands require the target device to remain connected and reachable.
• Device-side sound, vibration, or other indication behavior is firmware-defined.
• supportsFindDevice == false can mean either that the feature is unsupported or that the device did not report the capability.
• The app owns the iPhone-side sound, vibration, and UI used for a find-iPhone request.
• Neither protocol exposes an authoritative active-state or duration property.