docs: rewrite README for the Shield-only fork

2026-10-08 07:26:13 +01:00
1 parent 6622cc04b4
commit 304e6dc3ec
@@ -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