Automatic Wedge Association

Configure AWA:

The ability to enable or disable AWA is controlled via the shouldEnableAWA parameter in the IMSDeviceManager.configure method:

Example

Swift

// Configure AWA
IMSDeviceManager.configure(providers: [IMSDeviceProvidable], shouldEnableAWA: Bool = false)

Kotlin

Both platforms use the shouldEnableAWA parameter in configure methods:

• When true: Changes are synchronized with the remote server immediately

• When false: Changes are only applied locally, without server communication

This flag provides flexibility for different usage scenarios:

1. Offline operations that will sync later

2. Batching multiple changes for efficiency

3. Handling poor connectivity conditions

Fetching missing vehicles API

Swift

// IMSDeviceManager
func fetchMissingVehicles(completion: @escaping (Result<(wedges: [Wedge], missingVehicles: [Vehicle])>))

Kotlin

Purpose

This method allows client applications on both Android and iOS platforms to:

1. Retrieve the current set of registered wedge devices from the server

2. Retrieve the available vehicles from the server

3. Identify vehicles that do not have any associated wedge devices

Parameters

Android

• context: Context - The Android application context

iOS

• Completion handler version: completion - A callback to handle the result

Return Value

Both platform implementations return similar data:

• On success: Two lists<

  • List of Wedges - These are Wedges that have already been associated to a vehicle, which also contain the associated vehicleId

  • List of Vehicles - These are vehicles that do not have a wedge association

• On failure: An error describing what went wrong

Android

• Result<Pair<List<Wedge>, List<Vehicle>>>

iOS

• Completion handler: Result<(wedges: [Wedge], missingVehicles: [Vehicle])>

Usage Example

Swift

// Fetch missing vehicles and process results
IMSDeviceManager.fetchMissingVehicles { result in
    switch result {
    case .success(let data):
        let (wedges, missingVehicles) = data
        
        // Use wedge information
        wedges.forEach { wedge in
            // Process each wedge
            print("Wedge: \(wedge.name), ID: \(wedge.deviceId)")
        }
        
        // Handle unassociated vehicles
        missingVehicles.forEach { vehicle in
            // Process each vehicle without an associated wedge
            print("Missing vehicle: \(vehicle.name), ID: \(vehicle.vehicleId)")
        }
        
    case .failure(let error):
        // Handle the error case
        print("Error fetching missing vehicles: \(error.localizedDescription)")
    }
}

Kotlin

Error Handling

The API can return failures in the following scenarios:

• Network connectivity issues

• Authorization or authentication failures

• Server-side errors

• Invalid or unexpected data formats

Android

Handle errors through the Result.onFailure callback or by catching exceptions.

iOS

Handle errors through the Result.failure case in the completion handler.

1. Call within a coroutine: This is a suspending function that should be called from within a coroutine scope

2. Error handling: Always handle potential failures in the Result object

3. UI updates: Since this involves network operations, don't call directly from the UI thread

4. Rate limiting: Avoid calling this method excessively to conserve network and battery resources

Related APIs

Both platforms provide similar device management APIs:

Swift

// Get locally stored devices
IMSDeviceManager.associatedDevices -> Set<IMSDevice>

// Associate a device
IMSDeviceManager.associateDevice(
    _ device: IMSDevice, 
    completion: @escaping (Result<Void>)
)

// Unassociate a device
IMSDeviceManager.disassociateDevice(
    _ device: IMSDevice, 
    completion: @escaping (Result<Void>)
)

Kotlin

Thread Safety

• Android: The API is thread-safe and uses coroutines with appropriate dispatchers

• iOS: The API is thread-safe and uses GCD (Grand Central Dispatch) to manage background operations

Platform-Specific Requirements

Android

• Minimum SDK version: 21 (Android 5.0)

• Permissions: INTERNET, ACCESS_NETWORK_STATE

• Kotlin Coroutines library

iOS

• Minimum iOS version: 13.0 (iOS 15.0+ for async/await)

• No special permissions required

Best Practices

1. Connection Handling: Check for network connectivity before calling

2. Error Handling: Always implement proper error handling

3. UI Updates: All returned data should be used to update UI on the main thread

Limitations (iOS Only)

• Initial Connection Requirement: Secondary users must maintain an active device screen when first accessing wedges previously associated by primary users through Automatic Wedge Association.

• Trip Capture: After successful initial pairing, trip capture operates normally without screen wake requirements.

• Impact: Connection attempts fail when the device screen remains locked during initial association, though the system continues retry attempts at each trip initiation.

• Workaround: Ensure device screens remain unlocked when secondary users initially access primary user-associated wedges via Automatic Wedge Association.

• Technical Impact: This constraint affects user handoff mechanisms in multi-user environments where wedges are shared through the Automatic Wedge Association feature.