Add scheduled TV updates from Forgejo

Check a commit-pinned manifest on a configurable schedule, notify about newer versions, verify downloaded APKs, and hand off installation to Android. Generate the feed with each signed build.

Include the wake artwork recovery fix and on-device lifecycle and updater regression tests.
This commit is contained in:
Elijah Kuntz 2026-10-18 08:51:21 -07:00
parent f5f1c0928f
commit 0d1a11d943
23 changed files with 1493 additions and 51 deletions

View file

@ -2,6 +2,8 @@
A native, remote-first launcher built for the onn. 4K Plus Streaming device (Android 14, 2 GB RAM). It is installed alongside Projectivy as `tv.luma.launcher`. Home now opens Luma; Projectivy remains installed and enabled as a fallback.
Version **1.1.1** adds updates directly from the TV and includes the wake fix introduced in 1.0.1. Every resume restores missing images, including when Android briefly pauses the launcher without stopping it. Already-loaded tiles and images are kept on pause-only resumes; leaving the launcher still releases image memory.
## Use it
Press **Home**, or open **Luma** from Projectivy's app list. It can also be opened with:
@ -68,6 +70,30 @@ Tokens are encrypted with AES-GCM using a key held in Android Keystore. **Discon
Media rendering and the connection/disconnection flow were checked against a temporary local Plex fixture. A real Plex server and account have not been connected, so account authorization and actual title playback remain to be verified with your library. Pairing is user initiated; no background account polling occurs.
## Updates on every TV
Open **Settings → Updates**. Checks default to **Daily**; alternatives are every 3, 6, or 12 hours, or Off. **Check now** works independently of the schedule. A check also runs when returning home if one is due. Android schedules one small, persisted, network-constrained job and may defer it while the TV is sleeping or offline. There is no continuous polling service and no automatic APK download.
When a newer version is found, Luma posts a TV notification once for that version and shows an **Update** button beside the clock. Notifications can be managed in the same panel. Neither the check nor the notification opens another screen while watching an app. Select **Download & install** to download the APK. The first time, Android asks you to allow installations from Luma; Android's package installer then asks you to confirm the update with the remote. Settings and app data are retained. This uses the system installer, not silent or root installation.
The default public HTTPS feed is:
```text
https://git.elijahkuntz.com/Elijah/Luma/raw/branch/main/output/update.json
```
No SSH key or Forgejo account token is stored on the TV. For branch-based Forgejo URLs, Luma resolves the branch to a commit first, then reads both the manifest and APK from that immutable commit. It bounds metadata to 64 KiB and APK downloads to 32 MiB. Before opening the installer, it checks the expected SHA-256 and file size, package name, increasing version code, Android compatibility, and the installed signing certificate. A different signing key is rejected. The provider grants read-only access to exactly the verified APK URI. Interrupted downloads are removed; completed APKs are removed after the updated app starts.
### Publish an update
1. Increase `versionCode` and `versionName` in both `app/src/main/AndroidManifest.xml` and `app/build.gradle`. Every published update needs a greater version code.
2. Edit `docs/UPDATE_NOTES.md`, then run `scripts/build.sh` using the existing signing keystore. The build generates `output/Luma.apk` and `output/update.json` together, including the APK checksum and size.
3. Commit and push the source changes, **both output files**, and release notes to `main`. The next scheduled/manual check on each TV discovers the update. No separate release upload or account setup is needed.
Preserve `.tools/luma-development.keystore` separately from Git: the same signing key is required for every update. The first updater-capable APK must be installed on each TV once, through ADB, Downloader, or a file manager; later updates can be handled within Luma.
Android scheduling and installation behavior follow the [JobInfo API](https://developer.android.com/reference/android/app/job/JobInfo.Builder) and [package installation API](https://developer.android.com/reference/android/content/pm/PackageManager#canRequestPackageInstalls()).
## Performance design
- Platform Java/Android views and Canvas; no WebView, Compose runtime, playback engine, or third-party runtime dependencies.
@ -75,7 +101,7 @@ Media rendering and the connection/disconnection flow were checked against a tem
- App artwork is rasterized to 288 × 162. Icon cache is capped at 3 MiB; visible tiles also hold their displayed images.
- Plex image cache is capped at 3 MiB. Hero images are sampled to at most roughly 1280 × 720; rows and network response sizes are bounded.
- At most the current and previous artwork are retained during a short crossfade. A focus debounce avoids loading artwork for every passing selection.
- No boot receivers, alarms, PowerManager wake locks, or periodic background jobs. The optional Home override is an event-driven accessibility service in a separate process; turning it off removes that bound service. The optional DreamService runs only when Android explicitly binds it as a system screensaver.
- No boot receiver, alarms, or PowerManager wake locks. Update checks use one brief JobScheduler job, normally daily. The optional Home override is an event-driven accessibility service in a separate process; turning it off removes that bound service. The optional DreamService runs only when Android explicitly binds it as a system screensaver.
- Clock updates once per minute; optional scene rotation runs only while Luma is visible.
- On pause, networking and scene animations are canceled. On stop, queued work, image references, and caches are cleared. Worker threads time out after ten idle seconds.
- Android can reclaim the cached launcher process while another app is running. It is not kept alive artificially.
@ -114,4 +140,16 @@ python3 scripts/device_smoke.py --part screensaver-timeout
The scripts operate the TV through ADB. Run one at a time with the TV awake. The customization checks expect the documented defaults. The Plex fixture requires `python3 scripts/plex_fixture.py` running on the host, followed by `python3 scripts/device_smoke.py --part plex`. It uses temporary ADB reverse forwarding to a loopback server and disconnects the fixture when finished.
The wake regression uses a separate test APK signed with the same development key, without adding any test interface to Luma. It replays interrupted background loading, a pause/resume without another start callback, memory trimming, and five stop/start cycles. The old 1.0.0 build fails the interrupted-wake case; 1.0.1 passes.
```sh
bash scripts/build-wake-tests.sh
.tools/platform-tools/adb -s 192.168.50.195:35635 install -r output/Luma-wake-tests.apk
.tools/platform-tools/adb -s 192.168.50.195:35635 shell am instrument -w -r tv.luma.launcher.tests/.WakeRegressionInstrumentation
.tools/platform-tools/adb -s 192.168.50.195:35635 uninstall tv.luma.launcher.tests
```
Successful output ends with `INSTRUMENTATION_CODE: -1` and PASS lines for all cases. The runner controls activity lifecycle callbacks and should be run with no other device tests in progress.
Android force-stops the target package during instrumentation and can mark its accessibility helper as stopped/crashed. After testing, check **Settings → Default launcher** and toggle **Luma Home button** off/on in Android Accessibility if needed, then reopen Luma. This is test-runner cleanup, not an action needed during normal TV wake.
See [docs/ASSETS.md](docs/ASSETS.md) for the wallpaper generation prompt and asset provenance. Android TV intent handling follows [Android's TV app guidance](https://developer.android.com/training/tv/get-started/create); Plex integration follows the [official Plex Media Server API documentation](https://developer.plex.tv/pms/).