Getnet DocsGetnet Docs

Debug Bluetooth Connectivity

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Bluetooth connectivity on iOS is subject to strict system requirements and permissions. This guide helps you troubleshoot common Bluetooth pairing and connection issues when integrating the Get Mini SDK with PIN pad devices.

Common Bluetooth Issues

Understanding common Bluetooth problems and their solutions helps you quickly diagnose connectivity issues during development and deployment.

App Crashes on Scan

If your application crashes immediately when calling scanForReaders, the most common cause is missing Bluetooth permission declarations. iOS terminates apps that attempt Bluetooth operations without proper Info.plist configuration.

Check your Info.plist file and verify it contains the NSBluetoothAlwaysUsageDescription key with a non-empty string value. This permission key is mandatory for iOS 13 and later. Without it, any Bluetooth scanning attempt causes immediate app termination. Add the missing key through Xcode’s Info tab or by directly editing the plist source code.

For legacy iOS version support, also include NSBluetoothPeripheralUsageDescription in your Info.plist. Refer to the Configure iOS Permissions guide for complete permission setup instructions.

Reader Not Appearing in Scan Results

When Bluetooth scanning completes but returns an empty list of readers, several conditions could prevent reader discovery. Verify the PIN pad device is in pairing mode—the Bluetooth indicator should flash to signal availability. Check that no other application or device currently maintains an active connection to the PIN pad, as Bluetooth readers typically support only one active bond at a time.

If the reader still doesn’t appear, try resetting the PIN pad device by holding the power button for 10 seconds until it powers off, then power it back on. Verify that Bluetooth is enabled on the iOS device through system settings. Check that location services are enabled, as iOS requires location access for Bluetooth LE scanning even though the SDK doesn’t use GPS functionality.

Move the iOS device closer to the PIN pad to improve signal strength. Ensure the PIN pad battery has sufficient charge. Try scanning from a different iOS device to determine if the issue is device-specific or PIN pad-specific.

Connection Drops in Background

If Bluetooth connections disconnect immediately when the device screen locks or the app enters background mode, the application lacks background Bluetooth capabilities. By default, iOS suspends Bluetooth operations when apps move to the background.

Enable the “Uses Bluetooth LE accessories” background mode in your Xcode project. Navigate to your target’s “Signing & Capabilities” tab, click ”+ Capability”, select “Background Modes”, and check the “Uses Bluetooth LE accessories” box. This capability allows your app to maintain Bluetooth connections while backgrounded.

Background Bluetooth operations increase battery consumption. Only enable background mode if your application genuinely requires maintaining PIN pad connections while backgrounded. For most payment applications, foreground-only operation provides adequate functionality with better battery performance.

Advanced Debugging Techniques

When basic troubleshooting doesn’t resolve connectivity issues, advanced debugging techniques can help identify root causes.

Reset iOS Bluetooth Cache

Sometimes the iOS system Bluetooth cache maintains stale connection information that prevents new bonds from establishing. Clearing this cache often resolves persistent pairing problems.

Open the Settings app on your iOS device and navigate to Bluetooth settings. Locate the PIN pad reader in the device list—readers typically appear with names like “RP-XXXX” or similar identifiers. Tap the information icon next to the reader name and select “Forget This Device” to remove cached connection data.

After forgetting the device, toggle Bluetooth completely off and then back on through iOS settings. This clears any remaining cached state. Return to your application and attempt scanning again to establish a fresh connection.

Monitor Bluetooth System Logs

For persistent issues, enable iOS system logging to capture detailed Bluetooth communication data. Connect your iOS device to a Mac running Xcode and open the Devices and Simulators window. Select your device and enable the “Connect via network” option to capture wireless logs.

In the Console app on your Mac, filter logs by “bluetooth” or “CoreBluetooth” to see low-level Bluetooth system messages. These logs reveal timing issues, permission problems, or hardware communication errors that aren’t visible through application-level diagnostics.

Verify Physical Hardware

If troubleshooting doesn’t resolve connectivity issues, test the PIN pad device with another iOS device or application to verify hardware functionality. Contact Get Mini support if the PIN pad consistently fails to pair with multiple devices, as this may indicate hardware failure requiring replacement or repair.

Check that the PIN pad firmware is up to date through Get Mini support tools. Outdated firmware sometimes causes compatibility issues with newer iOS versions.

Next Steps