diff --git a/README.md b/README.md index d5defeb..fdabc22 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,108 @@ # NVIDIA Shield -[![hacs][hacs-badge]][hacs-url] [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +Home Assistant integration for the NVIDIA Shield TV — ADB media session tracking for +now-playing state from any app, plus Google remote-protocol commands, Jellyfin rich +metadata, and power monitoring. -Enhanced NVIDIA Shield TV integration for Home Assistant. ADB-based media session tracking, Jellyfin rich metadata, power monitoring, and receiver coordination. +This is a **Shield-only fork** of [ltomes/ha-nvidia-shield](https://github.com/ltomes/ha-nvidia-shield) +(early 0.1.x), rebuilt around a different architecture: one integration, one device, +ADB as the state source, and no dependency on separate `androidtv` / `androidtv_remote` +integrations. -> **Status:** Early access (0.1.x). Tested on the author's own setup; expect rough edges and occasional breaking changes until 1.0. Please file issues on GitHub if anything is broken. +> **Status:** early fork, actively rebuilt. Releases are date-based (`v2026.10.08`). +> Expect rough edges until the MVP phases land. The build-out plan is in +> [`docs/MVP_PLAN.md`](docs/MVP_PLAN.md); device research is in +> [`docs/RESEARCH_SHIELD.md`](docs/RESEARCH_SHIELD.md). -```mermaid -graph TD - subgraph "NVIDIA Shield Integration" - ADB["ADB Media Session"] -->|now playing| Entity["media_player.nvidia_shield"] - JF["Jellyfin"] -->|rich metadata| Entity - ATV["Android TV Remote"] -->|power / commands| Entity - PWR["Smart Plug"] -->|power state| Entity - end +## What we're building (the fork's goals) - Entity -->|"media_dag_*"| MZ["Media Zone"] +The fork exists to make a single integration own the Shield end-to-end: - style Entity fill:#76b900,color:#fff - style MZ fill:#1a73e8,color:#fff - style ADB fill:#444,color:#fff - style JF fill:#00a4dc,color:#fff - style ATV fill:#444,color:#fff - style PWR fill:#444,color:#fff -``` +1. **Event-driven ADB media session tracking as the primary playback state source** — + `dumpsys media_session` over a persistent connection, not screen capture, not + 10-second polling. +2. **Fallback state for apps without media sessions** — e.g. TiviMate publishes + none at all; foreground-app detection (`mResumedActivity`) + last-known-state + + the "audio playback" hint from the same session dump close that gap. +3. **All-in-one device** — absorb the Google remote protocol (`androidtvremote2`): + a `remote` entity alongside the media player, `play_media` with + `media_content_type: channel` for TiviMate channel-by-number, absolute volume, + focused-app push events. ADB stays the playback-state source; ADB pairing stays intact. +4. **Retire the surrounding glue** — the `mediasession2mqtt` bridge, universal + media player templates, and external remote entity reading all become native + integration behavior. -## Features +Phases 0–4 with files, risks, and definitions of done live in +[`docs/MVP_PLAN.md`](docs/MVP_PLAN.md). -- **ADB Media Session** -- Now-playing from any app (PipePipe, Spotify, VLC, Plex, etc.), not just Jellyfin -- **Jellyfin Rich Metadata** -- Title, series, season/episode, duration, position, stream details (resolution, codec, HDR, audio format) -- **Power Monitoring** -- Smart plug for reliable on/off detection with auto-discovered sibling sensors (watts, voltage, current) -- **Receiver Coordination** -- Links to a receiver entity and input name -- **Intent Tracking** -- Commands reflect in HA state immediately, self-heal against actual device state -- **Privacy Mode** -- Show only app name without media details for non-Jellyfin apps -- **Controlled ADB Pairing** -- Dedicated pairing step in config flow + re-pair button entity -- **Media DAG Attributes** -- Full signal chain data for [Media Zone](https://github.com/ltomes/ha-media-zone) orchestration +## Current features (inherited from upstream 0.1.x) + +- **ADB Media Session** — now-playing from any app that publishes a session + (Spotify, Netflix, Plex, Wholphin, …) +- **Jellyfin rich metadata** — title, series/episode, position, stream details + (resolution, codec, HDR, audio format) via the HA Jellyfin integration's cache +- **Power monitoring** — smart plug for reliable on/off with auto-discovered + sibling sensors (watts, voltage, current) +- **Intent tracking** — commands reflect in HA state immediately, self-heal + against actual device state +- **Privacy mode** — show only app name without media details for non-Jellyfin apps +- **Media DAG attributes** — `media_dag_*` attributes for media-zone style orchestration + +Changes inherited from upstream still apply in 0.1.x code: polling is timer-based, +the ADB connection lives inside the media player entity, and fallback app state +arrives in Phase 3. + +## Releases + +- **Date-based versioning**: `vYYYY.MM.DD` (e.g. `v2026.10.08`). +- Pushes to `master` on [Gitea](https://git.notexpectedyet.com/notexpectedyet/ha-nvidia-shield) + run the release workflow (`.github/workflows/release.yml`): + - A plain push publishes the current day's release (same-day pushes are deduped). + - Bumping `version` in `custom_components/nvidia_shield/manifest.json` forces that + specific version's release before the date fallback kicks in. +- Releases land on Gitea (tag + `nvidia_shield.zip` asset), and are optionally + mirrored to a public GitHub repo for HACS. ## Installation -### HACS (recommended) +### HACS (custom repository — GitHub mirror) + +HACS only works with public GitHub repositories, so releases are mirrored from +Gitea to a public GitHub repo. Add the *mirror* as a custom repository: 1. In HACS, open the overflow menu (⋮) → **Custom repositories**. -2. Paste `https://github.com/ltomes/ha-nvidia-shield`, pick type **Integration**, click **Add**. +2. Paste `https://github.com/notexpectedyet/ha-nvidia-shield`, pick type + **Integration**, click **Add**. 3. Find **NVIDIA Shield** in the HACS list and click **Download**. 4. **Restart Home Assistant.** -5. Go to **Settings → Devices & Services → Add Integration**, search for **NVIDIA Shield**, and set up the integration (see [Configuration](#configuration)). ### Manual -Copy `custom_components/nvidia_shield` to your HA `config/custom_components/` directory, restart, then add the integration from **Settings → Devices & Services**. +Copy `custom_components/nvidia_shield` to your HA `config/custom_components/` +directory, restart, then add the integration from **Settings → Devices & Services**. ## Configuration 1. Settings > Devices & Services > Add Integration > "NVIDIA Shield" 2. Select the Android TV Remote entity for your Shield 3. Enable ADB if you want now-playing from all apps -4. If ADB is enabled, the next step will pair -- approve the prompt on the Shield +4. If ADB is enabled, the next step will pair — approve the prompt on the Shield 5. Optionally configure Jellyfin, receiver, power switch ### ADB Pairing -ADB is paired during setup via a dedicated config flow step. If you need to re-pair later (e.g., after factory reset), use the **"Pair ADB"** button on the device page in HA. +ADB is paired during setup via a dedicated config flow step. If you need to +re-pair later (e.g. after factory reset), use the **"Pair ADB"** button on the +device page in HA. Requirements: Settings > Developer options > Network debugging enabled on the Shield. ### Options -- **Jellyfin Media Player** -- Auto-detected or manually selected -- **Receiver + Input** -- For Media Zone coordination -- **Power Switch** -- Smart plug entity -- **ADB Host/Port** -- Override auto-detection if needed +- **Jellyfin Media Player** — auto-detected or manually selected +- **Receiver + Input** — for media-zone coordination +- **Power Switch** — smart plug entity +- **ADB Host/Port** — override auto-detection if needed ## Entities @@ -82,20 +115,11 @@ Requirements: Settings > Developer options > Network debugging enabled on the Sh ## Development -Shared ADB helpers live in [ha-adb-common](https://github.com/ltomes/ha-adb-common) and are also used by [ha-hisense-tv](https://github.com/ltomes/ha-hisense-tv). For HACS installs, a copy is **vendored** at `custom_components/nvidia_shield/ha_adb_common/` so end users need nothing extra. We plan to publish `ha-adb-common` to PyPI so it can be declared as a normal `manifest.json` requirement; until then, the vendored copy is the source consumed at runtime. - -To hack on the shared code locally, clone [ha-adb-common](https://github.com/ltomes/ha-adb-common) as a sibling directory and run `uv sync --extra dev` — the `[tool.uv.sources]` section in `pyproject.toml` wires it up editable. - -## Part of the Media Zone Ecosystem - -This integration works standalone, but pairs with [ha-media-zone](https://github.com/ltomes/ha-media-zone) to create a unified zone controller: - -- [ha-media-zone](https://github.com/ltomes/ha-media-zone) -- Orchestrates receiver + display + sources into one entity -- [ha-emotiva-mc1](https://github.com/ltomes/ha-emotiva-mc1) -- RS232 control for Emotiva MC1 receiver -- [ha-hisense-tv](https://github.com/ltomes/ha-hisense-tv) -- Hisense Google TV control via ADB + AirPlay - -[hacs-badge]: https://img.shields.io/badge/HACS-Custom-41BDF5.svg -[hacs-url]: https://github.com/hacs/integration +- **Repository:** [Gitea — git.notexpectedyet.com/notexpectedyet/ha-nvidia-shield](https://git.notexpectedyet.com/notexpectedyet/ha-nvidia-shield), branch `master` +- **CI/CD:** Gitea Actions; every push to `master` releases (see `.github/workflows/release.yml`). + The optional `hacs-github-mirror` job needs `GH_MIRROR_TOKEN` + `GH_MIRROR_REPO` secrets. +- **Shared ADB helpers** are vendored at `custom_components/nvidia_shield/ha_adb_common/` + (trimmed in this fork); dev extras in `pyproject.toml` (`uv sync --extra dev`). ## License