Core Find Device Overview

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

Browse the generated Wiki navigation for the pages in this section.

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 Conformance — Use DeviceFindAPI for locate-device commands or 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. It 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
}
```

Objective-C

```objc
id<AIBudsDeviceFindAPI> device = (id<AIBudsDeviceFindAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceFindAPI)]) {
    NSLog(@"Device does not support AIBudsDeviceFindAPI");
    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

```objc
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 Conformance: Verify the protocol required by the selected flow.
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.
• 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.