Kaloyan DanchevandClaude Opus 4.6
332bbc8fe2
Bind-mounts a transparent web page over LG Home that launches Luma via WebOSServiceBridge, with a subscription-based background watcher as fallback. Tested on LG 65NANO813PA, webOS 6.5.3. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# luma-home
|
|
|
|
Replaces the LG webOS Home screen with [Luma](https://github.com/ecklf/lg-luma) on webOS 5/6 TVs rooted via [Homebrew Channel](https://github.com/nicko88/LG-Homebrew).
|
|
|
|
## How it works
|
|
|
|
LG Home (`com.webos.app.home`) is a native QML app. This project bind-mounts a transparent web page over its directory so SAM sees a web-type Home. The web page immediately calls `WebOSServiceBridge` to launch Luma. A background watcher provides a fallback redirect via `luna-send` subscription.
|
|
|
|
### Components
|
|
|
|
| File | On TV at | Purpose |
|
|
|------|----------|---------|
|
|
| `overlay/appinfo.json` | `/media/developer/luma-home/overlay/` | Home manifest — web type, transparent, no splash |
|
|
| `overlay/index.html` | same | Minimal page that launches Luma via WebOSServiceBridge |
|
|
| `boot-hook.sh` | `/media/developer/luma-home/` | Homebrew Channel boot hook — mounts overlay, restarts SAM, launches Luma |
|
|
| `watcher.sh` | same | Background watcher — subscribes to foreground events, redirects Home→Luma |
|
|
|
|
### Boot flow
|
|
|
|
1. Homebrew Channel runs `boot-hook.sh` at cold boot
|
|
2. Bind-mount replaces `/usr/palm/applications/com.webos.app.home` (RAM only — reboot without the hook restores stock)
|
|
3. SAM restarts and reads the web manifest
|
|
4. Luma launches as the initial app
|
|
5. Watcher starts in the background
|
|
|
|
### Home button flow
|
|
|
|
1. User presses Home → system opens `com.webos.app.home` (our transparent web page)
|
|
2. `index.html` JS fires `WebOSServiceBridge` → launches Luma
|
|
3. Watcher catches the foreground change as backup → also launches Luma
|
|
|
|
## Requirements
|
|
|
|
- LG webOS TV rooted with Homebrew Channel (tested on webOS 6.5.3)
|
|
- Luma v2.1.0+ installed as `com.ecklf.luma`
|
|
- Telnet or SSH access to the TV
|
|
|
|
## Install
|
|
|
|
```sh
|
|
# Copy files to TV
|
|
scp -r overlay/ boot-hook.sh watcher.sh root@<TV_IP>:/media/developer/luma-home/
|
|
|
|
# SSH into TV and install the boot hook
|
|
chmod +x /media/developer/luma-home/boot-hook.sh /media/developer/luma-home/watcher.sh
|
|
ln -sf /media/developer/luma-home/boot-hook.sh /var/lib/webosbrew/init.d/10-luma-home
|
|
|
|
# Run it now (or reboot)
|
|
sh /media/developer/luma-home/boot-hook.sh
|
|
```
|
|
|
|
## Uninstall
|
|
|
|
```sh
|
|
# Remove boot hook
|
|
rm /var/lib/webosbrew/init.d/10-luma-home
|
|
|
|
# Kill watcher
|
|
kill $(cat /tmp/luma-watcher.pid 2>/dev/null)
|
|
|
|
# Unmount overlay (or just reboot)
|
|
umount /usr/palm/applications/com.webos.app.home
|
|
```
|
|
|
|
## Known limitations
|
|
|
|
- Brief visual transition when pressing Home (web page loads before Luma appears)
|
|
- `blockSystemApp` API (used by Luma's built-in Home integration for webOS 25/26) does not exist on webOS 5/6, so we use `systemctl restart sam` instead
|
|
- Native Home replacement (Luma binary as Home directly) does not work on webOS 6 — SAM handles native system apps differently
|
|
|
|
## Future
|
|
|
|
Fork Luma and patch `home.cjs` to support webOS 5/6 natively — replace the version check and `blockSystemApp` calls with the `systemctl restart sam` approach proven here.
|
|
|
|
## Tested on
|
|
|
|
- LG 65NANO813PA, webOS 6.5.3-47 (kisscurl-koli)
|
|
- Luma v2.1.0
|
|
- Homebrew Channel v0.7.3
|