Explaing the basic/advanced modes in the README.md

README.md

@@ -8,21 +8,62 @@
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=pcolby_nfc-quick-settings&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=pcolby_nfc-quick-settings)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=pcolby_nfc-quick-settings&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=pcolby_nfc-quick-settings)
 
-NFC Quick Settings is a really basic Android app with no GUI of it's own, that simply adds an NFC
-tile to the tiles available to the [Quick Settings panel][].
+NFC Quick Settings is a really basic Android app with no GUI of it's own, that simply adds an NFC tile to the tiles
+available to the [Quick Settings panel][].
 
 [![Get it on Google Play](assets/GetItOnGooglePlay_Badge_Web_color_English.png)](https://play.google.com/store/apps/details?id=au.id.colby.nfcquicksettings)
 
-## Internal Details
+The Quick Settings tile indicates the current NFC status (enabled, or disabled), but the action it takes when tapped
+varies a little depending on the permissions available.
 
-Just for the curious, the application implements a basic [TileService][], that overrides:
+## Basic Mode
 
-* [onStartListening()][] to check the default NFC adapter's current status, and update the tile state
-  accordingly; and
-* [onClick()][] to show the device's NFC Settings by starting the [NFC Settings][] activity.
+In the _basic_ mode, which requires no special permissions, tapping the tile will simply open the device's NFS Settings
+page (assuming the device has one). This actually the best that can be done using official Android APIs and permissions.
 
-[NFC Settings]: https://developer.android.com/reference/android/provider/Settings#ACTION_NFC_SETTINGS
-[onClick()]: https://developer.android.com/reference/android/service/quicksettings/TileService#onClick()
-[onStartListening()]: https://developer.android.com/reference/android/service/quicksettings/TileService#onStartListening()
-[Quick Settings panel]: https://support.google.com/android/answer/9083864
-[TileService]: https://developer.android.com/reference/android/service/quicksettings/TileService
+## Advancde Mode
+
+The advanced mode requires special permissions (see below), but once enabled, tapping the Quick Settings tile will turn
+the NFC service on or off directly, without having to open the NFC settings page at all. Unfortunately, to acheive this
+_advanced_ mode, NFC Quick Settings needs to use APIs not intended for third-pary applications (specifically
+[`NfcAdapter::enable()`][] and [`NfcAdapter::disable()`][]). And to use those methods, the tile needs the
+[`WRITE_SECURE_SETTINGS`][] permission.
+
+### Granting `WRITE_SECURE_SETTINGS`
+
+As the [`WRITE_SECURE_SETTINGS`][] permission is not intended to be used by third-party applications, it needs to be
+granted to application via the [Android Debug Bridge (adb)][] tool.
+
+1. Install [Android Debug Bridge (adb)][]:
+
+   > `adb` is included in the Android SDK Platform Tools package. Download this package with the [SDK Manager][], which
+   > installs it at `android_sdk/platform-tools/`. If you want the standalone Android SDK Platform Tools package,
+   > [download it here](https://developer.android.com/tools/releases/platform-tools).
+
+2. Install NFC Quick Settings, via [Google Play] or [GitHub Releases].
+
+3. [Enable adb debugging on your device](https://developer.android.com/tools/adb#Enabling).
+
+4. [Connect to your device via Wi-Fi](https://developer.android.com/tools/adb#connect-to-a-device-over-wi-fi).
+
+5. Grant the [`WRITE_SECURE_SETTINGS`][] permission to NFC Quick Settings:
+
+   ```sh
+   adb shell pm grant au.id.colby.nfcquicksettings android.permission.WRITE_SECURE_SETTINGS
+   ```
+
+If for some reason you want revoke the [`WRITE_SECURE_SETTINGS`][] permission, and restore the _basic_ mode, then
+follow the same steps, but replace `grant` with `revoke`:
+
+```sh
+adb shell pm revoke au.id.colby.nfcquicksettings android.permission.WRITE_SECURE_SETTINGS
+```
+
+[`NfcAdapter::disable()`]: https://cs.android.com/android/platform/superproject/+/main:frameworks/base/core/java/android/nfc/NfcAdapter.java;l=986?q=NfcAdapter "android.nfc.NfcAdapter::disable()"
+[`NfcAdapter::enable()`]: https://cs.android.com/android/platform/superproject/+/main:frameworks/base/core/java/android/nfc/NfcAdapter.java;l=947?q=NfcAdapter "android.nfc.NfcAdapter::enable()"
+[`WRITE_SECURE_SETTINGS`]: https://developer.android.com/reference/android/Manifest.permission#WRITE_SECURE_SETTINGS "android.permission.WRITE_SECURE_SETTINGS"
+[Android Debug Bridge (adb)]: https://developer.android.com/tools/adb "Android Debug Bridge (adb)"
+[GitHub Releases]: https://github.com/pcolby/nfc-quick-settings/releases "NFC Quick Settings releases"
+[Google Play]: https://play.google.com/store/apps/details?id=au.id.colby.nfcquicksettings "NFC Quick Settings on Google Play"
+[SDK Manager]: https://developer.android.com/studio/intro/update#sdk-manager "Update your tools with the SDK Manager"
+[Quick Settings panel]: https://support.google.com/android/answer/9083864 "Change settings quickly on your Android phone"