Skip to content

Debloat your Android TV, install apps, browse and transfer files on it, all from your phone. Just 3 MB, no tracking, no root, no PC.

Bring README, changelog and contributing up to date with dev

jesse-agent-232f97da8d69ae9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cda6d4..af6f9d2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,5 +6,13 @@ for the people using the app. Headings are `## <version> — <date>`, where
**New:**, **Improved:** or **Fixed:**, then a plain line of at most about
twelve words, ending with a link to its PR.
-A pull request into `main` fails CI until this file has a section for its
-version.
+Changes merged into `dev` collect under `## Unreleased`. A release renames
+that heading to its version and date. A pull request into `main` fails CI
+until this file has a section for its version.
+
+## Unreleased
+
+- **New:** Install apps on the TV from an APK, split APKs or a bundle. [#9](../../pull/9)
+- **New:** Send files to the TV's Download or Movies folder, and save them back. [#9](../../pull/9)
+- **New:** Suggested apps to disable, from a tested list for your TV. [#11](../../pull/11)
+- **New:** A remote: D-pad, volume, Play / Pause, typing, Sleep and Restart. [#12](../../pull/12)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b5e536..18ebd70 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,10 +1,10 @@
# Contributing to Tellyscope
-Thanks for helping! Tellyscope is pre-alpha, so the code and its structure are still moving.
+Thanks for helping! Tellyscope is in alpha, so the code and its structure are still moving.
## Ground rules
-- **Read the [safety rules](README.md#safety-rules) first.** A pull request that uninstalls packages, bypasses the protected list or skips the backup step won't be merged.
+- **Read the [safety rules](README.md#safety-rules) first.** A pull request that uninstalls packages, bypasses the protected list or skips recording what was already off won't be merged.
- **Open pull requests against `dev`.** `main` is the release branch and only takes `dev`.
- **One change per pull request.** Smaller is easier to review.
- **`./gradlew build` must pass** before you open a PR. CI runs the same command.
@@ -14,15 +14,15 @@ Thanks for helping! Tellyscope is pre-alpha, so the code and its structure are s
## Releases
- **Alpha:** every merge into `dev` publishes an alpha. CI builds `app.tellyscope.alpha`, which installs next to the release, and once the build passes it tags the commit `vX.Y.Z-alpha.N` and publishes a GitHub pre-release under that tag, with the APK named `Tellyscope-vX.Y.Z-alpha.N.apk`. `X.Y.Z` is the current `versionName`, and `N` is one past the highest alpha of that version. A failed build tags nothing. You can still put out an alpha by hand: tag a commit that is on `dev` and push the tag, for example `git tag v0.0.1-alpha.1 origin/dev && git push origin v0.0.1-alpha.1`. The tag's `X.Y.Z` must equal `versionName` in `app/build.gradle.kts`, and its commit must be on `dev`; otherwise the build fails and publishes nothing.
-- **Shipping:** a release is a pull request from `dev` into `main`, merged with a merge commit. It must raise `versionName` and `versionCode` in `app/build.gradle.kts` past the latest `v*` tag and add that version's section to [CHANGELOG.md](CHANGELOG.md); CI refuses anything else. Merging it tags `vX.Y.Z` and publishes a GitHub release with the signed APK, notes from the changelog section and the commits since the previous tag.
+- **Shipping:** a release is a pull request from `dev` into `main`, merged with a merge commit. It must raise `versionName` and `versionCode` in `app/build.gradle.kts` past the latest `v*` tag and turn the `## Unreleased` section of [CHANGELOG.md](CHANGELOG.md) into that version's section; CI refuses anything else. Merging it tags `vX.Y.Z` and publishes a GitHub release with the signed APK, notes from the changelog section and the commits since the previous tag.
- **Signing:** CI signs both builds from three repository secrets: `RELEASE_KEYSTORE_BASE64` (the keystore, base64-encoded), `RELEASE_KEY_ALIAS` and `RELEASE_KEY_PASSWORD`, which is both the store and the key password (keytool's PKCS12 default uses one for both). Only the maintainer holds the key; never commit a keystore. Local release builds are unsigned.
## Debloat lists
-Package lists are the riskiest part of the app. When you add a package:
+The per-TV lists behind **Suggested for this TV** live in the [tellyscope-devices](../../../tellyscope-devices) repository, not here; add or fix a list there. When you add a package to a list:
- Say which TV models you tested on, and what changed after disabling it.
-- If disabling it broke anything (launcher, updates, remote, input, HDMI-CEC), it belongs on the protected list instead.
+- If disabling it broke anything (launcher, updates, remote, input, HDMI-CEC), put it in the list's keep entries, or propose it for the built-in protected list (`adb/src/main/kotlin/app/tellyscope/adb/Protected.kt`) here.
## Style
diff --git a/README.md b/README.md
index 805802f..36ea4a4 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,48 @@
# Tellyscope
-See inside your Android TV from your phone. Live stats, processes, network and one-tap reversible debloat over Wi-Fi ADB. No root, no PC.
+See inside your Android TV from your phone. Live stats, reversible debloat, app installs, file copies and a remote, all over Wi-Fi ADB. No root, no PC.
-> **Status: pre-alpha.** The app builds and opens an empty screen. Nothing connects to a TV yet. Don't install it expecting it to do anything.
+> **Status: alpha.** Tellyscope connects to real TVs and makes real changes, but it has only been tried on a few models. Expect rough edges, and keep the TV's own remote nearby.
-## What it will do
+<p>
+ <img src="docs/screenshots/scan.png" width="200" alt="Finding TVs on the Wi-Fi">
+ <img src="docs/screenshots/tv-page.png" width="200" alt="A TV's page: memory, storage, CPU and temperature">
+ <img src="docs/screenshots/install.png" width="200" alt="Installing an app on the TV">
+ <img src="docs/screenshots/remote.png" width="200" alt="The remote control">
+</p>
-Tellyscope is a phone app that talks to your Android TV or Google TV over the network using ADB, the same debugging protocol developers use. Once connected, it shows you:
+<sub>Rendered from the app's screenshot tests with sample data.</sub>
-- **Live stats**: CPU, memory, storage and temperature.
-- **Processes**: what's running and what's eating resources.
-- **Network**: interfaces, addresses and traffic.
-- **Debloat**: turn off preinstalled apps, ads and trackers you don't want, and turn them back on with one tap.
-- **Install apps**: pick an APK, a set of split APKs or an `.apks`/`.xapk` bundle on your phone and install it on the TV. It tells you first whether it's new or an update, and won't put an older version over a newer one unless you tick the box.
-- **Files**: send a file from your phone into the TV's Download or Movies folder, or save one from there to your phone. Nothing on the TV is overwritten.
-- **Remote**: D-pad, Back, Home, volume and play/pause from the phone, typing into the TV's search boxes, and Sleep or Restart.
+## What it does
-It connects either through classic network debugging (port 5555) or through Android 11+ wireless debugging with a pairing code.
+Tellyscope is a phone app that talks to your Android TV, Google TV or Fire TV over the network using ADB, the same debugging protocol developers use.
+
+- **Find and connect.** It looks for TVs on your Wi-Fi, or you add one by IP address. Classic network debugging (port 5555) and Android 11+ wireless debugging with a 6-digit pairing code both work. A step-by-step card shows how to turn debugging on for Google TV, Android TV, Fire TV, Xiaomi and XGIMI.
+- **Remembers your TVs.** They reconnect on their own after a restart of the app or the TV. You can rename a TV (the name stays on your phone) or forget it.
+- **Live stats.** Memory, storage, CPU, temperature and uptime, with a one-line summary such as "Running fine" or "Storage almost full".
+- **Apps.** Every app on the TV with its real name and icon. Stop, disable, turn back on or open any app that isn't protected; each button says what it will do and asks first.
+- **Suggested for this TV.** Tellyscope matches your TV to a tested clean-up list (adapted from [cleanyourtv](https://github.com/Gathin23/cleanyourtv)) and shows the apps on it that are still on. Pick your model if it isn't matched. Apps are pre-ticked only when the TV runs the Android version the list was tested on, and you confirm before anything is disabled.
+- **History.** Every change is listed with an Undo, and **Restore everything** turns back on what Tellyscope turned off. History is kept per TV, across restarts.
+- **Install apps.** Pick an APK, several split APKs or an `.apks`/`.xapk`/`.apkm` bundle on your phone. Before installing, Tellyscope shows the app's name, version and size and says whether it's new, an update, a reinstall or an older version. It won't install an older version over a newer one unless you tick the box. If the TV refuses, you get the reason in plain words.
+- **Files.** Send a file from your phone into the TV's Download or Movies folder, or save one from there to your phone. A file with the same name gets a " (1)" instead of being overwritten, and a cancelled copy leaves nothing half-written behind.
+- **Remote.** D-pad and OK, Back, Home, Menu, volume and mute, Play / Pause and Sleep. Type into the TV's search boxes from your phone (plain letters, numbers and symbols, one line at a time). Restart the TV; Tellyscope reconnects when it's back.
+
+## Setting up your TV
+
+1. On the TV, open **About** in Settings and press OK on **Build** (Fire TV: your device's name) 7 times, until it says you're a developer.
+2. In **Developer options**, turn on **USB debugging** (Fire TV: **ADB debugging**), and **Network debugging** if your TV lists it. Newer TVs may show **Wireless debugging** instead; turn that on too.
+3. Put your phone on the same Wi-Fi as the TV and open Tellyscope. Tap **Connect** next to your TV.
+4. The TV asks "Allow USB debugging?". Tick **Always allow from this computer**, then press **Allow**. With wireless debugging, Tellyscope asks for the 6-digit pairing code the TV shows instead.
+
+The menu paths differ by brand; the app shows the exact steps for yours.
## Safety rules
Debloating a TV can break it if done carelessly. Tellyscope is built around these rules, and contributions must keep them:
1. **Disable only, never uninstall.** Tellyscope uses `pm disable-user`, which is reversible from the app or with `pm enable`. It never runs `pm uninstall`, not even for the current user.
-2. **Backup first.** Before the first change on a TV, Tellyscope records the list of enabled packages, so every change can be undone, even after an app reinstall.
-3. **Protected list.** Packages the TV needs to boot, update, show the launcher or accept input are on a protected list. Tellyscope refuses to disable them, and there is no override in the app.
+2. **Record before changing.** Before the first change on a TV, Tellyscope notes which apps were already off, so **Restore everything** turns back on only what Tellyscope turned off. Every change goes into the TV's history with an Undo. The history lives on the phone and is deleted if you uninstall Tellyscope; a disabled app still shows in the Apps list with **Turn on**.
+3. **Protected list.** Packages the TV needs to boot, update, show the home screen or accept input are on a protected list. Tellyscope refuses to stop or disable them, and there is no override in the app. If the TV doesn't say which app is its home screen, Tellyscope refuses to stop or disable anything. A TV's suggested list can protect more apps, never fewer.
4. **No root, no exploits.** Only what ADB allows on a stock TV.
5. **Nothing left on the TV.** To show real app names and icons, Tellyscope copies a small helper to `/data/local/tmp`, runs it once and deletes it. The helper only reads through PackageManager: no writes, no permissions, no network.
diff --git a/docs/screenshots/install.png b/docs/screenshots/install.png
new file mode 100644
index 0000000..5d6f5c5
Binary files /dev/null and b/docs/screenshots/install.png differ
diff --git a/docs/screenshots/remote.png b/docs/screenshots/remote.png
new file mode 100644
index 0000000..87016a3
Binary files /dev/null and b/docs/screenshots/remote.png differ
diff --git a/docs/screenshots/scan.png b/docs/screenshots/scan.png
new file mode 100644
index 0000000..daff088
Binary files /dev/null and b/docs/screenshots/scan.png differ
diff --git a/docs/screenshots/tv-page.png b/docs/screenshots/tv-page.png
new file mode 100644
index 0000000..8f1bc5e
Binary files /dev/null and b/docs/screenshots/tv-page.png differ