# Installing Tigris — instructions for AI agents You are installing Tigris, an Android TV launcher, onto the user's TV from their computer. Follow these steps in order. Talk to the user in their language (most users write Chinese). The TV is someone's home device: whenever a step below says to ask, ask first. ## Hard rules - Never run `svc power shutdown`, `svc power reboot`, `reboot` or `input keyevent KEYCODE_POWER` / `KEYCODE_SLEEP` without asking. A powered-off TV can only be turned back on with its remote. - Never `pm uninstall` a system app or the TV's own launcher. - **Never disable the stock launcher on Xiaomi / Redmi** (`com.mitv.tvhome`, PatchWall). The fallback home refuses third-party launchers too, so the TV boots to a black screen. On Xiaomi, TCL and similar firmwares use the home guard (section 10) instead. On other TVs, disable a launcher only with the user's consent (step 5), and tell them how to undo it. - Before you send `KEYCODE_DPAD_CENTER` / `ENTER` on the TV, check what is focused (step 6). Many Tigris buttons power the TV off or put it to sleep. - Do not change other TV settings (animation scales, app permissions, background restrictions) unless the user asks. ## 0. What you need - A computer on the same local network as the TV, with `adb` installed (Android SDK Platform-Tools). Check with `adb version`. If it is missing, install it: Windows `winget install Google.PlatformTools`, macOS `brew install android-platform-tools`, Debian/Ubuntu `apt install adb`. - The TV's IP address. Ask the user. It is under Settings → Network (网络) or About (关于) on most TVs. - ADB debugging enabled on the TV. Most users have never done this, so if `adb connect` fails in step 1, walk them through it for their brand. Ask for the brand if you don't know it. | TV | How to turn on ADB | |---|---| | **Xiaomi / Redmi** | 设置 → 关于 → **产品型号**: press OK repeatedly until it says developer mode is on. Then 设置 → 账号与安全: turn on **ADB 调试** and **安装未知来源的应用**. | | **TCL / FFalcon (雷鸟)** | 设置 → 关于 → **本机信息**, then press **Up, Down, Left, Right** on the remote, less than a second apart. A **更多** group appears at the bottom; turn on **ADB** there. | | **Sony BRAVIA** | Settings → System → About → press OK on **Build** (Android TV OS build) 7 times. Then Settings → System → Developer options → turn on **USB debugging**. | | **Stock Android TV / Google TV**, Hisense and others | Settings → Device Preferences → About → press **Build** 7 times. Then turn on **USB debugging** in Developer options (sometimes called Network debugging or ADB debugging). | The first time the computer connects, the TV asks "Allow USB debugging?" (允许 USB 调试吗？). The user must choose **Allow** (允许) and tick **Always allow** (始终允许). ## 1. Connect ```sh adb connect :5555 adb -s :5555 get-state # should print "device" ``` If it prints `unauthorized`, the TV is showing "Allow USB debugging?". Ask the user to tick "Always allow from this computer" and press Allow, then retry. If the connection is refused, ADB is off (step 0). Xiaomi turns it off again on every wake from standby until Tigris's "keep ADB on" option is set (step 4). Use `-s :5555` on every later command. ## 2. Check the TV ```sh adb -s :5555 shell getprop ro.build.version.sdk # must be >= 28 (Android 9) adb -s :5555 shell getprop ro.product.manufacturer adb -s :5555 shell getprop ro.product.model adb -s :5555 shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME adb -s :5555 shell settings get secure screensaver_components adb -s :5555 shell settings get secure enabled_accessibility_services ``` Note the current home activity (the stock launcher), the current screensaver and the accessibility services; you need them to undo the install. Tell the user which features they will get (see the compatibility table in README.md). Section 9 covers adapting the app when something doesn't work. ## 3. Install There are two builds: - `Tigris.apk` (standard) declares itself a home screen. Use it everywhere except TCL. - `Tigris-guard.apk` declares no home screen and appears as an ordinary app. TCL refuses any APK that declares one unless TCL signed it. The guard build is otherwise identical; the home guard (section 10) keeps it in front. ```sh curl -L -o Tigris.apk https://github.com/lesnolie/Tigris/releases/latest/download/Tigris.apk adb -s :5555 install -r Tigris.apk ``` **If it fails with `INSTALL_FAILED_VERIFICATION_FAILURE`** (TCL: its verifier refuses every adb install), install the guard build through TCL's own 多屏互动 (T-Cast) instead. It needs Python 3 and the repository's `tools/tcast-push.py`: ```sh curl -L -o Tigris-guard.apk https://github.com/lesnolie/Tigris/releases/latest/download/Tigris-guard.apk curl -L -o tcast-push.py https://raw.githubusercontent.com/lesnolie/Tigris/main/tools/tcast-push.py python3 tcast-push.py Tigris-guard.apk ``` The script serves the APK from this computer on port 8765. The TV shows "多屏互动：正在发起应用推送" in a corner. Tell the user to choose **同意** on the TV. If the computer's firewall asks, allow the connection. If the script can't reach port 6553 (no 多屏互动 on that model), fall back to installing on the TV itself: ```sh adb -s :5555 push Tigris-guard.apk /sdcard/Download/Tigris.apk adb -s :5555 shell am start -n com.dangbeimarket/.ui.apkmanager.ApkManagerActivity # if 当贝市场 is installed ``` Then ask the user to pick Tigris in Dangbei's package manager (or with any file manager on the TV) and install it. Check the result with `adb shell pm path com.leslie.tvhome`. If GitHub is unreachable, build from source instead: clone the repo, then `./gradlew assembleStandardRelease assembleGuardRelease` (needs JDK 17 and an Android SDK; set `sdk.dir` in `local.properties`). The APKs are `app/build/outputs/apk/standard/release/app-standard-release.apk` and `app/build/outputs/apk/guard/release/app-guard-release.apk`. ## 4. Make it the home screen Standard build: ```sh adb -s :5555 shell cmd package set-home-activity com.leslie.tvhome/.HomeActivity adb -s :5555 shell input keyevent KEYCODE_HOME ``` Then grant what only adb can grant. These are needed on every TV whose system keeps the Home key for its own launcher (Xiaomi, TCL, most Chinese firmwares), and harmless elsewhere: ```sh P=com.leslie.tvhome adb -s :5555 shell pm grant $P android.permission.WRITE_SECURE_SETTINGS adb -s :5555 shell cmd notification allow_listener $P/$P.RevivalListener adb -s :5555 shell appops set $P SYSTEM_ALERT_WINDOW allow adb -s :5555 shell appops set $P APP_AUTO_START allow # TCL only; other firmwares print an error, ignore it adb -s :5555 shell appops set $P APP_ASSOC_START allow # TCL only ``` | Grant | What it is for | |---|---| | `WRITE_SECURE_SETTINGS` | Switches the home guard back on after the system turns it off; keeps the photo frame as screensaver; keeps ADB on; Xiaomi's backlight slider | | Notification listener | Restarts Tigris about half a second after the system kills it, and at boot. No notification is read | | `SYSTEM_ALERT_WINDOW` | Opening the home screen from the background after boot | | TCL `APP_AUTO_START` / `APP_ASSOC_START` | TCL blocks third-party apps from starting at boot otherwise | If step 5 shows the stock launcher coming back, turn on the home guard (section 10). On Xiaomi, also ask whether to keep ADB on: Xiaomi switches ADB off on every wake, which makes later updates through adb impossible until the user turns it on again in settings. ```sh adb -s :5555 shell am broadcast -a com.leslie.tvhome.CONFIG -n com.leslie.tvhome/.ConfigReceiver --ez guard true --ez keep_adb true # prints data="guard=true keep_adb=true secure_settings=true" ``` The user can change both later in 设置 → 桌面守护 / 保持 ADB 调试开启. These rows only appear where they matter: 桌面守护 on Xiaomi, TCL, or wherever Tigris is not the default home; 保持 ADB 调试开启 on Xiaomi only. ## 5. Verify Take a screenshot and look at it: ```sh adb -s :5555 exec-out screencap -p > tv.png ``` You should see a compact clock, two round controls and an optional profile portrait top-right, and a row of app tiles on a glass dock near the bottom. Back opens the Control Center: separate floating glass controls, or a dark panel on low-end TVs. Press Home (`input keyevent KEYCODE_HOME`) and check again. If the stock launcher appears instead: - On Xiaomi, TCL and other Chinese firmwares, turn on the home guard (step 4, section 10). **Do not disable the stock launcher on Xiaomi.** - On other TVs, run step 4 again and press Home once more. If it still comes back, try the guard first. Only if that fails, ask the user whether to disable the vendor launcher, and only then: ```sh adb -s :5555 shell pm disable-user --user 0 # undo: adb -s :5555 shell pm enable ``` On first start the app downloads background photos (needs internet). The first minute may show a gradient. ## 6. Local debugging authorization (power, sleep, deep memory cleanup) On first start Tigris asks to enable these features. When the user presses "开始", the TV shows "Allow debugging?" again, this time from the TV to itself. The user must tick "Always allow" and press Allow. Check the screen with `screencap` and guide them. You can verify afterwards: the Control Center (Back key on the home screen) no longer shows a "本机调试未授权" line. Once this is allowed, Tigris can also give itself the step 4 grants (设置 → 桌面守护 does that). If you need to press buttons for the user, first find the focused element: ```sh adb -s :5555 shell uiautomator dump /sdcard/u.xml && adb -s :5555 shell cat /sdcard/u.xml ``` Look for `focused="true"` and its `text` / `bounds` before sending `KEYCODE_DPAD_CENTER`. ## 7. Sony BRAVIA only: brightness, plus TV-side volume and HDMI Skip this step if the manufacturer is not Sony. The TV's IP control API must accept a registration for client `tvhome:1`: ```sh BODY='{"method":"actRegister","id":1,"version":"1.0","params":[{"clientid":"tvhome:1","nickname":"TVHome","level":"private"},[{"value":"yes","function":"WOL"}]]}' curl -s http:///sony/accessControl -d "$BODY" ``` The TV now shows a 4-digit PIN for about a minute. Ask the user to read it out, or read it from a `screencap`. Then: ```sh curl -s -u ":" http:///sony/accessControl -d "$BODY" # {"result":[]} means success ``` If the first call returns an error or nothing, ask the user to enable Settings → Network & Internet → Remote device settings → "Control remotely" (the menu name varies by model), then retry. To check: open the Control Center. The brightness slider is shown and the input row says "当前：…". ## 8. Optional settings Tell the user these exist; change them only if asked. All of them are in the Control Center → 设置 (gear), or on the "主屏幕设置" page: - Background (背景, also the **壁纸** tile on the home screen): every choice shown as a picture, picked with one press — Bing photos, anime wallpapers, 我的照片 (uploaded), 自定义链接, or a gradient theme; plus the change interval. The same page shows a QR code: a phone on the same Wi-Fi opens a page to upload its own photos, paste picture links (an image, a random-image API, or a page / JSON listing images; fetched daily), and pick the background and screensaver. - Photo frame as the system screensaver (电视空闲时显示相框), the idle time, and its content (屏保内容): photos or Apple TV aerial films (streamed from Apple, about 15–20 Mbps; falls back to photos offline). On Xiaomi, which shows its own screensaver instead of Android's, the home screen starts the frame 15 s before Xiaomi's would. - HDMI inputs on the home screen: Control Center → 输入源 → 在主屏幕上显示…. - Apps kept alive by memory cleanup. - Clock (时间格式, 时钟位置), focus animation (聚焦动画), Control Center style (控制中心样式). The last two default to 自动, which picks the cheaper look on low-end TVs. - Boot animation (开机动画), off by default. The app ships no video: the user uploads one on the phone page, or you push it with `adb push