Testing and Debugging

This guide covers logging, diagnostics, common issues, and debugging strategies for the MOSA SDK.

Logging

Android

Enable advanced logging:

val sdk = MOSADockSDK.builder()
    .setActivity(this)
    .setApiKey("your-api-key")
    .setUserId("user-123")
    .setAdvancedLogging(true)  // Enable advanced logging
    .build()

View logs in Logcat:

adb logcat | grep -i "MOSADockSDK"

iOS

Logging is enabled by default. View logs in Xcode console or system logs:

// Logs are automatically output to console
// Use Xcode's console or Console.app to view

Filter logs:

log stream --predicate 'subsystem == "com.mosa.docksdk"' --level debug

Flutter

Listen to SDK logs:

mosaDockSdk.sdkLogs.listen((log) {
  print('SDK Log: ${log['level']} - ${log['message']}');
});

Common Issues

Issue: NFC Not Working

Symptoms: NFC scan fails or doesn't start

Solutions:

1. Check NFC is enabled in device settings
2. Verify NFC permission is granted
3. Ensure device supports NFC (iPhone 7+ for iOS, Android 7.0+)
4. Check NFC tag is within range (~4cm)
5. Verify NFC tag is valid MOSA dock tag

Issue: BLE Connection Fails

Symptoms: BLE connection fails or times out

Solutions:

1. Check Bluetooth is enabled
2. Verify BLE permissions are granted
3. Ensure device supports BLE
4. Check dock is powered on and in range
5. Verify MAC address from NFC scan is correct
6. Try disconnecting and reconnecting

Issue: Key Request Fails

Symptoms: requestUnlockKey() returns null or throws error

Solutions:

1. Check internet connectivity
2. Verify API key is valid
3. Ensure user ID is correct
4. Check area ID exists and is valid
5. Verify session requirements are met
6. Check backend API status

Issue: Dock Operation Times Out

Symptoms: Operation times out before completion

Solutions:

1. Ensure dock is powered on
2. Check BLE connection is stable
3. Verify unlock key is not expired
4. Check dock is not in use by another user
5. Verify dock firmware is compatible
6. Try operation again

Issue: Callbacks Not Received

Symptoms: Callbacks are not called during operations

Solutions:

1. Android: Ensure callback is passed to unlockSmartLock()
2. iOS: Ensure delegate is set before operation
3. Flutter: Ensure event stream subscription is set up before initializing SDK
4. Verify callbacks are on main thread (should be automatic)
5. Check for errors in onError callback

Issue: Sync Not Working

Symptoms: Events not syncing to backend

Solutions:

1. Check internet connectivity
2. Verify sync is enabled
3. Check pending events count: getPendingEventsCount()
4. Manually trigger sync: forceSyncNow()
5. Check sync errors in logs
6. Verify API key is valid

Debugging Tips

Enable Verbose Logging

Enable advanced logging to see detailed SDK operations:

Android

val sdk = MOSADockSDK.builder()
    .setAdvancedLogging(true)
    .build()

iOS

// Logging is enabled by default
// Use Xcode console to view logs

Flutter

// Listen to SDK logs
mosaDockSdk.sdkLogs.listen((log) {
  print('SDK: ${log['level']} - ${log['message']}');
});

Check Device Capabilities

Always verify device capabilities before operations:

Android

if (!sdk.isBLESupported() || !sdk.isNFCSupported()) {
    // Device doesn't support required features
}

if (!sdk.isBLEEnabled() || !sdk.isNFCEnabled()) {
    // Features are disabled
}

iOS

if !sdk.isBLESupported() || !sdk.isNFCSupported() {
    // Device doesn't support required features
}

Flutter

final bleSupported = await mosaDockSdk.isBleSupported();
final nfcSupported = await mosaDockSdk.isNfcSupported();
final bleEnabled = await mosaDockSdk.isBleEnabled();
final nfcEnabled = await mosaDockSdk.isNfcEnabled();

Monitor Connection State

Monitor BLE connection state:

Android

sdk.getBleConnectionStateFlow().collect { connected ->
    println("BLE Connected: $connected")
}

iOS

sdk.bleConnectionPublisher
    .sink { connected in
        print("BLE Connected: \(connected)")
    }

Flutter

mosaDockSdk.bleConnectionStateEvents.listen((event) {
  print('BLE Connected: ${event.connected}');
});

Check Key Expiry

Always check key expiry before use:

Android

val isExpired = unlockKey.expiryTime <= (System.currentTimeMillis() / 1000)
if (isExpired) {
    // Request new key
}

iOS

let currentTime = Int(Date().timeIntervalSince1970)
if unlockKey.expiryTime <= currentTime {
    // Request new key
}

Flutter

if (unlockKey.isExpired) {
  // Request new key
}

Troubleshooting Checklist

Use this checklist when debugging issues:

• Device supports NFC and BLE
• NFC and BLE are enabled
• Required permissions are granted
• SDK is properly initialized
• API key is valid
• User ID is correct
• Internet connectivity available (for key requests)
• Dock is powered on and in range
• NFC tag is valid MOSA dock tag
• Unlock key is not expired
• Callbacks are properly set up
• Error callbacks are implemented
• Logs are checked for errors

Getting Help

If you're still experiencing issues:

1. Check Logs: Review SDK logs for error messages
2. Verify Setup: Ensure all prerequisites are met
3. Test with Sample App: Try the sample app to verify SDK works
4. Contact Support: See Support for help

Next Steps

• SDK Callbacks - Callback troubleshooting
• Support - Get help from support team

---

For platform-specific debugging, see the Platform Guides.