Physical Operations Overview

Welcome to the Physical Operations documentation for the AIBuds SDK. This section covers reading and changing the mapping between physical device operations and device functions.

Available Features

📄️Operations and Functions

Reference the physical operations and assignable functions exposed by the SDK

📄️View Operation Mapping

Read the device's physical-operation-to-function mapping

📄️Assign Functions

Assign a device function to a physical operation

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Manage AIBuds Physical Operations skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/manage-aibuds-physical-operations. Use it to implement Manage AIBuds Physical Operations in this iOS project and verify the result.

View official skill↗

Getting Started

To manage physical operations, follow these steps:

1. Connect to Device - Establish a connection with your AIBuds device
2. Check Protocol Conformance - Verify the device conforms to DevicePhysicalOperationsAPI
3. View Operation Mapping - Read physicalOperationsMapping
4. Assign Functions - Assign a DeviceFunction to a DeviceOperation

Key Concepts

Button Mapping

• Physical Operations: DeviceOperation represents clicks, long presses, touch-panel gestures, buttons, and supported slide gestures
• Device Functions: DeviceFunction defines assignable behaviors such as playback, volume, voice-assistant, recording, and camera actions
• Mapping: physicalOperationsMapping stores operation and function raw values as NSNumber keys and values

Protocol Reference

Physical operations are accessed through DevicePhysicalOperationsAPI. Before reading or changing the mapping, verify protocol conformance:

Swift

Swift

guard let device = device as? DevicePhysicalOperationsAPI else {
    print("Device does not support DevicePhysicalOperationsAPI")
    return
}

Objective-C

Objective-C

id<AIBudsDevicePhysicalOperationsAPI> device =
    (id<AIBudsDevicePhysicalOperationsAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDevicePhysicalOperationsAPI)]) {
    NSLog(@"Device does not support AIBudsDevicePhysicalOperationsAPI");
    return;
}

Best Practices

1. Check Protocol Conformance: Always verify the device supports the required protocol
2. Use Reported Operations: Present operations contained in physicalOperationsMapping
3. Handle Errors: Implement proper error handling in completion handlers
4. Provide Feedback: Inform users when button mappings are successfully updated

Notes

• Button mapping availability depends on the device model
• An enum case being present in DeviceOperation or DeviceFunction does not guarantee that every device supports it
• An operation or function can be unsupported even when its enum value exists; handle the assignment result
• The SDK exposes a dictionary rather than a KeyMapping model or asynchronous get-mapping method