WiGLE Integration

Relevant source files

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

• app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApi.kt
• app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApiService.kt
• app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleModels.kt
• app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleImporter.kt
• app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt
• app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/settings/APIKeysScreen.kt
• README.md

The WiGLE (Wireless Geographic Logging Engine) integration in ShadowCheckMobile allows users to interact with the WiGLE global database of wireless networks. This module provides capabilities to search for wireless access points, upload local wardriving data, and synchronize personal statistics with the WiGLE platform.

The integration serves as a bridge between the local device storage and the remote WiGLE API, enabling advanced SIGINT capabilities by augmenting local scans with global crowdsourced data.

Sources: README.md:14, app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApiService.kt

Architecture and Networking

The integration uses a layered architecture consisting of a Retrofit-based API interface, a service wrapper for business logic, and UI components for configuration and interaction.

API Communication Layer

Network communication is handled by WigleApiService, which utilizes Retrofit and OkHttpClient. It implements Basic Authentication using the user's WiGLE API Name and API Token.

The OkHttpClient includes an interceptor that injects the Authorization header into every request using Credentials.basic(apiName, apiToken).

Sources: app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApiService.kt:18-32, app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApi.kt

Data Models and API Endpoints

The system maps WiGLE's JSON responses into Kotlin data classes to manage network details, user statistics, and upload transaction statuses.

Core Data Structures

Class	Purpose	Key Fields
WigleNetwork	Represents a single access point	netid, ssid, trilat, trilong, encryption
WigleUserStats	User's global ranking and counts	discoveredWiFi, rank, totalWiFiLocations
WigleTransaction	Status of a file upload	transid, percentDone, discoveredGps, status

Sources: app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleModels.kt:14-38, app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleModels.kt:76-96

Supported API Endpoints

The WigleApi interface defines the following operations:

• User Stats: GET api/v2/stats/user retrieves the authenticated user's profile statistics.
• Network Search (V2/V3): GET api/v2/network/search allows searching for networks via SSID, BSSID (netid), or geographic bounding boxes (latrange, longrange).
• File Upload: POST api/v2/file/upload facilitates the transmission of wardriving files (CSV/KML) to the WiGLE database.
• KML Export: GET api/v2/file/kml/{transid} downloads processed transaction data in KML format.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/network/dto/WigleApi.kt:10-53

Wardriving Data Lifecycle

ShadowCheckMobile manages the lifecycle of WiGLE data through two primary operations: importing remote data into the local database and exporting local sightings to the WiGLE service.

Import Process

The WigleImporter class converts WigleNetwork objects retrieved from the API into local WifiNetwork entities. This process involves converting WiGLE's channel numbers to frequencies and parsing ISO-8601 timestamps.

Upload and Transaction Tracking

Users can upload wardriving files via the uploadFile method in WigleApiService. This uses a MultipartBody request containing the file and a "donate" flag.

Configuration and Security

WiGLE credentials (API Name and Token) are managed through a dedicated security interface.

Secure Credential Management

Credentials are not stored in plain text. The application uses EncryptedSharedPreferences via the AndroidX Security library to store API keys.

• UI Implementation: The APIKeysScreen provides input fields for "WiGLE API Key" (Token) and "API Name".
• Storage: Keys are encrypted using AES256-GCM.
• Persistence: Handled in SettingsScreen.kt using getEncryptedPrefs(context).

Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt:331-341, app/src/main/kotlin/com/shadowcheck/mobile/ui/screens/settings/APIKeysScreen.kt:117-133

Settings Integration

The SettingsScreen provides multiple entry points for WiGLE integration, including:

1. Import WiGLE Database: Buttons to trigger bulk imports.
2. Manage API Keys: Launching the APIKeysScreen.
3. Import WiGLE CSV: Specific utility for importing files locally rather than through the API.

Sources: app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt:102-111, app/src/main/kotlin/com/shadowcheck/mobile/rebuilt/ui/screens/SettingsScreen.kt:151-160

Summary

The WiGLE Integration module provides a robust framework for external data synchronization. By combining a secure credential storage system with a typed API service and data transformation logic, it enables the application to contribute to and benefit from the global wireless mapping community. Implementation details in WigleApiService and WigleImporter ensure that network metadata is accurately translated between local and remote environments.