Troubleshooting & Known Issues
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance on identifying, resolving, and managing common issues encountered within the ShadowCheck Mobile application. It focuses on administrative actions available to users and developers to maintain data integrity and system performance.
The application includes built-in maintenance tools accessible via the Settings interface to address database bloat, missing telemetry, and service dependencies.
Data & Database Maintenance
ShadowCheck Mobile collects significant amounts of network data across WiFi, Bluetooth, and cellular interfaces. Over time, this can lead to performance degradation or storage issues. The application provides specific management functions to mitigate these problems.
Database Purging Operations
Users can perform several tiers of data deletion to troubleshoot performance or clear storage. These operations interface directly with ShadowCheckDatabase through the SettingsScreen.
- Purge Sensor Data: Deletes all records from the
sensorReadingDaoto free up space occupied by high-frequency environmental data. - Delete Records Without GPS: Specifically targets network sightings that lack spatial context, ensuring the mapping feature remains accurate.
- Clear All Data: A destructive operation that wipes all 13 entities, including WiFi networks, Bluetooth devices, cellular towers, and sighting records.
Sources: SettingsScreen.kt:130-178, README.md:65-79
The diagram above illustrates the flow of database maintenance tasks initiated from the UI.
Data Integrity Issues
One known issue involves "orphaned" records where network detections are stored without corresponding GPS coordinates. The SettingsScreen provides a specific dialog to permanently delete these records to prevent map clutter.
Sources: SettingsScreen.kt:216-241
Google Play Services & AR Core Dependencies
The application relies heavily on Google Play Services and AR Core for mapping and Augmented Reality features. Missing or outdated versions of these services are common sources of failure.
Required Service States
The following table summarizes the error states associated with Google Play Services dependencies:
| Error String Resource | Trigger Condition | Recommended Action |
|---|---|---|
common_google_play_services_install_text | Service missing from device | Install via Play Store |
common_google_play_services_update_text | Outdated service version | Update service |
common_google_play_services_enable_text | Service is disabled | Enable in Android settings |
__arcore_install_app | Missing AR Core for AR view | Install AR Services |
Sources: strings.xml (en-rGB):45-60, strings.xml (en-rGB):4-8
AR Initialization Flow
When accessing the AR View, the system checks for the latest AR services. Failure at any point in this sequence will result in a prompt to the user.
The sequence above shows the dependency check conducted for advanced features.
Sources: strings.xml (fa):4-8, strings.xml (fa):45-60
Configuration & API Management
Incorrectly configured API keys for WiGLE, Mapbox, or Google Maps can cause mapping or data upload failures.
API Key Security
API keys are stored using EncryptedSharedPreferences with AES256_GCM encryption. Issues with key retrieval usually stem from MasterKey corruption or invalid input.
- Mapping Failures: If the
map_provideris set to "Mapbox" but the Mapbox API key is missing or invalid, the interactive map will fail to render. - WiGLE Integration: Uploading wardriving data requires a valid WiGLE API key managed through the "Manage API Keys" dialog.
Sources: SettingsScreen.kt:279-317, SettingsScreen.kt:350-363
Settings Configuration Options
| Option | Default | Impact if Misconfigured |
|---|---|---|
| Scan Interval | 3s | Too low may cause battery drain; too high misses networks. |
| Map Provider | Mapbox | Map rendering depends on the specific provider's API key. |
Sources: SettingsScreen.kt:47-111
User Interface & Localization
The application supports multiple locales (e.g., Farsi, Hebrew, Oriya, Kannada). Issues with UI rendering or "Default Error Message" (Invalid Input) are often handled via the resource strings.
- Invalid Input: Triggered when text fields (like API keys) do not meet expected formats.
- Resource Missing: Incomplete translations may revert to default English strings, particularly in the
SettingsScreenorTopAppBar.
Sources: strings.xml (en-rGB):71, strings.xml (fa):83, strings.xml (kn):80
Troubleshooting Summary
Most functional issues in ShadowCheck Mobile can be resolved by:
- Verifying Google Play Services and AR Core status.
- Ensuring valid API keys are saved in Encrypted Preferences.
- Performing database maintenance (Purge/GPS Cleanup) to resolve performance lag.
Sources: README.md:100-105, SettingsScreen.kt:130-170