Skip to content

Debloat any Android or Google TV over Wi-Fi and get an Apple TV-style home.

Launcher: declare MODERN_HOME for ColorOS TV

Cursor Agent3fa7546a698b
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 22fb43d47..997e6508d 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -523,6 +523,18 @@ Things that bit us or contributors, so they don't bite you. Commands use `tools/
android.intent.category.HOME` lists only PatchWall and `FallbackHome`. Keep the stock launcher
enabled - disabling it leaves only `FallbackHome` - and see the
[device notes](devices/xiaomi-nemo-laser-cinema2.md) for the queries and the firmware code.
+- **ColorOS TV refuses a HOME install, or boots only a launcher that declares its own category**,
+ verified on an OPPO K9 55 (`OPPOCNM632`), Android 9. The default `com.gathin.tvhome` build is not
+ accepted as Home. The working build is
+ `-PlauncherApplicationId=com.oneplus.tv.launcher2`, and `MainActivity`'s HOME filter also declares
+ `com.heytap.tv.launcher.category.MODERN_HOME` (without that category, ColorOS boot waits on the
+ brand animation). Leave `com.heytap.tv.launcher` installed and enabled: it is the stock home, and
+ building over that package name replaces it. `launcher/build-and-install.sh` installs
+ `com.gathin.tvhome` and would disable a stock launcher it was told to, so do not name
+ `com.heytap.tv.launcher` as `STOCK_LAUNCHER`. The other allowlisted ids are
+ `com.heytap.tv.launcher` (stock, do not overwrite) and `com.oppo.tv.launcher2`. The list is at
+ [`examples/oppo-k9-55-oppocnm632/`](../examples/oppo-k9-55-oppocnm632/) and the full note is
+ `docs/devices/oppo-k9-55-oppocnm632.md`.
- **The new launcher still doesn't own Home** after the stock one is disabled, seen on Google TV
(Xiaomi MiTV-MOOR2). Another system app answers HOME: `com.google.android.tungsten.setupwraith`,
with `.MainActivity` at intent-filter priority 4 and `.RecoveryActivity` at priority 1. You
diff --git a/docs/devices/oppo-k9-55-oppocnm632.md b/docs/devices/oppo-k9-55-oppocnm632.md
index e3c25aa28..6e254f894 100644
--- a/docs/devices/oppo-k9-55-oppocnm632.md
+++ b/docs/devices/oppo-k9-55-oppocnm632.md
@@ -9,8 +9,8 @@ and
The allowlist was first written up for a K9 65 (`OPPOCNM652`, ColorOS TV 2.4) in
[aerial-tv's device note](https://github.com/pengchujin/aerial-tv/blob/master/docs/devices/oppo-coloros-tv.md).
-The checks below are this 55" set. How to build a launcher that ColorOS will boot is in the
-launcher follow-up and in `docs/TROUBLESHOOTING.md` once that change lands.
+The checks below are this 55" set. How to build a launcher that ColorOS will boot, and what not to
+name as `STOCK_LAUNCHER`, is in the ColorOS bullet in `docs/TROUBLESHOOTING.md`.
## The three allowlisted package ids
diff --git a/launcher/app/build.gradle b/launcher/app/build.gradle
index 023aecdeb..4bceca4f3 100644
--- a/launcher/app/build.gradle
+++ b/launcher/app/build.gradle
@@ -7,7 +7,9 @@ android {
compileSdk 34
defaultConfig {
- // Opt-in identity for firmware with a package-name HOME allowlist; see docs/devices/xiaomi-mitv-aetp0-dofus.md.
+ // Opt-in identity for firmware with a package-name HOME allowlist.
+ // 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
targetSdk 34
diff --git a/launcher/app/src/main/AndroidManifest.xml b/launcher/app/src/main/AndroidManifest.xml
index b336792d3..05b18c676 100644
--- a/launcher/app/src/main/AndroidManifest.xml
+++ b/launcher/app/src/main/AndroidManifest.xml
@@ -95,6 +95,9 @@
<category android:name="android.intent.category.HOME" />
<category android:name="android.intent.category.COMMON_HOME" />
<category android:name="android.intent.category.DEFAULT" />
+ <!-- ColorOS TV: boot only promotes a HOME that declares this category.
+ docs/devices/oppo-k9-55-oppocnm632.md (prior art: aerial-tv oppo-coloros-tv.md). -->
+ <category android:name="com.heytap.tv.launcher.category.MODERN_HOME" />
</intent-filter>
<!-- Listed in the TV's own app list, so it can be opened from the stock home screen too. -->
<intent-filter>
diff --git a/launcher/build-and-install.ps1 b/launcher/build-and-install.ps1
index 63a5238f6..d581e7a6f 100644
--- a/launcher/build-and-install.ps1
+++ b/launcher/build-and-install.ps1
@@ -44,6 +44,9 @@ if ($env:SKIP_BUILD -ne '1') {
$py = '..\tools\venv\Scripts\python.exe'
# Which app owns Home differs by build; ask the TV, but only accept a launcher we recognise (the answer
# can also be Android's chooser "android", the setup wizard, or another third-party launcher).
+# ColorOS TV's com.heytap.tv.launcher stays out of the list below: recognising it would disable
+# the stock home, and the default applicationId is refused as Home on that firmware.
+# docs/devices/oppo-k9-55-oppocnm632.md.
$knownStock = @('com.google.android.tvlauncher', 'com.google.android.apps.tv.launcherx', 'com.google.android.leanbacklauncher', 'com.mitv.tvhome')
if (-not $StockLauncher) {
$homePkg = & $py -I ..\tools\tv.py 'cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME' | Select-Object -Last 1
diff --git a/launcher/build-and-install.sh b/launcher/build-and-install.sh
index da47f0a53..c0c4b5ea9 100755
--- a/launcher/build-and-install.sh
+++ b/launcher/build-and-install.sh
@@ -65,6 +65,9 @@ fi
# Only a launcher we recognise is accepted: the answer can also be Android's chooser ("android"),
# the setup wizard, or another third-party launcher, none of which should be disabled by accident.
# Pass STOCK_LAUNCHER=<package> to name it yourself, or STOCK_LAUNCHER=none to disable nothing.
+# ColorOS TV's com.heytap.tv.launcher stays out of the list below: recognising it would disable
+# the stock home, and the default applicationId is refused as Home on that firmware.
+# docs/devices/oppo-k9-55-oppocnm632.md.
KNOWN_STOCK_LAUNCHERS="com.google.android.tvlauncher com.google.android.apps.tv.launcherx com.google.android.leanbacklauncher com.mitv.tvhome"
if [ -z "${STOCK_LAUNCHER:-}" ]; then
HOME_PKG=$("$PY" -I ../tools/tv.py 'cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME' \
diff --git a/tests/test_oppo_k9_coloros.py b/tests/test_oppo_k9_coloros.py
index f1a733a8f..374952242 100644
--- a/tests/test_oppo_k9_coloros.py
+++ b/tests/test_oppo_k9_coloros.py
@@ -1,13 +1,15 @@
-"""OPPO K9 55 (OPPOCNM632) list and device note.
+"""OPPO K9 55 (OPPOCNM632) ColorOS list and launcher.
-ColorOS accepts a HOME install only for three package names. This list leaves the stock home
-`com.heytap.tv.launcher` enabled. The device note names that allowlist and warns not to run
-`launcher/build-and-install.sh`. Launcher manifest and troubleshooting checks live with the
-launcher change.
+The examples half names the three allowlisted package ids, leaves the stock home enabled, and
+links the device note from tv.json and examples/README.md. The launcher half declares
+com.heytap.tv.launcher.category.MODERN_HOME on the HOME filter, keeps com.heytap.tv.launcher out
+of the install scripts' stock-launcher lists, and names that category and the device-note path
+in docs/TROUBLESHOOTING.md.
Run from the repository root: python3 -m unittest tests.test_oppo_k9_coloros -v
"""
import json
+import re
import unittest
from pathlib import Path
@@ -18,10 +20,19 @@ LIST = ROOT / "examples" / "oppo-k9-55-oppocnm632" / "debloat.txt"
EXTRA = ROOT / "examples" / "oppo-k9-55-oppocnm632" / "debloat-extra.txt"
TV_JSON = ROOT / "examples" / "oppo-k9-55-oppocnm632" / "tv.json"
INDEX = ROOT / "examples" / "README.md"
+MANIFEST = ROOT / "launcher" / "app" / "src" / "main" / "AndroidManifest.xml"
+INSTALL_SH = ROOT / "launcher" / "build-and-install.sh"
+INSTALL_PS1 = ROOT / "launcher" / "build-and-install.ps1"
+TROUBLESHOOTING = ROOT / "docs" / "TROUBLESHOOTING.md"
+MODERN_HOME = "com.heytap.tv.launcher.category.MODERN_HOME"
+HOME = "android.intent.category.HOME"
STOCK = "com.heytap.tv.launcher"
ALLOWLIST = (STOCK, "com.oneplus.tv.launcher2", "com.oppo.tv.launcher2")
NOTE_LINK = "../docs/devices/oppo-k9-55-oppocnm632.md"
+NOTE_PATH = "docs/devices/oppo-k9-55-oppocnm632.md"
+FILTER = re.compile(r"<intent-filter\b[^>]*>(.*?)</intent-filter>", re.S)
+CATEGORY = re.compile(r'<category\s+android:name="([^"]+)"')
def active_packages(path):
@@ -33,6 +44,10 @@ def active_packages(path):
return packages
+def known_line(text, marker):
+ return text.split(marker, 1)[1].split("\n", 1)[0]
+
+
class OppoK9ColorOsTest(unittest.TestCase):
def test_the_note_names_the_allowlist(self):
text = NOTE.read_text(encoding="utf-8")
@@ -53,3 +68,22 @@ class OppoK9ColorOsTest(unittest.TestCase):
def test_the_examples_index_links_the_note(self):
# tv.json is not a markdown page. test_docs_pages_reachable only counts a markdown link.
self.assertIn(f"]({NOTE_LINK})", INDEX.read_text(encoding="utf-8"))
+
+ def test_home_filter_declares_modern_home(self):
+ blocks = FILTER.findall(MANIFEST.read_text(encoding="utf-8"))
+ homes = [CATEGORY.findall(block) for block in blocks if HOME in CATEGORY.findall(block)]
+ self.assertTrue(homes, "MainActivity's HOME intent-filter was not found")
+ self.assertIn(MODERN_HOME, homes[0])
+
+ def test_install_scripts_leave_the_stock_home_out(self):
+ sh = known_line(INSTALL_SH.read_text(encoding="utf-8"), 'KNOWN_STOCK_LAUNCHERS="')
+ ps1 = known_line(INSTALL_PS1.read_text(encoding="utf-8"), "$knownStock = @(")
+ self.assertNotIn(STOCK, sh)
+ self.assertNotIn(STOCK, ps1)
+
+ def test_troubleshooting_names_the_category_and_the_note(self):
+ text = TROUBLESHOOTING.read_text(encoding="utf-8")
+ self.assertIn(MODERN_HOME, text)
+ for package in ALLOWLIST:
+ self.assertIn(package, text)
+ self.assertIn(NOTE_PATH, text)