Bluetooth & BLE Discovery

Relevant source files

The following files were used as context for generating this wiki page:

• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/BluetoothListScreen.kt
• app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/details/BluetoothDetailsScreen.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/ScannerService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt
• app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/lists/BluetoothListScreen.kt
• app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/maps/BluetoothMapScreen.kt

The Bluetooth and Bluetooth Low Energy (BLE) Discovery system in ShadowCheck Mobile is a core component designed for the detection, analysis, and geographical logging of nearby wireless devices. It operates as a background intelligence service that identifies both "Classic" Bluetooth devices and BLE beacons, cross-referencing them with GPS coordinates to facilitate wardriving and surveillance detection.

The system is architected to handle high-frequency scanning through specialized foreground services, ensuring continuous data collection even when the application is not in the foreground. It integrates with a local SQLite database (Room) to store unique device sightings, signal strength (RSSI), and hardware metadata.

Sources: README.md, app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt:18-35, app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:6-50

Architecture and Data Flow

The discovery architecture relies on a central service, the CompleteScannerService, which manages dual-mode scanning (Classic and BLE) and location synchronization.

Scanning Lifecycle

1. Service Activation: The scanner starts as a foreground service with the action START, attaching to a persistent notification.
2. Location Coupling: The service requests updates from both GPS and Network providers. Discovery only proceeds if hasValidLocation is true (accuracy < 50m).
3. Concurrent Discovery:
   • BLE Scanning: Uses BluetoothLeScanner with a ScanCallback to capture advertising packets.
   • Classic Discovery: Triggers startDiscovery() and listens for ACTION_FOUND broadcasts.
4. Deduplication: The system applies a 30-second deduplication window. If a device was seen within the last 30 seconds, the database record is updated; otherwise, a new sighting is logged.

The following diagram illustrates the data flow from hardware sensors to persistent storage:

Diagram shows the flow of hardware signals through the CompleteScannerService logic to the local database.
Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/CompleteScannerService.kt:126-200, app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/service/ScannerService.kt:80-95

Data Models

The system distinguishes between standard Bluetooth and BLE devices using two primary Room entities.

BluetoothDevice (Classic)

This entity tracks devices found via legacy discovery, typically including bonded peripherals and discoverable mobile devices.

Field	Type	Description
address	String	MAC address of the device (Primary Key source).
name	String?	Human-readable name (if broadcasted).
rssi	Int	Received Signal Strength Indication in dBm.
deviceClass	Int	Bluetooth Class of Device (CoD).
bondState	Int	Pairing status (10: None, 11: Bonding, 12: Bonded).
latitude/longitude	Double	Geo-coordinates at the moment of discovery.

BleDevice (Low Energy)

Specifically designed for beacons and IoT devices, capturing metadata from advertising packets.

Field	Type	Description
txPower	Int	Transmit power level reported by the device.
isConnectable	Boolean	Whether the device currently accepts connections.
serviceUuids	String	List of GATT services offered by the device.
manufacturerData	String	Specific data provided by the device vendor.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/data/Entities.kt:6-50, app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/details/BluetoothDetailsScreen.kt:87-104

User Interface and Visualization

The UI layer provides three distinct ways to interact with discovered data: list views, detailed technical breakdowns, and map-based visualization.

Discovery Screens

• BluetoothListScreen: Provides a real-time list of nearby devices using a LazyColumn. It displays the device name, MAC address, and a color-coded RSSI indicator.
• BluetoothDetailsScreen: Displays exhaustive technical details, including the calculated "Signal Quality" (Excellent to Very Weak) based on RSSI thresholds and timestamps for when the device was "First Seen" and "Last Seen".
• BluetoothMapScreen: Uses the Google Maps SDK to plot device locations. Markers are filtered to only show devices with valid (non-zero) latitude/longitude data.

Sequence: Device Discovery to Detail View

The following sequence diagram outlines the interaction when a user discovers a device and views its details.

Diagram showing the sequence from hardware detection to user interaction in the UI.
Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/BluetoothListScreen.kt:33-45, app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/details/BluetoothDetailsScreen.kt:110-116, app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/maps/BluetoothMapScreen.kt:25-50

Technical Implementation Details

Signal Quality Logic

Signal quality is calculated dynamically in the UI layer to provide a user-friendly assessment of proximity and threat level:

private fun getSignalQuality(rssi: Int): String {
    return when {
        rssi >= -50 -> "Excellent"
        rssi >= -60 -> "Good"
        rssi >= -70 -> "Fair"
        rssi >= -80 -> "Weak"
        else -> "Very Weak"
    }
}

Sources: app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/details/BluetoothDetailsScreen.kt:110-118

Permissions and Requirements

The discovery system requires significant Android permissions, as specified in the Manifest:

• BLUETOOTH_SCAN: Required to initiate discovery.
• BLUETOOTH_CONNECT: Required to query device names/metadata.
• ACCESS_FINE_LOCATION: Required because Bluetooth discovery can be used to derive user location.
• FOREGROUND_SERVICE_LOCATION: Required for the CompleteScannerService to run in the background.

Sources: app/src/main/AndroidManifest.xml:5-20

Conclusion

The Bluetooth & BLE Discovery module serves as a robust tool for environmental signal intelligence. By combining background scanning, geographical tagging, and detailed device metadata, it allows for the identification of persistent surveillance devices and the mapping of personal area network (PAN) density. The multi-layered approach of separate Classic and BLE tracking ensures comprehensive coverage of the wireless spectrum within the ShadowCheck ecosystem.