From b1c1f25dc6bb09a8c62577ebf18f3951932a728a Mon Sep 17 00:00:00 2001 From: Shivam Kuchhal Date: Mon, 9 Nov 2026 18:58:51 +0530 Subject: [PATCH 1/3] feat(firetv): add native launcher support, API 25 compatibility, and 60s boot fix - Backwards compatibility for Fire OS 6 (Android 7.1 / API 25): - Lower minSdk to 25 and enable Java 8+ coreLibraryDesugaring for java.time. - Guard PackageManager.getChangedPackages() behind Build.VERSION.SDK_INT >= 26. - Fix 60-second Fire OS boot animation stall: - Signal Settings.Secure 'bootanim.real_home_ready' = 1 in MainActivity to prevent WMS 60s fallback timeout when stock home is disabled. - Full Amazon Settings accessibility: - Add com.amazon.tv.settings.v2 to manifest queries and re-prioritize MainSettingsActivity in settings fallback array. - Validate candidate intent with resolveActivity() before returning in SystemSettings. - Documentation: - Add docs/devices/amazon-fire-tv-native-home.md with verified setup for Fire OS 6 (Mantis) and Fire OS 7 (Kara). --- docs/devices/amazon-fire-tv-native-home.md | 68 +++++++++++++++++++ launcher/app/build.gradle | 4 +- launcher/app/src/main/AndroidManifest.xml | 3 +- .../java/com/gathin/tvhome/MainActivity.java | 16 +++++ .../com/gathin/tvhome/SystemSettings.java | 4 +- launcher/app/src/main/res/values/config.xml | 3 +- 6 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 docs/devices/amazon-fire-tv-native-home.md diff --git a/docs/devices/amazon-fire-tv-native-home.md b/docs/devices/amazon-fire-tv-native-home.md new file mode 100644 index 0000000000..e9b29582e2 --- /dev/null +++ b/docs/devices/amazon-fire-tv-native-home.md @@ -0,0 +1,68 @@ +# Amazon Fire TV: Native Launcher Support & Zero-Latency Home Binding + +This note documents findings and configuration tested across two generations of Amazon Fire TV Sticks: +- **Target 1:** Fire TV Stick 4K Max 1st Gen (`AFTKA` / `kara`), Android 9 / API 28, Fire OS **7.7.1.3**. +- **Target 2:** Fire TV Stick 4K 1st Gen (`AFTMM` / `mantis`), Android 7.1.2 / API 25, Fire OS **6.7.1.1** (build `NS6711 / 0011644900484`). + +--- + +## 1. Native Home Key Binding without Accessibility Delay + +By default, alternative launchers on Fire OS rely on an accessibility service (`HomeKeyService`) or background pollers to detect the stock launcher and redirect focus. This introduces noticeable latency (500–1500 ms) and visible UI flicker when pressing the remote's Home button. + +With root access (e.g. via transient GhostLock execution): +- **Stock HomeActivity Disabling:** Rather than disabling the entire `com.amazon.tv.launcher` package, only the primary home activity component is disabled: + ```bash + pm disable com.amazon.tv.launcher/.ui.HomeActivity_vNext + ``` + *(Leaving `com.amazon.tv.launcher` enabled preserves the full settings menu, screensavers, and system overlays.)* +- **Default Home Intent Assignment:** + ```bash + cmd package set-home-activity --user 0 com.gathin.tvhome/.MainActivity + ``` +- **Result:** Physical Home key presses (`KEYCODE_HOME`) resolve directly to CleanYourTV with **0 ms latency** and zero screen flash. + +--- + +## 2. Boot Animation Watchdog Delay (60-second Fix) + +### Issue +When `HomeActivity_vNext` is disabled, Fire OS WindowManagerService (`FireTvWindowManagerServiceCallback$HomeInitialisationObserver`) never receives the signal indicating that the real home application has finished rendering. As a safety measure, Fire OS holds the boot animation ("firetv" loop) on screen for a **60-second fallback timeout**: +```text +FireTvWmsCallback: Stopping boot animation because timer elapsed waiting for real home to send signal. +``` +Even though the Android runtime and CleanYourTV boot in ~28 seconds, the UI is hidden behind the boot animation until ~88 seconds after power-on. + +### Solution +CleanYourTV now sets the secure setting upon launch in `MainActivity.onCreate()` and `onResume()`: +```java +Settings.Secure.putInt(getContentResolver(), "bootanim.real_home_ready", 1); +``` +Requires `android.permission.WRITE_SECURE_SETTINGS` (granted via ADB or root): +```bash +pm grant com.gathin.tvhome android.permission.WRITE_SECURE_SETTINGS +``` +Upon receiving this signal, Fire OS immediately logs: +```text +FireTvWmsCallback: Stopping boot animation because real home sent signal. +``` +This reduces boot time from **88.2s down to 30.8s** (a ~58s reduction). + +--- + +## 3. Full Settings Grid vs "About" Page + +On Fire OS: +- `com.amazon.tv.settings.v2/.tv.device.DeviceActivity` opens only the single-page "My Fire TV / About" subscreen. +- `com.amazon.tv.launcher/.ui.MainSettingsActivity` hosts the complete **14-category Settings Grid** (Network, Display & Audio, Applications, Remotes & Bluetooth, Preferences, Alexa, Equipment Control, etc.). + +By listing `com.amazon.tv.launcher/.ui.MainSettingsActivity` first in `settings_fallback_components` and keeping `MainSettingsActivity` enabled while disabling `HomeActivity_vNext`, the Settings pill in CleanYourTV launches the full system settings page. + +--- + +## 4. Backwards Compatibility for Fire OS 6 (Android 7.1 / API 25) + +1. **`minSdk 25` & Desugaring:** + Enabled `coreLibraryDesugaring` (`com.android.tools:desugar_jdk_libs:2.0.4`) so `java.time` (`LocalDate`) works seamlessly on Android 7.1 without runtime `NoClassDefFoundError`. +2. **API Level Guard:** + Guarded `PackageManager.getChangedPackages()` (introduced in API 26) with `Build.VERSION.SDK_INT >= 26` to avoid `NoSuchMethodError` on Android 7.1. diff --git a/launcher/app/build.gradle b/launcher/app/build.gradle index 6bec3ba865..35f2448464 100644 --- a/launcher/app/build.gradle +++ b/launcher/app/build.gradle @@ -11,7 +11,7 @@ android { // Xiaomi: docs/devices/xiaomi-mitv-aetp0-dofus.md (com.ts.launcher). // ColorOS TV: docs/devices/oppo-k9-55-oppocnm632.md (com.oneplus.tv.launcher2). applicationId providers.gradleProperty('launcherApplicationId').getOrElse('com.gathin.tvhome') - minSdk 26 + minSdk 25 targetSdk 34 versionCode 12 versionName '3.3' @@ -37,12 +37,14 @@ android { } compileOptions { + coreLibraryDesugaringEnabled true sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } dependencies { + coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4' implementation 'androidx.recyclerview:recyclerview:1.3.2' implementation 'androidx.dynamicanimation:dynamicanimation:1.0.0' // Test only (never in the APK): plain JVM tests for the module card validators, src/test. diff --git a/launcher/app/src/main/AndroidManifest.xml b/launcher/app/src/main/AndroidManifest.xml index ca18afa966..e337d1fec3 100644 --- a/launcher/app/src/main/AndroidManifest.xml +++ b/launcher/app/src/main/AndroidManifest.xml @@ -65,6 +65,7 @@ + @@ -90,7 +91,7 @@ - + diff --git a/launcher/app/src/main/java/com/gathin/tvhome/MainActivity.java b/launcher/app/src/main/java/com/gathin/tvhome/MainActivity.java index 12fc3090ab..fadf144e48 100644 --- a/launcher/app/src/main/java/com/gathin/tvhome/MainActivity.java +++ b/launcher/app/src/main/java/com/gathin/tvhome/MainActivity.java @@ -451,6 +451,7 @@ public void run() { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); + dismissFireTvBootAnimation(); setContentView(R.layout.activity_main); density = getResources().getDisplayMetrics().density; // config.xml, overlaid by config.json from a pushed theme (see Config and tools/theme.sh). @@ -1077,6 +1078,7 @@ protected void onStart() { @Override protected void onResume() { super.onResume(); + dismissFireTvBootAnimation(); resumed = true; // A festival that started or ended while Home was in the background: rebuild with or without it. if (festive != festival.active(LocalDate.now())) { @@ -1143,6 +1145,18 @@ private long settingsRevision() { return getSharedPreferences(Config.SETTINGS_NAME, MODE_PRIVATE).getLong(Config.SETTINGS_REVISION_KEY, 0); } + /** + * Signals Fire OS that the active home launcher is ready. + * When Amazon's stock launcher is disabled, Fire OS WMS waits up to a 60-second fallback timer + * before dismissing the boot animation unless Settings.Secure "bootanim.real_home_ready" is set to 1. + */ + private void dismissFireTvBootAnimation() { + try { + android.provider.Settings.Secure.putInt(getContentResolver(), "bootanim.real_home_ready", 1); + } catch (Throwable ignored) { + } + } + /** * Only "Reorder tiles" in Launcher settings still answers with a result: Home rebuilds (the saved choices are * reloaded) and then enters reorder mode. Every other change is picked up in onResume through the change count. @@ -1226,11 +1240,13 @@ private void reloadApps(boolean animate, boolean rebuild, boolean entrance) { /** True when PackageManager reports apps changed since the last rebuild (one binder call). */ private boolean packagesChangedSinceRebuild() { + if (android.os.Build.VERSION.SDK_INT < 26) return false; ChangedPackages changed = getPackageManager().getChangedPackages(packageSequence); return changed != null && !changed.getPackageNames().isEmpty(); } private int currentPackageSequence(int since) { + if (android.os.Build.VERSION.SDK_INT < 26) return since; ChangedPackages changed = getPackageManager().getChangedPackages(since); return changed != null ? changed.getSequenceNumber() : since; } diff --git a/launcher/app/src/main/java/com/gathin/tvhome/SystemSettings.java b/launcher/app/src/main/java/com/gathin/tvhome/SystemSettings.java index 3b9e1d0136..ed2c5a0c96 100644 --- a/launcher/app/src/main/java/com/gathin/tvhome/SystemSettings.java +++ b/launcher/app/src/main/java/com/gathin/tvhome/SystemSettings.java @@ -47,13 +47,13 @@ static Intent vendorIntent(Context context) { for (String value : context.getResources().getStringArray(R.array.settings_fallback_components)) { ComponentName component = ComponentName.unflattenFromString(value); if (component == null) continue; - // Explicit resolveActivity() always succeeds, so check the package exists instead. try { pm.getPackageInfo(component.getPackageName(), 0); } catch (PackageManager.NameNotFoundException e) { continue; } - return new Intent().setComponent(component); + Intent intent = new Intent().setComponent(component); + if (intent.resolveActivity(pm) != null) return intent; } return null; } diff --git a/launcher/app/src/main/res/values/config.xml b/launcher/app/src/main/res/values/config.xml index 2255d16f05..c0f658f642 100644 --- a/launcher/app/src/main/res/values/config.xml +++ b/launcher/app/src/main/res/values/config.xml @@ -10,9 +10,10 @@ + com.amazon.tv.launcher/com.amazon.tv.launcher.ui.MainSettingsActivity + com.amazon.tv.settings.v2/com.amazon.tv.settings.v2.tv.device.DeviceActivity com.xiaomi.mitv.settings/com.xiaomi.mitv.settings.entry.MainActivity com.tcl.settings/com.tcl.settings.ui.MainActivity - com.amazon.tv.launcher/com.amazon.tv.launcher.ui.MainSettingsActivity From 2b81ec35d6d8db40678ce4d2e19b87b67f7e6c74 Mon Sep 17 00:00:00 2001 From: Shivam Kuchhal Date: Mon, 9 Nov 2026 19:09:24 +0530 Subject: [PATCH 2/3] docs(firetv): detail wireless root workflows for Fire OS 6 and Fire OS 7 - Add comprehensive guide for replacing stock Fire TV launcher with 0 ms latency. - Detail 100% wireless root workflow for Fire OS 7 (AFTKA / kara / 4K Max 1st Gen). - Detail 100% wireless root workflow for Fire OS 6 (AFTMM / mantis / 4K 1st Gen). - Document NDK API 24 compilation requirements and aligned_alloc libc fix for Mantis. - Document safe component disabling (HomeActivity_vNext) to preserve full 14-grid Amazon Settings. - Detail the 60-second boot animation stall mechanism and verify 57s speedup. --- docs/devices/amazon-fire-tv-native-home.md | 223 +++++++++++++++++---- 1 file changed, 186 insertions(+), 37 deletions(-) diff --git a/docs/devices/amazon-fire-tv-native-home.md b/docs/devices/amazon-fire-tv-native-home.md index e9b29582e2..5a42a07dab 100644 --- a/docs/devices/amazon-fire-tv-native-home.md +++ b/docs/devices/amazon-fire-tv-native-home.md @@ -1,68 +1,217 @@ # Amazon Fire TV: Native Launcher Support & Zero-Latency Home Binding -This note documents findings and configuration tested across two generations of Amazon Fire TV Sticks: -- **Target 1:** Fire TV Stick 4K Max 1st Gen (`AFTKA` / `kara`), Android 9 / API 28, Fire OS **7.7.1.3**. -- **Target 2:** Fire TV Stick 4K 1st Gen (`AFTMM` / `mantis`), Android 7.1.2 / API 25, Fire OS **6.7.1.1** (build `NS6711 / 0011644900484`). +This guide details how to replace the stock Amazon Fire TV launcher with CleanYourTV as the native default home screen with **0 ms hardware Home button latency**, verified across two different Fire TV generations: + +| Property | Target 1: Fire TV Stick 4K Max 1st Gen | Target 2: Fire TV Stick 4K 1st Gen | +| :--- | :--- | :--- | +| **Model ID** | `AFTKA` (board: `kara`) | `AFTMM` (board: `mantis`) | +| **SoC / Kernel** | MediaTek MT8696 (Linux 4.19 / arm64) | MediaTek MT8695 (Linux 4.4.120+ / armv7l) | +| **OS Version** | Fire OS **7.7.1.3** (Android 9 / API 28) | Fire OS **6.7.1.1** (Android 7.1.2 / API 25) | +| **Root Engine** | GhostLock Fire OS 7 (Sheldon/Kara profile) | GhostLock Mantis port (API 24, MT8695 profile) | +| **Execution** | **100% Wireless ADB** (`:5555`) | **100% Wireless ADB** (`:5555`) | + +--- + +## 1. Why Native Binding vs Accessibility Overlay + +Standard launcher managers on Fire OS rely on Android Accessibility (`HomeKeyService`) or background polling to detect when Amazon's launcher comes into the foreground and immediately start the custom launcher. + +While functional, this approach has inherent flaws: +- **Latency:** 500–1500 ms delay before focus switches. +- **UI Flicker:** Stock Amazon home renders briefly before CleanYourTV appears. +- **Service Killing:** Fire OS aggressive memory management frequently stops accessibility services during heavy video playback. + +By gaining temporary in-memory root access via GhostLock, we can disable only the stock Home activity component while keeping the rest of Fire OS intact: +```bash +pm disable com.amazon.tv.launcher/.ui.HomeActivity_vNext +cmd package set-home-activity --user 0 com.gathin.tvhome/.MainActivity +``` +Because the stock launcher package (`com.amazon.tv.launcher`) remains enabled, Amazon's Alexa overlays, screensavers, and the complete 14-grid System Settings remain fully functional. --- -## 1. Native Home Key Binding without Accessibility Delay +## 2. Wireless Setup: Fire OS 7 (`kara` / `sheldon` / 4K Max 1st Gen) + +### Requirements +- Fire OS 7.x (e.g. 7.7.1.3). +- GhostLock Fire OS 7 binary (compiled for API 28 arm64/arm). + +### Wireless Steps +1. Connect over Wi-Fi ADB: + ```bash + adb connect :5555 + adb -s :5555 wait-for-device + ``` + +2. Push CleanYourTV and the root payload: + ```bash + adb -s :5555 install -r launcher/cleanyourtv-release.apk + adb -s :5555 shell "mkdir -p /data/local/tmp/gl" + adb -s :5555 push ghostlock_root /data/local/tmp/gl/ghostlock_root + adb -s :5555 shell "chmod 755 /data/local/tmp/gl/ghostlock_root" + ``` + +3. Launch the GhostLock root daemon wirelessly: + ```bash + adb -s :5555 shell "nohup /data/local/tmp/gl/ghostlock_root > /data/local/tmp/gl/daemon.log 2>&1 &" + ``` + +4. Execute root actions through the transient `su` socket: + ```bash + adb -s :5555 shell "/data/local/tmp/gl/su -c ' + pm grant com.gathin.tvhome android.permission.WRITE_SECURE_SETTINGS + cmd package compile -m speed -f com.gathin.tvhome + pm disable com.amazon.tv.launcher/.ui.HomeActivity_vNext + cmd package set-home-activity --user 0 com.gathin.tvhome/.MainActivity + pm hide --user 0 com.amazon.firehomestarter + pm hide --user 0 com.amazon.tv.forcedotaupdater.v2 + pm hide --user 0 com.amazon.device.software.ota + '" + ``` + +5. Reboot wirelessly: + ```bash + adb -s :5555 reboot + ``` + +--- -By default, alternative launchers on Fire OS rely on an accessibility service (`HomeKeyService`) or background pollers to detect the stock launcher and redirect focus. This introduces noticeable latency (500–1500 ms) and visible UI flicker when pressing the remote's Home button. +## 3. Wireless Setup: Fire OS 6 (`mantis` / 4K 1st Gen) -With root access (e.g. via transient GhostLock execution): -- **Stock HomeActivity Disabling:** Rather than disabling the entire `com.amazon.tv.launcher` package, only the primary home activity component is disabled: - ```bash - pm disable com.amazon.tv.launcher/.ui.HomeActivity_vNext - ``` - *(Leaving `com.amazon.tv.launcher` enabled preserves the full settings menu, screensavers, and system overlays.)* -- **Default Home Intent Assignment:** - ```bash - cmd package set-home-activity --user 0 com.gathin.tvhome/.MainActivity - ``` -- **Result:** Physical Home key presses (`KEYCODE_HOME`) resolve directly to CleanYourTV with **0 ms latency** and zero screen flash. +Fire OS 6 uses Android 7.1.2 (API 25) with a 32-bit `armv7l` kernel (4.4.120+). Pre-built Fire OS 7 GhostLock binaries will fail on Fire OS 6 with: +```text +CANNOT LINK EXECUTABLE: cannot locate symbol "aligned_alloc" +``` +because `aligned_alloc` was only introduced in Android API 28 libc. + +### Compilation for Mantis (API 24) +To build a compatible root binary for Mantis: +1. Apply the Mantis memory corruption patch from `Delitants/firetv-mantis-standalone` to GhostLock branch `4.4`. +2. Compile using Android NDK targeting API 24 (`armv7a-linux-androideabi24-clang`) to ensure all symbols link against Android 7.x libc: + ```bash + $NDK/toolchains/llvm/prebuilt/*/bin/armv7a-linux-androideabi24-clang \ + -fPIE -pie -Wall -O2 src/*.c -o ghostlock_root + ``` +3. Use the matching device kernel profile (e.g. `mantis-NS6711-5908.conf`). + +### Wireless Steps +1. Connect over Wi-Fi ADB: + ```bash + adb connect :5555 + adb -s :5555 wait-for-device + ``` + +2. Install CleanYourTV: + ```bash + adb -s :5555 install -r launcher/cleanyourtv-release.apk + ``` + +3. Stage the exploit binary, kernel profile, and an action script: + ```bash + adb -s :5555 shell "mkdir -p /data/local/tmp/gl_deploy" + adb -s :5555 push ghostlock_root /data/local/tmp/gl_deploy/ghostlock_root + adb -s :5555 push mantis-NS6711-5908.conf /data/local/tmp/gl_deploy/profile.conf + ``` + +4. Create the execution script `/data/local/tmp/gl_deploy/action.sh`: + ```bash + adb -s :5555 shell "cat << 'EOF' > /data/local/tmp/gl_deploy/action.sh + #!/system/bin/sh + pm grant com.gathin.tvhome android.permission.WRITE_SECURE_SETTINGS + cmd package compile -m speed -f com.gathin.tvhome + pm disable com.amazon.tv.launcher/.ui.HomeActivity_vNext + cmd package set-home-activity --user 0 com.gathin.tvhome/.MainActivity + pm hide --user 0 com.amazon.firehomestarter + pm hide --user 0 com.amazon.tv.forcedotaupdater.v2 + pm hide --user 0 com.amazon.device.software.ota + pm hide --user 0 com.amazon.device.software.ota.override + reboot + EOF + chmod 755 /data/local/tmp/gl_deploy/ghostlock_root /data/local/tmp/gl_deploy/action.sh + " + ``` + +5. Trigger in-memory root execution wirelessly: + ```bash + adb -s :5555 shell "nohup /data/local/tmp/gl_deploy/ghostlock_root --profile /data/local/tmp/gl_deploy/profile.conf --exec /data/local/tmp/gl_deploy/action.sh > /data/local/tmp/gl_deploy/exec.log 2>&1 &" + ``` + GhostLock obtains kernel RW, zeroes the task UID to `root (0)`, runs `action.sh`, applies the changes, and initiates a clean reboot. --- -## 2. Boot Animation Watchdog Delay (60-second Fix) +## 4. Boot Animation Watchdog Delay (60-second Fix) + +### The Issue +By analyzing `/system/framework/oat/arm/fosservices.odex`, we identified that Fire OS's WindowManagerService (`FireTvWindowManagerServiceCallback$HomeInitialisationObserver`) listens for a signal on the secure setting: +```text +bootanim.real_home_ready +``` +When Amazon's stock home screen finishes rendering, it sets this key to `1`, signaling `surfaceflinger` to exit the boot animation. -### Issue -When `HomeActivity_vNext` is disabled, Fire OS WindowManagerService (`FireTvWindowManagerServiceCallback$HomeInitialisationObserver`) never receives the signal indicating that the real home application has finished rendering. As a safety measure, Fire OS holds the boot animation ("firetv" loop) on screen for a **60-second fallback timeout**: +When `HomeActivity_vNext` is disabled, this signal is never received. Fire OS starts an internal **60-second safety fallback timer** (`BOOT_ANIMATION_TIMEOUT = 60000`): ```text FireTvWmsCallback: Stopping boot animation because timer elapsed waiting for real home to send signal. ``` -Even though the Android runtime and CleanYourTV boot in ~28 seconds, the UI is hidden behind the boot animation until ~88 seconds after power-on. +Even though the system finishes booting in ~28 seconds, the TV screen stays trapped on the looping "firetv" logo for 88+ seconds. -### Solution -CleanYourTV now sets the secure setting upon launch in `MainActivity.onCreate()` and `onResume()`: +### The Fix in CleanYourTV +CleanYourTV now sets `bootanim.real_home_ready = 1` immediately inside `MainActivity.onCreate()` and `onResume()`: ```java -Settings.Secure.putInt(getContentResolver(), "bootanim.real_home_ready", 1); +private void dismissFireTvBootAnimation() { + try { + android.provider.Settings.Secure.putInt(getContentResolver(), "bootanim.real_home_ready", 1); + } catch (Throwable ignored) {} +} ``` -Requires `android.permission.WRITE_SECURE_SETTINGS` (granted via ADB or root): -```bash -pm grant com.gathin.tvhome android.permission.WRITE_SECURE_SETTINGS -``` -Upon receiving this signal, Fire OS immediately logs: +Requires `android.permission.WRITE_SECURE_SETTINGS` (granted in step 4 above). + +### Result +Upon launching CleanYourTV, Fire OS immediately records: ```text FireTvWmsCallback: Stopping boot animation because real home sent signal. ``` -This reduces boot time from **88.2s down to 30.8s** (a ~58s reduction). +- **Before fix:** `wm_boot_animation_done: 88239 ms` (~88.2 seconds) +- **After fix:** `wm_boot_animation_done: 30828 ms` (**~30.8 seconds**) +- **Improvement:** Boot animation dismissed **57.4 seconds faster** (~65% reduction). --- -## 3. Full Settings Grid vs "About" Page +## 5. Full Amazon Settings vs "About" Screen On Fire OS: - `com.amazon.tv.settings.v2/.tv.device.DeviceActivity` opens only the single-page "My Fire TV / About" subscreen. -- `com.amazon.tv.launcher/.ui.MainSettingsActivity` hosts the complete **14-category Settings Grid** (Network, Display & Audio, Applications, Remotes & Bluetooth, Preferences, Alexa, Equipment Control, etc.). +- `com.amazon.tv.launcher/.ui.MainSettingsActivity` hosts the complete **14-category Settings Grid** (Network, Display & Audio, Applications, Remotes & Bluetooth, Preferences, Equipment Control, Alexa, Notifications, etc.). -By listing `com.amazon.tv.launcher/.ui.MainSettingsActivity` first in `settings_fallback_components` and keeping `MainSettingsActivity` enabled while disabling `HomeActivity_vNext`, the Settings pill in CleanYourTV launches the full system settings page. +By disabling only `com.amazon.tv.launcher/.ui.HomeActivity_vNext` (instead of the whole launcher package), `MainSettingsActivity` remains fully intact and functional. CleanYourTV prioritizes `com.amazon.tv.launcher/.ui.MainSettingsActivity` in `config.xml` (`settings_fallback_components`), ensuring the Settings pill opens the complete settings menu. --- -## 4. Backwards Compatibility for Fire OS 6 (Android 7.1 / API 25) +## 6. Verification and Rollback + +### Verification +Check default Home resolver over Wi-Fi ADB: +```bash +adb -s :5555 shell "cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME" +``` +Expected output: +```text +priority=0 preferredOrder=0 match=0x108000 specificIndex=-1 isDefault=true +com.gathin.tvhome/.MainActivity +``` -1. **`minSdk 25` & Desugaring:** - Enabled `coreLibraryDesugaring` (`com.android.tools:desugar_jdk_libs:2.0.4`) so `java.time` (`LocalDate`) works seamlessly on Android 7.1 without runtime `NoClassDefFoundError`. -2. **API Level Guard:** - Guarded `PackageManager.getChangedPackages()` (introduced in API 26) with `Build.VERSION.SDK_INT >= 26` to avoid `NoSuchMethodError` on Android 7.1. +Simulate physical Home button press: +```bash +adb -s :5555 shell "input keyevent 3" +``` +Focused window should immediately return: +```text +mCurrentFocus=Window{... u0 com.gathin.tvhome/com.gathin.tvhome.MainActivity} +``` + +### Rollback to Stock +To restore the stock Amazon launcher at any time: +```bash +adb -s :5555 shell "pm enable com.amazon.tv.launcher/.ui.HomeActivity_vNext" +adb -s :5555 shell "pm unhide --user 0 com.amazon.firehomestarter" +adb -s :5555 shell "reboot" +``` From 9dc2a840af01b6d9572e06a3176b6a6424a2e215 Mon Sep 17 00:00:00 2001 From: Shivam Kuchhal Date: Mon, 9 Nov 2026 19:14:06 +0530 Subject: [PATCH 3/3] docs(firetv): document external companion repos and toolchain prerequisites --- docs/devices/amazon-fire-tv-native-home.md | 23 +++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/devices/amazon-fire-tv-native-home.md b/docs/devices/amazon-fire-tv-native-home.md index 5a42a07dab..d647f555e2 100644 --- a/docs/devices/amazon-fire-tv-native-home.md +++ b/docs/devices/amazon-fire-tv-native-home.md @@ -30,7 +30,20 @@ Because the stock launcher package (`com.amazon.tv.launcher`) remains enabled, A --- -## 2. Wireless Setup: Fire OS 7 (`kara` / `sheldon` / 4K Max 1st Gen) +## 2. External Prerequisites & Companion Repositories + +CleanYourTV is strictly an application launcher and does not bundle or distribute root exploit binaries within its repository. Because transient in-memory root requires device-specific and kernel-version-specific memory offsets, users obtain the matching binaries and profiles from dedicated open-source companion projects: + +- **For Fire OS 7 (`kara` / `sheldon` / Fire TV Stick 4K Max 1st Gen):** + Use the [firetv-clean-root](https://github.com/saisarathbb/firetv-clean-root) companion toolchain. It provides the pre-built `ghostlock_root` binary compiled for Android 9 / API 28 along with Sheldon/Kara configuration profiles. +- **For Fire OS 6 (`mantis` / Fire TV Stick 4K 1st Gen):** + Use the [firetv-mantis-standalone](https://github.com/Delitants/firetv-mantis-standalone) toolchain. It provides the MediaTek MT8695 memory profile (`mantis-NS6711-5908.conf`) and patch files to compile GhostLock targeting Android 7.1 / API 24 libc. +- **Upstream Exploit Engine:** + The underlying in-memory privilege escalation mechanism is maintained at [GhostLock](https://github.com/R0rt1z2/GhostLock). + +--- + +## 3. Wireless Setup: Fire OS 7 (`kara` / `sheldon` / 4K Max 1st Gen) ### Requirements - Fire OS 7.x (e.g. 7.7.1.3). @@ -76,7 +89,7 @@ Because the stock launcher package (`com.amazon.tv.launcher`) remains enabled, A --- -## 3. Wireless Setup: Fire OS 6 (`mantis` / 4K 1st Gen) +## 4. Wireless Setup: Fire OS 6 (`mantis` / 4K 1st Gen) Fire OS 6 uses Android 7.1.2 (API 25) with a 32-bit `armv7l` kernel (4.4.120+). Pre-built Fire OS 7 GhostLock binaries will fail on Fire OS 6 with: ```text @@ -139,7 +152,7 @@ To build a compatible root binary for Mantis: --- -## 4. Boot Animation Watchdog Delay (60-second Fix) +## 5. Boot Animation Watchdog Delay (60-second Fix) ### The Issue By analyzing `/system/framework/oat/arm/fosservices.odex`, we identified that Fire OS's WindowManagerService (`FireTvWindowManagerServiceCallback$HomeInitialisationObserver`) listens for a signal on the secure setting: @@ -176,7 +189,7 @@ FireTvWmsCallback: Stopping boot animation because real home sent signal. --- -## 5. Full Amazon Settings vs "About" Screen +## 6. Full Amazon Settings vs "About" Screen On Fire OS: - `com.amazon.tv.settings.v2/.tv.device.DeviceActivity` opens only the single-page "My Fire TV / About" subscreen. @@ -186,7 +199,7 @@ By disabling only `com.amazon.tv.launcher/.ui.HomeActivity_vNext` (instead of th --- -## 6. Verification and Rollback +## 7. Verification and Rollback ### Verification Check default Home resolver over Wi-Fi ADB: