Hotspotter

Warning

The official paper for Hotspotter is currently pending acceptance and publication into a conference. Until then, it cannot be included nor linked in this repository. Once this is available, the repository will be updated with the relevant links and details.

Hotspotter is an incentivized crowdsensing system that collects, maps, and visualizes WiFi and cellular data to pinpoint hotspots and dead zones for the effective visualization of network coverage.

The system is composed of three subsystems: the database subsystem (PostgreSQL + Uber H3), the web subsystem (SvelteKit), and the mobile subsystem (Android + CapacitorJS + SvelteKit). The Android API enables data collection via the Fused Location Provider API, the Telephony Manager API, WiFi Manager API, and Google identity providers. More details on the system design can be found in the published paper.

Development

The mobile application is a single-page SvelteKit application powered by the Capacitor runtime for cross-platform WebView-based applications. However, this project only targets the Android platform for now.

Prerequisites

• PostgreSQL
• Node.js
• pnpm
• Android Studio
  • platform-tools
  • platforms;android-34
  • build-tools;34.0.0
• OpenJDK 17
• Android 10 (API 28)

Development

The following sections explain how to get an instance of the project set up.

Installing Corepack

We use Corepack as the package manager "manager" for Node.js, which should come pre-installed with the default distributions. Corepack is responsible for fetching and proxying the correct version of pnpm based on the packageManager entry of the package.json file.

# This command should be available upon installing Node.js.
corepack enable pnpm

Environment Variables

In a .env file, populate the following environment variables.

Name	Description	Required	Default
MOBILE	If set to 1, builds the SvelteKit application as a static site for the mobile app.	❌	0
POSTGRES_URL	Connection URL to the PostgreSQL instance.	✔
PUBLIC_GOOGLE_APP_CLIENT_ID	The OAuth app client ID for Android from the Google Cloud console.	✔
PUBLIC_GOOGLE_WEB_CLIENT_ID	The OAuth web client ID from the Google Cloud console.	✔
PUBLIC_HOTSPOTTER_URL	The base endpoint for the Hotspotter API.	✔

# Example Configuration
MOBILE=1
POSTGRES_URL='postgres://127.0.0.1/postgres'
PUBLIC_GOOGLE_APP_CLIENT_ID=18878593077-vsfeephdmnr5035916obko0cbjq02djm.apps.googleusercontent.com
PUBLIC_GOOGLE_WEB_CLIENT_ID=18878593077-1mfrpdc8kfs9p5f6fm3ac5lruq1bmpp5.apps.googleusercontent.com
PUBLIC_HOTSPOTTER_URL='https://hotspotter.vercel.app/'

Setting up the Database Utilities

The project uses PostgreSQL as the primary database for storing and querying uploaded readings. However, the default installation does not inject the Postgres helper utilities into the PATH. To do so, simply add the C:\Program Files\PostgreSQL\16\bin folder¹ to the PATH.

# Running these helper commands should now be available.
postgres --version
initdb --version
psql --version

Disabling the Global Database Service

Note that the default installation adds a background Windows service that hosts the postgres server on 127.0.0.1:5342. Although the global service does make it convenient to get started, we opt to disable the global instance in favor of a more local instance.

Using an administrator-level PowerShell session:

$Postgres = 'postgresql-x64-16'
Stop-Service -Name $Postgres
Set-Service -Name $Postgres -StartupType Disabled

Initializing the Local Database

With the global database service disabled, we can now host our own local instance without conflicting on 127.0.0.1:5432. We start by initializing the data/ folder in which PostgreSQL will store all tables, rows, and columns.

# Create the `data/` folder.
pnpm db:init

# Start the database server.
pnpm db:start

Note

At this point, the terminal should be hijacked by the database server logs. From now on, we should spawn a new terminal tab to enter more commands. We just leave the database server running in the background. This is effectively what the background service did for us.

We now initialize the database tables and columns with psql.

# Run the `postgres/init.sql` script with `psql`.
pnpm db:migrate

Building the Mobile Application

Recall that the mobile application is a Capacitor application that wraps the statically generated web pages by SvelteKit. The produced .html, .css, and .js files are effectively what gets loaded as the user interface.

# Install the dependencies.
pnpm install

# Compile the production build (i.e., with optimizations).
pnpm build

Warning

Whenever changes are made to the SvelteKit application, the build/ folder must be rebuilt with the pnpm build command. Many hours of debugging can be wasted on outdated build artifacts.

Signing the Mobile Application

To sign the release APKs, one can generate a 2048-bit RSA private key (valid for 365 days) using the following keytool command.

keytool -genkey -v -keystore android/app/store.jks -keyalg RSA -keysize 2048 -validity 365 -alias hotspotter

To configure Gradle to sign the debug and release APKs, create a android/app/keystore.properties file that contains the following passwords (as previously provided to the keytool command).

storeFile=store.jks
storePassword=
keyAlias=hotspotter
keyPassword=

Installing the Mobile Application

With the build/ now available, we can now install the application into the Android device. There are two ways to run the application:

• In the actual device via USB. Ensure that USB debugging is enabled.
• Via the Android emulator. Ensure that the selected system image already contains Google Play Services within the latest Android version.

Physical Device

# Find the ID of the connected device via USB.
pnpm run:android --list

# Copy the `build/` into the APK and then
# run the application in the physical device.
pnpm run:android --target $ID

Android Emulator

# Copy the `build/` folder into the APK and
# then run the application in an emulator.
pnpm run:android

Code Quality

These are the commands that automate code quality assurance. All main code must pass the tests.

# Check Formatting
pnpm fmt # prettier

# Apply Formatting Auto-fix
pnpm fmt:fix # prettier --write

# Check Linting Rules
pnpm lint:html   # linthtml
pnpm lint:css    # stylelint
pnpm lint:js     # eslint
pnpm lint:svelte # svelte-check

# Check All Lints
pnpm lint

Acknowledgements

This project was developed in fulfillment of the final requirements for the attainment of a Bachelor of Science degree in Computer Science under the Department of Computer Science, College of Engineering, University of the Philippines Diliman.

The following researchers were involved in this year-long project:

• Sebastian Luis S. Ortiz
• Justin Gabriel R. Enriquez

The research conducted in this project would not have been possible if it weren't for the following research advisers:

• Dr. Wilson M. Tan
• Dr. Cedric Angelo M. Festin

The Hotspotter logo was designed and created by:

• Angelica Julianne A. Raborar

Footnotes

1. This is the default installation location. Setups may vary. ↩