Quintz
2.1.0 · GitHub
More about this app
Rootless Wi-Fi band locker and BSSID steering tool that pins Android to 5/6 GHz via Shizuku, with AP telemetry and an RF direction finder.
Quintz โก
Wi-Fi Band Preference, BSSID Pinning & RF Telemetry for Android.
Overview
Quintz is a rootless Wi-Fi utility for choosing radios and monitoring connections on dual-band and mesh networks.
Routers can broadcast 2.4 GHz, 5 GHz, and 6 GHz under one SSID. Android may remain on a 2.4 GHz radio after a stronger higher-band radio becomes available. Quintz lets you prefer 5/6 GHz, pin a specific BSSID, or return a network to normal auto-roaming.
Quintz uses Shizuku to access Android's Wi-Fi service without requiring root. It combines per-network steering intent, a background recovery watchdog, an AP scanner, and rolling RF telemetry. Available bands and successful transitions depend on the device, router, and Android Wi-Fi implementation.
Key Features
๐ 1-Tap 5 GHz Preference (No Root Required)
- Selects a strong 5 GHz / 6 GHz BSSID on your network, then keeps the saved profile available for roaming.
- The preferred-band action is not a permanent BSSID pin: Android and the Wi-Fi firmware can still roam to another BSSID or band when conditions require it.
- Use a specific BSSID lock when you need to keep the profile pinned to one access point.
- Quintz stores Auto, Prefer 5 GHz, or Pin BSSID intent per SSID, so changing one network does not change the watchdog target for another.
- Supports WPA2-Personal, WPA3-SAE, Enhanced Open (OWE), and open networks.
- Profile changes require a compatible Android Wi-Fi framework and authorized Shizuku access.
๐ก๏ธ Smart Fallback Watchdog
- Runs as a foreground service and checks the connected band while the watchdog is enabled and Shizuku is available.
- The 5 GHz preference leaves the saved profile unpinned so Android or device firmware can roam to 2.4 GHz when needed. The watchdog does not trigger an unlock at a particular 5 GHz RSSI value.
- When the device is connected to the target SSID on 2.4 GHz, the watchdog scans for a same-SSID 5 GHz / 6 GHz BSSID. The default recovery threshold is
-72 dBm. - A successful
start-scancommand only means Android accepted the request. Quintz waits up to 12 seconds for evidence that the target network's 5/6 GHz scan result refreshed, and excludes those candidates if it did not. - Recovery requires the same eligible BSSID in two fresh observations at least 10 seconds apart. If confirmed, Quintz requests a BSSID-specific transition, verifies that the target BSSID became active, then unpins the saved profile again so roaming remains allowed.
- For a pinned network, the watchdog monitors and restores that exact BSSID (on either band), then verifies the hard profile pin. Auto mode does not trigger band or BSSID recovery.
- The recovery scan interval starts at about 12 seconds and backs off to 30 seconds when no eligible candidate is found or a recovery attempt fails. Failed switch attempts also receive a retry cooldown that increases from 60 seconds up to 5 minutes.
- Automatic recovery checks fresh observations and trusted security information. Secured networks require a saved password; open and OWE networks require an explicit trusted radio choice instead of automatic same-name band selection.
- Missing credentials, unavailable Shizuku, stale results, profile recovery conflicts, or Android/OEM behavior can prevent or delay a switch. Recovery can interrupt the connection.
โ๏ธ How BSSID Pinning Works
- Saved-profile changes: A Shizuku user service reads and updates Android's Wi-Fi configuration, sets or clears its BSSID pin, and requests reassociation. Status and scan paths also use
cmd wifianddumpsys wifiwhere appropriate. - Verification and recovery: Before changing a profile, Quintz saves an encrypted recovery record. It checks profile readback and the resulting connection before committing the new intent. Failed or interrupted transitions attempt to restore the previous profile and app settings; a changed or unverifiable profile can leave recovery pending.
- Per-network MAC policy: Shows Android's configured Device MAC or persistent Randomized MAC, separately from Quintz's saved preference and the observed address. Choosing the configured policy does nothing. In Auto mode, a change updates the saved Android profile for the next connection without issuing a reconnect. With an active BSSID pin or 5 GHz preference, Quintz reconnects the same network, keeps that mode and pin, and verifies the observed MAC. Router reservations can be affected.
- Separate password storage: The password status shows whether Quintz has its own encrypted copy, independently of Android's saved network. MAC-only changes reuse Android's existing profile and do not require a password copy in Quintz. Forgetting the Quintz copy leaves Android's saved network intact.
- Device limits: A saved-profile pin cannot guarantee uninterrupted association. The watchdog attempts to restore the selected BSSID for Pin BSSID intent, or return to an eligible 5/6 GHz radio for Prefer 5 GHz intent.
๐ Real-Time Roaming & RF Telemetry Monitor
- Rolling graphs for active connection RSSI and PHY link speed over the last minute.
- Connected signal and link-speed cursors stay at NOW, holding the latest value between readings; the cursor disappears if observations stop for more than 7.5 seconds.
- Multi-AP Roaming Crossover Detection: Plots recent same-network candidate scan readings as thin lines with dots at measured observations. Measured lines break across gaps longer than 20 seconds or channel/band changes. A lighter dashed tail holds the last known value to NOW; its dot stays at the actual observation time. Readings too old for a live comparison are marked stale, with dimmer held tails.
- Candidate scans consume Android's scan-completion notifications, with bounded polling when notifications are unavailable. Foreground scanning pauses briefly after success and backs off when results do not refresh. Candidate rows show observation age; they are not one-second live measurements.
- This scan path supports Android 10+ (the app's minimum version) through Shizuku. Scan latency and availability depend on Android, OEM firmware, and Wi-Fi hardware; neither scan requests nor completion notifications guarantee a fresh reading of every AP.
- Color-Coded RF Quality Bands: Visual thresholds for Optimal (
> -65 dBm), Evaluation (-65 to -75 dBm), and Roam / Weak (< -75 dBm) zones. - Automated Handoff Event Tracking: Drops timestamped event pins whenever band or BSSID transitions take place.
- Candidate actions: Bind to an eligible radio from the telemetry monitor. Cached history remains visible for up to a minute, but a live comparison requires a recent observation from the latest scan; displaying a radio does not make it actionable.
๐ AP Scanner & Channel Analyzer
- Scans and lists all nearby access points, frequencies, channel numbers, and MACs.
- Clear indicators for Wi-Fi standards (11n, 11ac, 11ax, Wi-Fi 7).
- Rows distinguish ACTIVE (the connected radio) from PINNED (the saved target).
- Actions show
PINfor the active unpinned radio,UNPINfor a pinned radio, andBINDfor other eligible radios. A saved pin can be cleared even when that radio is not the active connection.
โก Quick Settings Tile
- Switches an Auto network to Prefer 5 GHz, or returns a steered/pinned network to Auto from the Quick Settings shade.
- Requires authorized Shizuku and saved credentials for secured-network preference. Missing credentials or an open/OWE network's explicit radio selection opens the app.
- The subtitle shows connection/steering status. Returning the last steered network to Auto stops the watchdog; other saved targets can keep it enabled.
๐ Background Work & Resource Use
- UI status polling, scanning, and telemetry stop when the app leaves the foreground. Scanner and telemetry work also follow the selected screen and telemetry pause state.
- An enabled watchdog continues status checks and recovery scans in its foreground service while the app is minimized. It uses scan backoff and switch cooldowns, and stops when no saved steering targets remain.
- Graph drawing caches reusable geometry and text measurements. Smooth animation preserves measurement timestamps; it does not create extra RF readings or guarantee a particular frame rate or battery cost.
Prerequisites
- Android 10 or later (minimum API 29; compile/target SDK 35).
- Shizuku (v13+ recommended).
- Profile capture and mutation currently allow SDK 29โ36 and require successful runtime capability checks. This range does not establish compatibility with every device or manufacturer. WEP, enterprise Wi-Fi, Passpoint, ambiguous profiles, and unavailable profile credentials are not supported by the full profile-change path.
Why Shizuku?
Since Android 10, Google restricted third-party applications from programmatically managing Wi-Fi networks and BSSID associations. Shizuku runs a privileged system service that lets user apps execute authorized system shell commands without modifying Android system files or rooting your device.
Set up Shizuku:
- Install Shizuku from Google Play or its official GitHub releases.
- On Android 11+, follow Shizuku's wireless-debugging pairing and startup steps. On unrooted Android 10, start it through ADB from a computer. See the official setup guide.
- Open Quintz and grant Shizuku access when prompted.
With either non-root startup method, Shizuku must be started again after a device reboot. Android battery restrictions or loss of Shizuku access can interrupt watchdog recovery.
Building from Source
Requirements
- JDK 21
- Android SDK Platform 35 and Build Tools 35.0.0 (used by release signing)
- Git
- Android SDK Platform Tools / ADB for device installation and tests
Configure the SDK location using Android Studio or an ignored local.properties file with sdk.dir. The repository includes the Gradle wrapper.
Steps
Clone the repository:
git clone https://github.com/corgilittlelegs/Quintz.git cd QuintzBuild an installable debug APK:
./gradlew :app:assembleDebugInstall to your connected device via ADB:
adb install -r app/build/outputs/apk/debug/app-debug.apk
Debug builds use package ID com.quintz.wifi.debug and can coexist with the release package com.quintz.wifi. Updating a debug installation requires the same debug signing key.
Release Builds & Signing
./gradlew :app:assembleRelease
This produces app/build/outputs/apk/release/app-release-unsigned.apk, which must be signed before installation. Release builds enable R8 code and resource shrinking. The manual release workflow supplies version values and signs the APK using externally supplied legacy/rotated keys and their signing lineage. Follow release signing for the required environment variables and GitHub secrets, and release versioning for version/tag behavior.
Local signing material belongs in the ignored keystore/ directory and must be backed up separately. Gradle does not fall back to debug signing for release builds.
Verification
Run the same build, unit-test, and lint gate as the verification workflow:
./gradlew :app:testDebugUnitTest :app:testReleaseUnitTest \
:app:lintDebug :app:lintRelease \
:app:assembleDebug :app:assembleDebugAndroidTest :app:assembleRelease \
--no-daemon --console=plain
Run Android instrumentation tests with a connected device or emulator:
./gradlew :app:connectedDebugAndroidTest --no-daemon --console=plain
Some profile-access/recovery tests require authorized Shizuku and specific device state, and skip when those prerequisites are absent. Passing the CI emulator tests does not verify real Wi-Fi reassociation, OEM compatibility, signed upgrades, or battery use.
GitHub Actions
| Workflow | Trigger | Result |
|---|---|---|
| Verify app | Push to main or pull request |
Unit tests, lint, both build variants, instrumentation packaging, and Android emulator tests |
| Build Debug APK | Manual Run workflow, with patch, minor, or major |
A versioned Debug prerelease under Releases, such as debug-v2.1.1, plus an Actions artifact retained for 14 days |
| Release APK | Manual Run workflow on main, with patch, minor, or major |
Tests/lint, release build, external signing, and a public GitHub release with APK and SHA-256 checksum |
Commit and sync the intended changes before running a manual build. Debug versions preview the chosen increase from the latest stable tag: stable 2.1.0 plus patch produces 2.1.1-debug. Download Quintz-2.1.1-debug.apk from that version's Debug prerelease, or extract its Quintz-2.1.1-debug Actions artifact. Repeated builds for the same version replace that prerelease's APK, matching checksum, and build details; the internal Android update code increases with each new run. Debug releases are marked Pre-release and do not replace the latest stable release. The workflow requires DEBUG_KEYSTORE_BASE64, reuses it for every build, and rejects missing keys or signing/version mismatches. See debug signing and updates for setup and migration.
Syncing code does not publish a release. Release signing secrets must be configured first; the workflow rejects missing signing material and checks that main still matches the release commit before publishing. The optional ./release.sh [patch|minor|major] command dispatches the same release workflow through GitHub CLI.
Debug Diagnostics
Debug builds include a diagnostics button in the app header. Open DIAGNOSTICS (DEBUG) and choose COPY for the current report, EXPORT to share a flight-recorder ZIP through Android's chooser, or CLEAR to clear recorded logs.
The recorder stores local diagnostic events, watchdog heartbeats, and available process-exit information. An unobserved interval records a gap with an unknown cause; it does not by itself prove a reboot or continuous monitoring. Release builds disable this recorder and its sharing UI.
Exports redact credential-bearing command arguments and recognized password fields, but include network names, BSSIDs, device details, and connection history. Review the archive before sharing it. Profile recovery payloads are kept separately in encrypted private storage and are not exported.
Architecture & Tech Stack
- Architecture: MVVM with unidirectional data flow (UDF) via Kotlin Coroutines and
StateFlow. - UI Framework: 100% Jetpack Compose with Material 3 and custom industrial cyber-tactical CLI design tokens.
- Security: Local network credentials encrypted using AndroidX
EncryptedSharedPreferences. - Profile Recovery: Encrypted durable recovery records, profile fingerprint/readback checks, and verified transition commits.
- System Integration: Shizuku user-service IPC for Wi-Fi profile access, plus bounded shell execution for status, scans, and system integration.
Privacy & Security
- Local operation: Wi-Fi steering and telemetry do not require a Quintz server. The app has no analytics or advertising integration. It requests Inter and JetBrains Mono from Google Play services' downloadable-font provider, which may fetch fonts over the network when they are not cached; see Android's downloadable-font documentation.
- Local credentials: Wi-Fi passwords use
EncryptedSharedPreferenceswith an Android Keystore key. Hardware backing depends on the device and is not guaranteed by this configuration. Password saving is refused when secure storage is unavailable. - Backup exclusions: Credential/settings preference files are excluded from Android cloud backup and device transfer. Profile recovery records and flight-recorder journals use private storage excluded from backup.
- User-controlled sharing: Debug reports are shared only through an explicit copy/export action; they can contain network and device identifiers.
- Open Source: Full source code is available for audit and verification.
Third-Party Open Source Credits & Acknowledgments
Quintz relies on and thanks the following open source projects:
Shizuku by Rikka Apps / RikkaW
Licensed under the Apache License 2.0
Enables rootless privileged API execution on Android devices.Android Jetpack & Jetpack Compose by Google / AOSP
Licensed under the Apache License 2.0
Modern UI toolkit, AndroidX lifecycle, architecture components, and crypto security.Kotlin & Kotlinx Coroutines by JetBrains
Licensed under the Apache License 2.0
Asynchronous stream processing and state management.JetBrains Mono by JetBrains
Licensed under the SIL Open Font License 1.1
Monospace typography used across telemetry readouts.
License
This project is licensed under the MIT License โ see the LICENSE file for details.
How Shizuku is used
Can pin Wi-Fi to a chosen 5 or 6 GHz radio, prefer fast bands, restore auto roaming, apply MAC choice and manage its Quick tile via `cmd wifi`, `dumpsys wifi` and privileged Wi-Fi calls through Shizuk
This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.
How this app uses Shizuku
Quintz uses Shizuku for privileged Wi-Fi profile and system operations that normal apps cannot perform.
- Lock to specific radio: pin the current network to a 5 GHz or 6 GHz access point the user picks by updating the saved profile with that access point address and reassociating to it through the privileged service.
- Prefer fast band: automatically pick the strongest eligible 5 GHz or 6 GHz radio and steer to it while leaving roaming allowed, using the same privileged profile update and reassociation.
- Restore auto roaming: clear the access point pin and return to normal automatic selection through the privileged service.
- Show live connection: read current network name, access point address, frequency, band, signal, speed and lock state with the
cmd wifi statusshell command through Shizuku plusdumpsys wifilookups, combined with normal Android connection info and privileged connection info. - Scan nearby radios: trigger a fresh scan with the
cmd wifi start-scanshell command through Shizuku and list nearby access points through the privileged scan results to show per radio signal, band, channel and security for steering choices, telemetry and direction finding. - Maintain lock automatically: background monitoring reuses the same status, scan, lock and unlock operations to fall back to auto roaming and to steer back when a strong 5 or 6 GHz radio returns.
- Control Quick tile: toggle between auto roaming and preferred 5 GHz directly from the Quick Settings tile using the same status, lock and unlock operations.
- Check Quick tile: read whether the app Quick Settings tile is installed with the
settings get secure sysui_qs_tilesshell command through Shizuku. - Remove Quick tile: remove the app Quick Settings tile with the
cmd statusbar remove-tileshell command through Shizuku, verified with a follow up tile list read. - Apply MAC mode: apply the per network MAC randomization choice selected in the app as part of the same privileged profile update.
Android APIs or commands used
IWifiManager.getPrivilegedConfiguredNetworksIWifiManager.addOrUpdateNetworkIWifiManager.removeNetworkIWifiManager.disableNetworkIWifiManager.enableNetworkIWifiManager.getConnectionInfoIWifiManager.getScanResultsIWifiManager.getFactoryMacAddressesWifiConfiguration.setSecurityParamsWifiConfiguration.getRandomizedMacAddresscmd wifi statusdumpsys wificmd wifi start-scansettings get secure sysui_qs_tilescmd statusbar remove-tile
Notable details
Without Shizuku the app falls back to read only Android connection info and cannot scan, lock, unlock or change MAC; tile status then uses a direct secure settings read or cached value.
Changelog
What's new for version 2.1.0
Quintz v2.1.0
Changes since v2.0.0
๐ New Features
- feat: set make_latest to true in release workflow (b9a7926)
- feat: add Shizuku-backed Wi-Fi profile service and recovery mechanisms (6cabeaf)
- feat: add WiFi profile recovery, Shizuku service integration, and associated tests (0f63045)
- feat: implement Wi-Fi scan policies, telemetry window management, unit tests, and code audit documentation (339a61f)
๐ Bug Fixes
- fix: validate Wi-Fi passwords against security policies and handle unknown SSIDs correctly (11744c5)
- fix: update MAC policy UI test icons and adjust MainScreen panel layout modifiers (f673213)
โก Improvements & Refactoring
- refactor: enhance wifi controller with robust network state management and profile recovery coordination (67141b6)
๐ฆ Installation & Verification
- Download
Quintz-v2.1.0.apkbelow. - Install it on Android 10 or later.
- Launch Shizuku and grant Quintz permission when prompted.
SHA-256 Checksum:
eb1f9c6a94eb13d672309a9c6defd43993745c4f9c91c4906f8842284fb805f0
(The matching .sha256 checksum file is also attached below)
Permissions
11 permissions requested
Sources
2 sources
Sources
2 sources