Not-Expected-Yet/ha-nvidia-shield
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
6b866019ef7d26b3326b0f6facbea070d8ac71b9
ha-nvidia-shield/custom_components/nvidia_shield/media_player.py
T
James Mackay a8041e1428 feat(intents): the registered-intent engine, the buttons and the send_intent action (t17, part 1) 
Second half of the intents feature (docs/INTENTS_PLAN.md §3-§5), engine first: the
options screen that WRITES a registration follows in this same ticket.

WHAT SHIPPED.

* THE MODEL (const.py + media_player.py). A registered intent is ordinary options
  data — a list of dicts {id,name,package,activity,action,categories,data,fields}
  — so it survives a reload and is otherwise inert. `normalise_intent` accepts a
  row only if it names something to launch (a component with the slash Android
  requires, OR an action), `registered_intents` reads the options defensively
  (junk rows dropped, duplicate ids keep the first, the registration cap applied)
  and never touches a shell.
* THE COMMAND. `intent_am_start_command` assembles
  `am start -n <component> -a <action> -c <category>… -d <data> --es/--ei/--ez key value`.
  `{placeholder}` substitution is plain regex replacement over the DATA template
  only — no eval, no format(), no shell interpolation — and every value is
  shlex.quote'd, so a variable whose value is `"; rm -rf /"` reaches the device as
  literal data inside one quoted word. Address validation for adb_command is
  untouched; `adb_command` stays the one raw-shell door.
* HONEST FAILURES, each with a plain message AND a translation key so the button
  and the action both read well: an unknown intent name lists the registered ones,
  a missing REQUIRED field names the field, a variable the intent did not declare
  is REFUSED (nothing silently travels to the device and nothing is silently
  dropped), a value that cannot become its declared type names the field and the
  value, a data template with an unfilled placeholder names the placeholder, ADB
  off/down says the protocol cannot carry intents, a transport that never answered
  says so, and a device that refused the intent surfaces the DEVICE'S OWN message
  ("unable to resolve Intent", "does not exist", "Permission Denial") and raises.
* THE ACTION. `nvidia_shield.send_intent` takes `intent` (a select selector whose
  options are the loaded intents, `custom_value` on) plus `variables`, resolves
  exactly ONE Shield through t14's resolver (one participant, or no_target /
  unsupported_target / ambiguous_target naming the service), and returns the
  device's output under `intent_response`. Registered with
  `SupportsResponse.OPTIONAL` FIRST, because `async_set_service_schema` reads
  `hass.services.supports_response()` to publish the response flag — the t14
  mechanism, re-verified against the installed HA for t17. The description is
  republished on every entry setup, so an options change (which reloads) refreshes
  the dropdown.
* THE BUTTONS. One button per registered intent (name from the registration, id
  from the intent's stable id so a rename does not orphan the entity), pressing it
  sends the intent with the fields' declared defaults and raises on every failure
  instead of doing nothing. Its extra attributes expose what it will send.

TWO MEASURED REPAIRS IN THE SAME HOOK (media_player.py). Both were latent because
the test harness pre-sets `_manager`:
* the service registries were filled BEFORE the entry's manager was assigned, so a
  real entry registered `None` and `adb_command` would crash with AttributeError
  instead of answering. The manager is now consumed first, and both registries are
  filled after it;
* `async_will_remove_from_hass` never dropped the entity's participation (the
  comment said it did), so a removed or unloaded entry left a stale manager and the
  action answered `adb_unavailable` for an entity that no longer exists instead of
  reporting an unsupported target. Both registries are dropped now, keyed by the
  key computed at add time.

Verify: 794 passed / 4 skipped and 795 passed / 3 skipped (androidtvremote2) —
unchanged counts, so nothing regressed; ruff clean.
2026-10-12 12:43:10 +01:00

2480 lines
106 KiB
Python
Raw Blame History

"""Media player entity for Nvidia Shield.
Phase 2 architecture (docs/MVP_PLAN.md §2): the entry's ShieldConnectionManager
(connection.py) owns both transports — ADB (adb_shell, state source) and the
absorbed remote protocol (androidtvremote2, local push) — plus their StateStore;
this entity is a thin callback-view over it.
State architecture:
- Power ladder: protocol is_on push → ADB wake (exact mWakefulness) → plug off
- Playback state: Jellyfin (polling, slow 10-30s) or ADB media session
- Metadata: Jellyfin attributes, published as separate top-level
``now_playing_*`` attributes — t65 flattened the one nested
``media_dag_now_playing`` object into them, and ``now_playing_via`` names the
tier that produced the reading (``jellyfin`` / ``media_session`` / ``app``)
- Commands: a configured per-command script (t44) → protocol key push → ADB
keyevent. The external androidtv_remote entity tier that used to back this is
gone — t41 removed it with the entity — so a command has exactly one owner.
State ladder (t55) — what ``state`` reports, in order. The vocabulary is
EXACTLY ``{playing, paused, buffering, idle, off, on}``; each step is the first
source that has something to say, and the earlier steps always win:
1. OFF — the configured power entity reads "off", or the protocol's
is_on push is False (the device reporting its own power
state). Both OUTRANK media: a stale Jellyfin session must not
resurrect playback on a device that is off.
2. intent — a play/pause/stop this entity just sent (optimistic UI until
a slow Jellyfin poll confirms it; self-heal in 10 s).
3. Jellyfin — STATE_PLAYING / STATE_PAUSED of the configured entity.
4. session — the ADB media session's PlaybackState, including BUFFERING
(Android state 6, inferred from the dump's line shape rather
than observed on hardware). State 3 → playing, 2 → paused.
5. IDLE — ADB says the device is asleep (standby), OR the device is
powered on (protocol is_on True / ADB awake / the plug is on)
and NOTHING is playing. "Powered on, app open, nothing
playing" is IDLE for exactly this reason.
6. ON — NOTHING reported a POWER OR PLAYBACK FACT — not "no data" (t58
UNIT 0, the t59 F2 ruling, which this wording follows). ON is
the "we cannot know" state and the only situation it may
describe, so every source that ANSWERS — even to say "not
playing" — takes the ladder to IDLE at worst, never here:
* a configured Jellyfin entity in ANY state, including idle /
off / standby / unavailable (and it reports "not playing"
without ever masking a live media session, because the
playing/paused tiers above still win);
* a live media session that carries no playback flag, i.e. the
app publishes a session but is not playing, paused or
buffering;
* a bare foreground app — the protocol's current-app push or
the ADB mResumedActivity parse answered;
* a configured power entity, whatever it currently says;
* protocol is_on / ADB awake, plugged or not.
ON survives for an entry where NONE of those exists: no
transport data, no power entity, no Jellyfin entity, no session,
no foreground app. It must never mask a playing/paused/buffering
source — the rule that fixes the live "On overrides my playing
states" report.
Intent tracking bridges the gap between instant commands and slow Jellyfin polling:
1. User presses pause → intent recorded → UI shows paused immediately
2. Command sent over the serving transport → Shield pauses on screen
3. 10-30s later Jellyfin confirms paused → intent cleared
4. If Jellyfin doesn't confirm in 30s → retry once on the serving
transport (protocol/ADB stamped on the intent) → surrender to truth
"""
import asyncio
import logging
import re
import shlex
import time
import voluptuous as vol
from homeassistant.components.media_player import (
BrowseMedia,
MediaClass,
MediaPlayerDeviceClass,
MediaPlayerEntity,
MediaPlayerEntityFeature,
MediaPlayerState,
MediaType,
)
from homeassistant.config_entries import ConfigEntry
from homeassistant.const import (
ATTR_DEVICE_ID,
ATTR_ENTITY_ID,
STATE_OFF,
STATE_ON,
STATE_PAUSED,
STATE_PLAYING,
)
from homeassistant.core import CALLBACK_TYPE, Event, HomeAssistant, callback
from homeassistant.exceptions import HomeAssistantError, ServiceValidationError
from homeassistant.helpers import config_validation as cv
from homeassistant.helpers import entity_registry as er
from homeassistant.helpers.entity import DeviceInfo
from homeassistant.helpers.entity_platform import AddEntitiesCallback
from homeassistant.helpers.event import async_call_later, async_track_state_change_event
from .connection import ShieldConnectionManager
from .const import (
ADB_COMMAND_RESPONSE_KEY,
ADB_COMMAND_TARGET_DOMAIN,
ATTR_MEDIA_DAG_JELLYFIN_ENTITY,
ATTR_MEDIA_DAG_RECEIVER_ENTITY,
ATTR_MEDIA_DAG_RECEIVER_INPUT,
ATTR_MEDIA_DAG_ROLE,
ATTR_MEDIA_DAG_RUNNING_APPS,
CHANNEL_DIGIT_DELAY,
CONF_ADB_COMMAND_ENABLED,
CONF_ADB_STORE_APP_INFO,
CONF_APP_ICON_MAP,
CONF_APP_NAME_MAP,
CONF_CHANNEL_DIGIT_DELAY,
CONF_CHANNEL_SEND_ENTER,
CONF_JELLYFIN_ENTITY,
CONF_POWER_ENTITY,
CONF_RECEIVER_ENTITY,
CONF_RECEIVER_INPUT,
CONF_REGISTERED_INTENTS,
DEFAULT_APP_DIRECTORY,
DOMAIN,
INTENT_FIELD_LIMIT,
INTENT_FIELD_TYPES,
INTENT_REGISTRATION_LIMIT,
INTENT_RESPONSE_KEY,
INTENT_SERVICE_TARGET,
INTENT_TYPE_FLAGS,
PROTOCOL_MEDIA_KEYS,
PROTOCOL_REMOTE_KEYS,
SCRIPT_VAR_APP_NAME,
SCRIPT_VAR_LEVEL,
SCRIPT_VAR_MUTED,
SERVICE_ADB_COMMAND,
SERVICE_SEND_INTENT,
TIVIMATE_PACKAGE,
command_scripts,
)
from .ha_adb_common import (
PlaybackIntent,
resolve_package_name,
running_apps_from_tasks,
)
from .jellyfin import fetch_session_media_info
from .power import discover_power_siblings
_LOGGER = logging.getLogger(__name__)
INTENT_TIMEOUT = 10 # seconds before self-heal fires
MAX_RETRIES = 1
# Map service names to the MediaPlayerState we expect after the command
SERVICE_TO_STATE = {
"media_pause": MediaPlayerState.PAUSED,
"media_play": MediaPlayerState.PLAYING,
"media_stop": MediaPlayerState.IDLE,
}
#: t61: the domain a receiver must be in for playback to ENSURE it is on. A
#: receiver in any other domain (an AVR media_player) keeps its own semantics —
#: input selection and attribute enrichment — and is never switched here.
RECEIVER_SWITCH_DOMAIN = "switch"
#: t63: the browse root's id and type — the FIX for the live report "Browse media
#: seems to spin and never finish loading".
#:
#: The id must be a real STRING. HA core never serves a node without one: 43
#: ``BrowseMedia`` constructions across the core media_player platforms all pass a
#: string (a literal or module constant — arcam_fmj's "root", "apps",
#: ``BROWSE_ROOT``, ``TUNER_PRESETS_ROOT`` — or "" for a pure container); zero
#: pass ``None``. The media-browser frontend keys the node it is loading on that
#: id, so ``media_content_id=None`` left the dialog re-requesting the same node for
#: ever. "root" is arcam_fmj's own browse-root id, and every requested id — this
#: one, ``None``, or anything a stale frontend asks for — answers the same node, so
#: a repeat request is idempotent rather than a loop.
BROWSE_ROOT_ID = "root"
#: The root's content type, and deliberately NOT ``MediaType.APPS``: core pairs
#: that type (with an "apps" id) with ``children=[…]`` — a folder OF apps — and this
#: node has no children at all, so the claim invites the frontend to treat an empty
#: node as an unloaded collection. No ``MediaType`` member means "a directory with
#: nothing in it", so the node carries the class it already declares, which is also
#: exactly what ``can_expand=False`` and ``children=[]`` say.
BROWSE_ROOT_TYPE = str(MediaClass.DIRECTORY)
#: t65: the now-playing surface is FLATTENED into separate top-level attributes.
#:
#: The user reads attributes as YAML: "These could do with being separate attributes
#: rather than an object in one?" — the nested ``media_dag_now_playing`` object is
#: gone, and every field it carried is published on its own, prefixed so it stays
#: readable beside the entity's other attributes:
#:
#: now_playing_via: media_session
#: now_playing_state: playing
#: now_playing_title: Sky News
#: now_playing_artist: ...
#:
#: Two rules hold the surface together:
#:
#: * **No None.** HA renders a ``None`` attribute as ``attribute: null`` in the
#: template editor, so an unknown field is OMITTED rather than published — a
#: reading carries only what the tier actually answered.
#: * ``now_playing_via`` names the TIER that produced the reading (``jellyfin``,
#: ``media_session`` or ``app``). It is deliberately NOT ``source``:
#: ``source``/``source_list`` already mean "the selected app input" on a
#: media_player, and a tier key called ``source`` is what made the reading look
#: like media metadata from somewhere else.
NOW_PLAYING_PREFIX = "now_playing_"
#: The tier indicator's attribute name.
ATTR_NOW_PLAYING_VIA = f"{NOW_PLAYING_PREFIX}via"
#: Every field the three tiers can put in a reading (t55/t65). A reading's own key
#: becomes ``NOW_PLAYING_PREFIX + key`` on the entity, except ``via``.
NOW_PLAYING_READING_KEYS = (
"via",
"state",
"title",
"media_type",
"artist",
"album",
"series",
"season",
"episode",
"duration",
"position",
"position_updated_at",
"thumbnail",
"media_info",
)
#: The state values a now-playing ROW may carry, and the whole documented set
#: (t17/O2). A reading comes from a tier that answered, and a tier answers in one
#: of these four: ``playing``/``paused``/``buffering`` from a live session or
#: Jellyfin, ``idle`` for a source that reported "nothing is playing" (including
#: the foreground tier's remembered-playback bridge, which is why the ROW's state
#: is the LADDER's answer and not the tier's own label).
#:
#: Anything else is deliberately NOT publishable. ``off`` means the device is off
#: (a stale session must not put a title beside it), ``on`` means nothing anywhere
#: reported a power or playback fact — so there is no reading to describe — and
#: ``standby`` is deprecated and never leaves the ladder. The gate used to be
#: "not off", which published whatever the entity state said; the README documents
#: four values, so the code now publishes exactly those four and a test walks
#: EVERY ``MediaPlayerState`` member against the README to keep the two in step.
NOW_PLAYING_STATE_VALUES = ("playing", "paused", "buffering", "idle")
def now_playing_attribute_names() -> frozenset[str]:
"""The flat now-playing attribute names — the whole published surface (t65)."""
return frozenset(
ATTR_NOW_PLAYING_VIA if key == "via" else f"{NOW_PLAYING_PREFIX}{key}"
for key in NOW_PLAYING_READING_KEYS
)
def flatten_now_playing(now_playing: dict | None) -> dict:
"""One tier reading -> separate TOP-LEVEL attributes (t65).
Unknown fields are dropped, never published as ``None``: the complaint is
readability in YAML and templates, and a ``now_playing_title: null`` row is
exactly the noise this removes. Empty strings go the same way; ``0`` and
``False`` are real values and stay.
"""
if not now_playing:
return {}
flat: dict = {}
for key, value in now_playing.items():
if value is None or value == "":
continue
name = ATTR_NOW_PLAYING_VIA if key == "via" else f"{NOW_PLAYING_PREFIX}{key}"
flat[name] = value
return flat
_BASE_FEATURES = (
MediaPlayerEntityFeature.TURN_ON
| MediaPlayerEntityFeature.TURN_OFF
| MediaPlayerEntityFeature.VOLUME_STEP
| MediaPlayerEntityFeature.VOLUME_MUTE
| MediaPlayerEntityFeature.PLAY_MEDIA
| MediaPlayerEntityFeature.BROWSE_MEDIA
)
_PLAYBACK_FEATURES = (
MediaPlayerEntityFeature.PLAY
| MediaPlayerEntityFeature.PAUSE
| MediaPlayerEntityFeature.STOP
| MediaPlayerEntityFeature.NEXT_TRACK
| MediaPlayerEntityFeature.PREVIOUS_TRACK
)
async def async_call_script(
hass: HomeAssistant, script: str, action: str, variables: dict | None = None
) -> None:
"""Call a configured script with variables, surfacing failures (t44/t47).
``blocking=True`` so a script that fails surfaces HERE: a command that cannot
run must be a visible, translated error rather than a silent no-op. Module-level
so the media player and the remote entity share one implementation.
"""
data: dict = {"entity_id": script}
if variables:
data["variables"] = variables
try:
await hass.services.async_call("script", "turn_on", data, blocking=True)
except Exception as err: # noqa: BLE001 - re-raised as a user-facing error
_LOGGER.error("the script for %s (%s) failed: %s", action, script, err)
raise ServiceValidationError(
translation_domain=DOMAIN,
translation_key="command_script_failed",
translation_placeholders={
"action": action,
"script": script,
"error": str(err),
},
) from err
async def async_run_command_script(
hass: HomeAssistant, options: dict, command: str, variables: dict | None = None
) -> bool:
"""Run the script configured for ``command``; True when one handled it (t44)."""
script = command_scripts(options).get(command)
if not script:
return False
await async_call_script(hass, script, command, variables)
return True
async def async_setup_entry(
hass: HomeAssistant,
entry: ConfigEntry,
async_add_entities: AddEntitiesCallback,
) -> None:
async_add_entities([NvidiaShieldMediaPlayer(hass, entry)])
# P5-1: one-time legacy unique_id migration (t20 F3 closure)
hass.async_create_task(_migrate_legacy_unique_id(hass, entry))
async def _migrate_legacy_unique_id(hass, entry) -> None:
"""Migrate legacy androidtv-entity-id unique_ids once (t20 F3).
Legacy entries carry the androidtv entity id as unique_id; the one-time
migration moves it to the protocol MAC when the transport can resolve
it, else to the config-entry id. After the single update_entry the
legacy pattern no longer matches, so this never runs twice for an
entry. No behavior change: the entry's data/options are untouched.
"""
# t41: the entity path is gone, so the SHAPE of the stale id is the marker.
# Legacy entries (pre-t29 G2) carry the androidtv entity id as unique_id;
# every other shape (a MAC, the config-entry id, a yaml: seed id) is left
# exactly as it is.
legacy = entry.unique_id or ""
if not legacy.startswith("media_player."):
return
manager = getattr(entry, "runtime_data", None)
new_id = None
if manager is not None:
info = await manager.async_protocol_device_info()
if info is not None:
_name, new_id = info
if not new_id:
new_id = entry.entry_id
# t26 F4: another entry may already own the target MAC — the collision
# pre-check falls back to the config-entry id instead of re-binding the
# unique_id to a MAC that could collide with a real second instance.
other_entries = getattr(
getattr(hass, "config_entries", None), "entries", []
) or []
if any(
getattr(other, "unique_id", None) == new_id
for other in other_entries
if getattr(other, "entry_id", None) != entry.entry_id
):
_LOGGER.warning(
"P5-1: unique_id migration target %r already in use — falling "
"back to the config-entry id",
new_id,
)
new_id = entry.entry_id
hass.config_entries.async_update_entry(entry, unique_id=new_id)
_LOGGER.info("P5-1: legacy unique_id %r migrated to %r", legacy, new_id)
def entity_available(manager: ShieldConnectionManager | None) -> bool:
"""Is ANY usable transport healthy for this entry? (t40 live install)
The single ladder behind ``media_player.available``, ``remote.available``
and the diagnostics payload, so the three cannot disagree:
* the protocol transport is wired and has not reported the device
unreachable — it serves power/app/volume even when ADB is down;
* or ADB is connected (live state data);
* or fresh wake data exists (the poller has spoken at least once);
* or the manager is passive (no ADB configured at all): nothing to
transport is not a broken transport.
Unavailable only when a CONFIGURED transport is actively down and no usable
data exists. The t5-F2 rule ("an ADB manager that is down means unreliable
state") took the whole entity down while a healthy paired protocol transport
was still serving commands — the reported defect.
"""
if not isinstance(manager, ShieldConnectionManager):
return True
if manager.protocol_active and manager.is_available is not False:
return True
if manager.connected:
return True
if manager.awake is not None:
return True
return not manager.available
def resolve_app_name(
package: str | None,
app_name_map,
app_label,
curated=None,
) -> str | None:
"""Resolve a package id to a friendly name (t40; curated tier t66).
The single chain behind ``media_player.app_name`` and the Current App
sensor, delegating to ``ha_adb_common.app_label.resolve_package_name`` so the
discovery table and the options editor cannot drift from it:
1. the user's explicit apps map (``CONF_APP_NAME_MAP``);
2. the cached device label (``manager.app_label`` — a cache miss enqueues the
on-demand fetch and falls through);
3. the curated table (``DEFAULT_APP_DIRECTORY``) — the tier that names apps on
a Shield whose ``pm dump`` exposes no label at all;
4. the raw package text — a bare or unknown package falls back to itself,
never to None, and it is shown ONCE (no ``pkg=pkg`` anywhere).
"""
return resolve_package_name(
package,
user_map=app_name_map,
# the callable keeps the device tier LAZY: the user's map answers first
device_label=app_label,
curated=DEFAULT_APP_DIRECTORY if curated is None else curated,
)
def normalize_app_directory(directory) -> dict[str, str]:
"""The t51 rule for an apps table: strip the edges, drop blanks, keep order.
ONE implementation for every consumer (the media player's source list, the
remote's activity list, the reverse lookup), so display and match key stay one
string: an entry like ``com.x= TiviMate `` shows as "TiviMate" AND resolves as
"TiviMate". An entry whose name — or whose package — is blank is dropped, so no
surface offers a child with no package behind it or a name no launch can reach.
Two packages normalizing to the same name are BOTH KEPT (each stays reachable by
its own id) and the FIRST in map order wins the name (t53).
"""
normalized: dict[str, str] = {}
for package, name in (directory or {}).items():
key = str(package).strip()
label = str(name).strip()
if not key or not label:
continue
normalized[key] = label
return normalized
def app_directory(options) -> dict[str, str]:
"""Launchable apps for an entry: the user's map, else the curated default (t61).
ONE source for the source list and the reverse lookup, so the dropdown can
never offer a name the launch path cannot resolve (``_app_directory``, and now
the remote's activity list, both read this).
"""
return normalize_app_directory(
(options or {}).get(CONF_APP_NAME_MAP) or DEFAULT_APP_DIRECTORY
)
def distinct_app_names(names) -> list[str]:
"""Each name ONCE, compared case-insensitively, keeping the first spelling (t53).
``Dup``/``dup`` would otherwise show two rows while the case-insensitive
reverse lookup resolves both to the first entry — one row can only launch the
app it shows. The shadowed package is not lost: it stays reachable by id.
"""
seen: set[str] = set()
offered: list[str] = []
for name in names:
text = str(name)
folded = text.casefold()
if not text or folded in seen:
continue
seen.add(folded)
offered.append(text)
return offered
def activity_names(options, discovered=()) -> list[str]:
"""The remote entity's ACTIVITY list: friendly names, stable order (t15).
Core ``androidtv_remote`` builds its list from a user-maintained app map
because ``AndroidTVRemote`` exposes NO app-list API (measured on the installed
library, not assumed). Ours is the same shape of source plus what ADB discovery
actually found on THIS device:
1. the entry's app directory (the user's map, else the curated table) in map
order — the same names the media player's source list offers;
2. apps discovery found that no directory row covers, named by the one chain
(user map → device label → curated → id).
A discovered app NOTHING can name is skipped rather than offered as its own
package id (the ``pkg=pkg`` noise this contract forbids); it stays launchable by
id through ``remote.turn_on(activity=...)``. Nothing is invented here: an empty
directory with no discovery yields an empty list, and the protocol's pairing
state cannot add an entry.
"""
directory = app_directory(options)
names = list(directory.values())
covered = set(directory)
for row in discovered or ():
package = str(row.get("package") or "").strip()
if not package or package in covered:
continue
covered.add(package)
label = str(row.get("name") or "").strip()
if not label or label == package:
continue
names.append(label)
return distinct_app_names(names)
class NvidiaShieldMediaPlayer(MediaPlayerEntity):
_attr_device_class = MediaPlayerDeviceClass.TV
_attr_has_entity_name = True
_attr_name = None
_attr_should_poll = False
# Overridden as a property below: ADB-health aware
def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
self.hass = hass
self._entry = entry
self._attr_unique_id = f"{DOMAIN}_{entry.entry_id}_media_player"
self._unsub_listeners: list = []
# Intent tracking
self._intent: PlaybackIntent | None = None
self._intent_timer_unsub: CALLBACK_TYPE | None = None
# Power monitoring — discovered from power switch entity
self._power_sensors: dict[str, str] = {}
# Jellyfin media stream info (resolution, codec, etc.)
self._media_info: dict | None = None
# ADB-derived state comes from the entry's ShieldConnectionManager
# (connection.py) — this entity is a thin callback-view over its store.
self._manager: ShieldConnectionManager | None = None
self._manager_unsub: CALLBACK_TYPE | None = None
# In-flight channel digit entry (play_media(channel) — §7); a new
# play_media cancels the previous sequence (core task-cancel guard).
self._channel_task = None
# Last channel entered via play_media(channel) — the foreground
# tier's title fallback when an app publishes no session (P3-3a).
self._last_channel: str | None = None
# Entity-owned background tasks (intent retries, media-info fetch);
# cancelled on unload. The manager owns the socket — never touch it
# here directly.
self._entity_tasks: set = set()
@property
def available(self) -> bool:
"""Available while ANY usable transport is healthy (t40 live install).
ADB enabled but unreachable no longer takes the entity down: a paired,
available protocol transport still serves power/app/volume. The ladder
is shared with the remote and diagnostics (``entity_available``).
"""
return entity_available(getattr(self._entry, "runtime_data", None))
@property
def _jellyfin_entity(self) -> str | None:
return self._entry.options.get(CONF_JELLYFIN_ENTITY) or None
@property
def _receiver_entity(self) -> str | None:
return self._entry.options.get(CONF_RECEIVER_ENTITY) or None
@property
def _receiver_input(self) -> str | None:
return self._entry.options.get(CONF_RECEIVER_INPUT) or None
@property
def device_info(self) -> DeviceInfo:
# G10 (t30): when the protocol transport is live and captured, the
# registry card carries the protocol-pushed identity (name from the
# device itself, manufacturer 'Google' per the audit ruling); the
# pre-capture shape stays the entry-title fallback.
captured = (
self._manager.protocol_device_data if self._manager is not None else None
)
if captured:
name, manufacturer, model, sw = captured
return DeviceInfo(
identifiers={(DOMAIN, self._entry.entry_id)},
name=name or self._entry.title,
manufacturer=manufacturer,
model=model,
sw_version=sw or None,
)
return DeviceInfo(
identifiers={(DOMAIN, self._entry.entry_id)},
name=self._entry.title,
manufacturer="NVIDIA",
model="Shield TV",
)
@property
def _power_entity(self) -> str | None:
return self._entry.options.get(CONF_POWER_ENTITY) or None
@property
def _adb_store_info(self) -> bool:
return self._entry.options.get(CONF_ADB_STORE_APP_INFO, True)
async def async_added_to_hass(self) -> None:
# Consume the entry's ShieldConnectionManager (thin-view pattern) FIRST:
# everything below that publishes this entity as a service target needs
# the manager, and ``__init__`` only knows the entry.
manager = getattr(self._entry, "runtime_data", None)
if manager is not None:
self._manager = manager
self._manager_unsub = manager.register_listener(
self._on_manager_update
)
# F4: the registry key is computed once and stored on the entity, so
# add/remove always agree even when HA core assigns entity_id AFTER the
# first read. t17: the same key now serves both service registries
# (``adb_command`` and ``send_intent``), which is why it is not called
# ``_adb_command_key`` any more.
self._service_target_key = (
getattr(self, "entity_id", None) or self._attr_unique_id
)
# P4-2a: opt-in as an adb_command target (option default off). Registered
# at setup; unregistered at unload (see async_will_remove_from_hass).
if self._entry.options.get(CONF_ADB_COMMAND_ENABLED, False):
_ADB_COMMAND_TARGETS[self._service_target_key] = self._manager
# t17: registered intents are the user's OWN opt-in — nothing runs unless
# they registered one — so this entity participates in ``send_intent``
# whenever it exists. An entry whose ADB is off still resolves as a
# target and then says so honestly (``intents_need_adb``), which is a
# better answer than "that entity is not a target".
_INTENT_TARGETS[self._service_target_key] = self._manager
# Discover power sensor siblings from the power switch
if self._power_entity:
self._power_sensors = discover_power_siblings(self.hass, self._power_entity)
entities = [
entity_id
for entity_id in (self._jellyfin_entity, self._power_entity)
if entity_id
]
self._unsub_listeners.append(
async_track_state_change_event(
self.hass, entities, self._on_source_change
)
)
async def async_will_remove_from_hass(self) -> None:
for unsub in self._unsub_listeners:
unsub()
self._unsub_listeners.clear()
self._clear_intent()
if self._manager_unsub:
self._manager_unsub()
self._manager_unsub = None
# Cancel in-flight entity tasks so they cannot outlive the entity.
for task in self._entity_tasks:
task.cancel()
self._entity_tasks.clear()
# P4-2a/t29 G8: drop this entity's service participation (same key as add,
# NEVER the current entity_id — HA may have changed it). The services
# themselves stay registered (always-on setup).
#
# t17 FIX: this drop was missing entirely, so a removed or unloaded entry
# kept a STALE manager in the registry and ``adb_command`` would answer
# ``adb_unavailable`` (or crash) for an entity that no longer exists
# instead of reporting an unsupported target. Both registries are
# dropped here because both are filled in async_added_to_hass.
key = getattr(self, "_service_target_key", None)
if key:
_ADB_COMMAND_TARGETS.pop(key, None)
_INTENT_TARGETS.pop(key, None)
# ── Intent management ──
def _set_intent(self, service: str, target: MediaPlayerState) -> None:
"""Record a new playback intent. Replaces any existing intent."""
# Cancel existing timer
if self._intent_timer_unsub:
self._intent_timer_unsub()
# Capture current Jellyfin state before the intent
jf = self._read(self._jellyfin_entity)
prior = jf.state if jf else None
self._intent = PlaybackIntent.create(
target_state=target.value,
command=service,
prior_state=prior,
)
# Schedule self-heal timeout
self._intent_timer_unsub = async_call_later(
self.hass, INTENT_TIMEOUT, self._on_intent_timeout
)
_LOGGER.debug("Intent set: %s → %s (prior JF: %s)", service, target, prior)
def _clear_intent(self) -> None:
"""Clear the pending intent and its timer."""
if self._intent_timer_unsub:
self._intent_timer_unsub()
self._intent_timer_unsub = None
self._intent = None
@callback
def _on_intent_timeout(self, _now) -> None:
"""Self-heal: intent wasn't confirmed by Jellyfin in time."""
intent = self._intent
if intent is None:
return
jf = self._read(self._jellyfin_entity)
jf_state = jf.state if jf else None
# Check if Jellyfin caught up during the timeout window
if jf_state == intent.target_state:
_LOGGER.debug("Intent %s confirmed at timeout check", intent.command)
self._clear_intent()
self.async_write_ha_state()
return
# Retry once
if intent.retry_count < MAX_RETRIES:
intent.retry_count += 1
intent.created_at = time.monotonic()
_LOGGER.warning(
"Intent %s not confirmed (JF=%s, want=%s), retrying (attempt %d)",
intent.command, jf_state, intent.target_state, intent.retry_count,
)
if (
intent.via_protocol
and intent.protocol_key
and self._manager is not None
):
# The command was served by the protocol key push — retry there.
self._track_task(
self._manager.send_protocol_key(intent.protocol_key)
)
elif (
intent.via_adb
and intent.adb_command
and self._manager is not None
and self._manager.connected
):
# The command was originally served by ADB — retry over ADB.
self._track_task(
self._manager.send_media_command(intent.adb_command)
)
else:
# t41: neither of OUR transports served this command (both were
# down when it was sent), so there is nothing to re-send. Retrying
# by delegating to another integration is exactly what this change
# removes — surrender to the truth instead.
_LOGGER.warning(
"Intent %s had no serving transport to retry — falling back "
"to truth",
intent.command,
)
self._clear_intent()
self.async_write_ha_state()
return
self._intent_timer_unsub = async_call_later(
self.hass, INTENT_TIMEOUT, self._on_intent_timeout
)
return
# Exhausted retries — surrender to Jellyfin truth
_LOGGER.error(
"Intent %s failed after %d retries (JF=%s), falling back to truth",
intent.command, MAX_RETRIES, jf_state,
)
self._clear_intent()
self.async_write_ha_state()
# ── State change listener ──
@callback
def _on_source_change(self, event: Event) -> None:
"""React to state changes in Jellyfin or the power switch."""
entity_id = event.data.get("entity_id")
new_state_obj = event.data.get("new_state")
# Power off clears any intent — device is off, intent is moot
if (
entity_id == self._power_entity
and new_state_obj
and not self._is_power_on()
and self._intent
):
_LOGGER.debug("Intent cleared: device powered off")
self._clear_intent()
# Jellyfin state change — check for intent confirmation and fetch media info
if entity_id == self._jellyfin_entity and new_state_obj:
new_jf = new_state_obj.state
# Intent confirmation
if self._intent:
intent = self._intent
if new_jf == intent.target_state:
_LOGGER.debug("Intent %s confirmed by Jellyfin", intent.command)
self._clear_intent()
elif new_jf not in (
intent.prior_state, "unavailable", "unknown", None
):
_LOGGER.debug(
"Intent %s overridden by external action (JF=%s)",
intent.command, new_jf,
)
self._clear_intent()
# Fetch media stream info when playing
if new_jf in (STATE_PLAYING, STATE_PAUSED):
entity_picture = new_state_obj.attributes.get("entity_picture", "")
self._track_task(
self._fetch_media_info(entity_picture)
)
else:
self._media_info = None
# Always re-evaluate state
self.async_write_ha_state()
# ── Helpers ──
def _read(self, entity_id: str | None):
if not entity_id:
return None
return self.hass.states.get(entity_id)
@callback
def _on_manager_update(self) -> None:
"""Connection manager's store changed — re-evaluate our state."""
self.async_write_ha_state()
def _track_task(self, coro) -> None:
"""Dispatch an entity background task; cancelled on unload.
Entity-owned tasks (intent retries, media-info fetch) must never go
through a bare hass.async_create_task: they would survive removal
(reviewer finding F2). The connection manager owns its own tasks and
the socket — nothing here touches it directly.
"""
task = self.hass.async_create_task(coro)
self._entity_tasks.add(task)
task.add_done_callback(self._entity_tasks.discard)
return task
async def _fetch_media_info(self, entity_picture: str) -> None:
"""Read stream info from the HA Jellyfin integration's coordinator."""
info = await fetch_session_media_info(
self.hass, self._jellyfin_entity, self._entry.title
)
if info != self._media_info:
self._media_info = info
self.async_write_ha_state()
def _jf_active(self) -> bool:
"""Is Jellyfin reporting active playback?"""
jf = self._read(self._jellyfin_entity)
if jf and jf.state in (STATE_PLAYING, STATE_PAUSED):
return True
# If we have an active intent for play/pause, media is conceptually active
return bool(
self._intent and self._intent.target_state in (STATE_PLAYING, STATE_PAUSED)
)
# ── State ──
def _is_power_on(self) -> bool | None:
"""Determine if the Shield is powered on.
Priority: ADB wake state > power entity plug off > unknown.
ADB is the authority — it knows if the device is awake or asleep.
The plug being "on" just means the outlet has power (standby).
"""
# 1. Protocol is_on push — fastest truth when the transport is live
protocol_is_on = self._manager.is_on if self._manager else None
if protocol_is_on is not None:
return protocol_is_on
# 2. ADB wake state — exact mWakefulness parse
adb_awake = self._manager.awake if self._manager else None
if adb_awake is not None:
return adb_awake
# 3. Power entity — only trust "off" (plug pulled = definitely off)
if self._power_entity:
power_state = self._read(self._power_entity)
if power_state and power_state.state == "off":
return False
return None
@staticmethod
def _session_state(info) -> MediaPlayerState | None:
"""The MediaPlayerState a media session is reporting, or None (t55).
One place decides what a session means, so ``state`` and
``supported_features`` cannot disagree about it. Buffering is checked
FIRST: a session refilling its buffer is mid-playback, and state 6 is
the stock-Android buffering value (an inference from the dump's line
shape — no captured fixture here carries it), so BUFFERING is the
more informative of the two if a firmware ever set 6 together with 3.
"""
if info is None:
return None
if info.buffering:
return MediaPlayerState.BUFFERING
if info.playing:
return MediaPlayerState.PLAYING
if info.paused:
return MediaPlayerState.PAUSED
return None
@property
def state(self) -> MediaPlayerState:
"""The playback state — the ladder is documented in the module docstring.
Exactly ``{playing, paused, buffering, idle, off}`` are reported for a
device we have data about; ``ON`` is reserved for the case where NO
source reported a POWER OR PLAYBACK FACT — not merely "no transport is
connected" (t58 UNIT 0, the t59 F2 ruling). A source that exists and
answers "not playing" (Jellyfin idle/off/standby/unavailable, a live
media session with no playback flag, a bare foreground app) HAS reported,
so the ladder stops at IDLE, never ON. ON must also never mask a
playing/paused/buffering source. A powered-on Shield with an app open but
nothing playing reads IDLE, not ON (t55 — the live defect users read as
"On overrides my playing states").
"""
# A source that reported a power or playback fact, even a negative one.
# ON is the "we cannot know" state, so it survives only when nothing at
# all answered — this flag IS the distinction the ruling turns on.
reported = False
# 1. Explicit OFF. The plug being off is definitive; the protocol's
# is_on push is the device reporting its own power state. Either
# one OUTRANKS every media source — a stale Jellyfin session must
# never resurrect playback on a device that is off.
if self._power_entity:
# a CONFIGURED source counts as reporting whatever it says now,
# which is why an unavailable plug yields IDLE rather than ON
reported = True
power_state = self._read(self._power_entity)
if power_state and power_state.state == "off":
return MediaPlayerState.OFF
manager = self._manager
if manager is not None and manager.is_on is False:
return MediaPlayerState.OFF
# 2. A user-commanded intent is the freshest media truth we have.
if self._intent is not None:
return MediaPlayerState(self._intent.target_state)
# 3. Jellyfin (slow, but authoritative for its own sessions). A
# configured entity reports in EVERY state it can be in: playing and
# paused are truth, and idle / off / standby / unavailable / missing
# all mean "its session is not playing" — reported, just not
# playable, so the ladder continues WITHOUT an early return (a silent
# Jellyfin must never mask a live media session) and IDLE is where it
# ends (t58 UNIT 0).
if self._jellyfin_entity:
reported = True
jf = self._read(self._jellyfin_entity)
if jf:
if jf.state == STATE_PLAYING:
return MediaPlayerState.PLAYING
if jf.state == STATE_PAUSED:
return MediaPlayerState.PAUSED
# 4. Live media session (non-Jellyfin apps), buffering included. The
# session EXISTING is a report even when it carries no playback flag
# (an idle or paused app still publishes one): that is IDLE, and it is
# the t58 UNIT 0 case that used to fall through to ON.
session = manager.best_session(self.app_id) if manager is not None else None
if session is not None:
reported = True
session_state = self._session_state(session)
if session_state is not None:
return session_state
# 5. ADB standby: powered but asleep — still data (the device
# answered), so IDLE, never ON. media_player.STANDBY is deprecated
# (2025-07), so IDLE is the compliant mapping (t22 audit).
if manager is not None and manager.awake is False:
return MediaPlayerState.IDLE
# 6. The device is on (protocol is_on True, ADB awake, or the power
# plug is on — every one of those is a source that reported
# something). An open app or an awake device reads IDLE, not ON.
# A bare foreground app is a report in its own right: the protocol's
# current-app push or the ADB mResumedActivity parse answered.
if self._is_power_on() is not None:
reported = True
if manager is not None and manager.awake is not None:
reported = True
# EITHER transport's foreground answer counts: the protocol's
# current_app push and the ADB mResumedActivity parse are both
# "something reported", even when neither is playing anything.
if manager is not None and manager.foreground_app is not None:
reported = True
# 7. Nothing anywhere reported a power or playback fact. ON is the "we
# cannot know" state, and the only situation it is allowed to
# describe.
return MediaPlayerState.IDLE if reported else MediaPlayerState.ON
@property
def supported_features(self) -> MediaPlayerEntityFeature:
if self._jf_active():
features = _BASE_FEATURES | _PLAYBACK_FEATURES
else:
# A media session's playback controls include the BUFFERING case:
# pausing/resuming a buffering stream must be offered exactly like
# PLAYING (t55).
session = (
self._manager.best_session(self.app_id) if self._manager else None
)
if session is not None and self._session_state(session) is not None:
features = _BASE_FEATURES | _PLAYBACK_FEATURES
else:
features = _BASE_FEATURES
# t44/t47: a command that exists ONLY as a script still has to be
# reachable, and the feature flag is what makes HA offer it. volume_set has
# no native path at all; select_source appears when EITHER a script is
# configured OR there is a source list to offer (t47 gave it a native path).
if self._script_for("volume_set"):
features |= MediaPlayerEntityFeature.VOLUME_SET
if self._script_for("select_source") or self.source_list:
features |= MediaPlayerEntityFeature.SELECT_SOURCE
return features
# ── Metadata from Jellyfin ──
def _jf_attr(self, key: str):
jf = self._read(self._jellyfin_entity)
return jf.attributes.get(key) if jf else None
@property
def app_id(self):
"""The raw foreground package from the manager's store (t41).
Both native transports stamp it: the protocol current-app push and the
ADB mResumedActivity parse. None until one of them has reported.
"""
return self._manager.current_app if self._manager is not None else None
@property
def _app_name_map(self) -> dict:
"""The user's apps name/icon map (P4-1 options editor)."""
return self._entry.options.get(CONF_APP_NAME_MAP) or {}
@property
def _app_directory(self) -> dict:
"""Launchable apps: the user's map, else the curated default (P4-1; t15).
The rule lives in the module-level :func:`app_directory` (t51: strip the
edges, drop blanks, keep map order, first name wins case-insensitively, the
shadowed package still reachable by id) so the source list, the reverse
lookup AND the remote's activity list cannot disagree about it.
"""
return app_directory(self._entry.options)
@property
def source_list(self) -> list[str]:
"""The apps as friendly names — the dropdown a UMP replacement reads (t47).
Directory order (the user's map order, or the curated list), so rebuilding
the page does not shuffle it. Blanks are already gone and names already
stripped by ``_app_directory`` (t49/t51) — the normalization lives in that
one accessor so the dropdown and the reverse lookup cannot disagree.
Each name is offered ONCE, compared CASE-INSENSITIVELY (t53), keeping the
first spelling the user typed. Exact duplicates were already collapsed, but
``Dup``/``dup`` were not: the dropdown then showed two rows while the
reverse lookup — which is case-insensitive by design (t47) — resolved BOTH
of them to the first entry, so the second row launched the wrong app. One
row per name means a row can only launch the app it shows. The shadowed
package is not lost: ``select_source`` accepts its own package id.
"""
return distinct_app_names(self._app_directory.values())
@property
def source(self) -> str | None:
"""The foreground app's friendly name — the same chain as app_name (t47).
``resolve_app_name``: the user's map, then the cached device-manifest label,
then the raw package. Same answer as the Current App sensor, so a
universal-media-player replacement cannot see two different truths.
"""
return self.app_name
@property
def app_name(self):
"""P5-1 resolution order — explicit override first:
1. CONF_APP_NAME_MAP (the user's explicit override)
2. device manifest label (`pm dump`, cached ≥24 h, resolved on
demand — a miss enqueues the fetch and falls through)
3. raw package (protocol push / ADB foreground parse)
"""
# t40: one implementation, shared with the Current App sensor
# (``resolve_app_name``) — the two can no longer disagree about what
# is on screen.
package = self._manager.foreground_app if self._manager is not None else None
return resolve_app_name(
package,
self._app_name_map,
self._manager.app_label if self._manager is not None else None,
)
@property
def media_content_type(self):
return self._jf_attr("media_content_type") if self._jf_active() else None
@property
def media_title(self):
return self._jf_attr("media_title") if self._jf_active() else None
@property
def media_series_title(self):
return self._jf_attr("media_series_title") if self._jf_active() else None
@property
def media_season(self):
return self._jf_attr("media_season") if self._jf_active() else None
@property
def media_episode(self):
return self._jf_attr("media_episode") if self._jf_active() else None
@property
def media_duration(self):
return self._jf_attr("media_duration") if self._jf_active() else None
@property
def media_position(self):
return self._jf_attr("media_position") if self._jf_active() else None
@property
def media_position_updated_at(self):
return self._jf_attr("media_position_updated_at") if self._jf_active() else None
@property
def media_image_url(self):
"""Jellyfin session picture, else the P5-2 apps-map icon override."""
if self._jf_active():
jf = self._jf_attr("entity_picture")
if jf:
return jf
package = self._manager.foreground_app if self._manager else None
if package:
icon_map = self._entry.options.get(CONF_APP_ICON_MAP, {})
return icon_map.get(package)
return None
@property
def volume_level(self) -> float | None:
"""Protocol volume push readout (C-VOL — level only, no VOLUME_SET)."""
if self._manager is None:
return None
info = self._manager.volume_info
if info is None:
return None
level, volume_max, _muted = info
try:
if volume_max and volume_max > 0:
return level / volume_max
except (TypeError, ValueError):
pass
return None
@property
def is_volume_muted(self) -> bool | None:
"""Real mute state from the protocol push (was unknowable pre-Phase 2)."""
if self._manager is None:
return None
info = self._manager.volume_info
return info[2] if info is not None else None
def _get_now_playing(self) -> dict | None:
if not self._jf_active():
return None
jf = self._read(self._jellyfin_entity)
if not jf:
return None
attrs = jf.attributes
np = {
"state": self.state.value,
"title": attrs.get("media_title"),
"media_type": attrs.get("media_content_type"),
"via": "jellyfin",
}
for src, dst in [("media_series_title", "series"), ("media_season", "season"),
("media_episode", "episode"), ("media_duration", "duration"),
("media_position", "position"),
("media_position_updated_at", "position_updated_at")]:
v = attrs.get(src)
if v is not None:
np[dst] = v
if attrs.get("entity_picture"):
np["thumbnail"] = attrs["entity_picture"]
if self._media_info:
np["media_info"] = self._media_info
return np
def _now_playing(self) -> dict | None:
"""The first tier with something to say (t65).
Order is the ladder's own confidence order (t55): Jellyfin, then the live
ADB media session, then the foreground app. The tier that answers is the
one named in ``now_playing_via``.
"""
for reading in (
self._get_now_playing(),
self._get_adb_now_playing(),
self._get_app_now_playing(),
):
if reading:
return reading
return None
def _session_playback_label(self, info) -> str:
"""``playing``/``buffering``/``paused``/``idle`` for a live session (t55).
BUFFERING is its own label rather than a flavour of playing: the state
entity says so, and the now-playing dict must not contradict it. The
session flags themselves stay independent; this only names the state.
"""
if info.buffering:
return "buffering"
if info.playing:
return "playing"
if info.paused:
return "paused"
return "idle"
def _get_adb_now_playing(self) -> dict | None:
"""Build now-playing from ADB media session (non-Jellyfin apps)."""
info = self._manager.best_session(self.app_id) if self._manager else None
if not info:
return None
if not self._adb_store_info:
# Privacy mode: show that something is playing but not what
if info.playing or info.paused or info.buffering:
return {
"state": self._session_playback_label(info),
"title": self.app_name or self.app_id or "Playing",
"via": "media_session",
}
return None
if not info.title:
return None
np = {
"state": self._session_playback_label(info),
"title": info.title,
"via": "media_session",
}
if info.artist:
np["artist"] = info.artist
if info.album:
np["album"] = info.album
return np
def _get_app_now_playing(self) -> dict | None:
"""Foreground-tier now-playing (P3-3a): an app is open but publishes
no media session (TiviMate, R2). Title = last known state, else the
last channel entered, else the zero-cost audio-playback hint.
The STATE here is ``idle`` or the last-known session's playback state;
the entity-level ladder reports IDLE for this tier (t55), so the two
agree — a bare foreground app is no longer reported as ON.
"""
manager = self._manager
if manager is None:
return None
foreground = manager.foreground_app
if not foreground:
return None
state = "idle"
title = None
info = manager.last_known_session(foreground)
if info is not None and (info.playing or info.paused or info.buffering):
state = self._session_playback_label(info)
# Privacy mode: identity stays the app, never the media title
title = None if not self._adb_store_info else info.title
if title is None and not self._adb_store_info:
# F3: privacy mode first — identity stays the app, so neither the
# channel number nor the media title can leak as the identity.
title = self.app_name or self.app_id or foreground
if title is None and self._last_channel and (
# F1: the channel number belongs to the channel app only — never
# leak it to the launcher or another foreground app.
foreground == TIVIMATE_PACKAGE or foreground in manager.audio_playback
):
title = self._last_channel
if title is None and foreground in manager.audio_playback:
# E hint (zero round-trip cost): audio was recently played
title = "Media recently active"
if title is None:
# Bare foreground app: no now-playing identity, but the device is
# ON — the entity ladder reports IDLE for this (t55).
return None
return {"state": state, "title": title, "via": "app"}
def _get_power_data(self) -> dict | None:
"""Read current values from discovered power sensors."""
if not self._power_sensors:
return None
data = {}
for key, entity_id in self._power_sensors.items():
if key == "switch":
continue
state = self._read(entity_id)
if state and state.state not in ("unavailable", "unknown"):
try:
data[key] = float(state.state)
except (ValueError, TypeError):
data[key] = state.state
return data if data else None
def _get_running_apps(self) -> list[dict] | None:
"""Build a list of running apps from ADB recent tasks + media sessions."""
if not self._manager:
return None
apps = self._manager.running_apps
if not apps:
return None
if not self._adb_store_info:
return None
return running_apps_from_tasks(
apps,
self._manager.active_sessions,
foreground_package=self.app_id,
last_known=self._manager.last_known_map(),
)
# G12 (t30): attributes that change with every poll must not bloat the
# database (entity doc) — dag internals are declared unrecorded.
# t65: the flattened now-playing surface replaces the single nested
# ``media_dag_now_playing`` key, so EVERY name it can publish is declared here
# (``now_playing_attribute_names()``) — otherwise the recorder starts storing a
# fresh row per poll for each of them.
_unrecorded_attributes = frozenset(
{
*now_playing_attribute_names(),
ATTR_MEDIA_DAG_RUNNING_APPS,
ATTR_MEDIA_DAG_RECEIVER_ENTITY,
ATTR_MEDIA_DAG_RECEIVER_INPUT,
ATTR_MEDIA_DAG_ROLE,
}
)
@property
def extra_state_attributes(self) -> dict:
"""Extra state attributes — a PROPERTY, as HA requires (t40 blocker).
``Entity.__async_calculate_state`` merges them with
``attr |= self.extra_state_attributes``; declaring this as a plain
method made every state write raise
``TypeError: 'method' object is not iterable``, so the entity could
never render on a live install.
"""
attrs = {
"app_id": self.app_id,
"app_name": self.app_name,
# t15: which tier produced the app identity ("protocol" push / ADB parse),
# so the newly-reachable push cannot silently outrank the ADB reading the
# user's setup is built on — the same disclosure now_playing_via makes.
"app_source": (
self._manager.foreground_source if self._manager is not None else None
),
ATTR_MEDIA_DAG_ROLE: "source",
}
# t65: the reading is FLATTENED into separate top-level attributes.
# OFF is excluded deliberately: a Jellyfin session that has gone stale
# must not publish a title beside a device that is off ("no stale title
# from a previous app lingering"), and the state already says nothing is
# playing. Every other state publishes whatever the tier answered, and
# nothing it did not (no None rows — see ``flatten_now_playing``).
if self.state != MediaPlayerState.OFF:
state = self.state.value
reading = self._now_playing()
# t17/O2: only the four states a READING can carry are published, so
# a state outside the documented set can never leak into
# ``now_playing_state`` (see NOW_PLAYING_STATE_VALUES). The reading is
# dropped whole, exactly as it is for a device that reads off.
if state not in NOW_PLAYING_STATE_VALUES:
reading = None
if reading:
# The published state is the ENTITY's own state, so a dashboard
# never reads two answers: the tier can briefly serve a
# last-known playback state (t55's TTL bridge) or sit inside an
# intent window, and the state ladder is the authority in both.
reading = {**reading, "state": state}
attrs.update(flatten_now_playing(reading))
if self._receiver_entity:
attrs[ATTR_MEDIA_DAG_RECEIVER_ENTITY] = self._receiver_entity
if self._receiver_input:
attrs[ATTR_MEDIA_DAG_RECEIVER_INPUT] = self._receiver_input
if self._jellyfin_entity:
attrs[ATTR_MEDIA_DAG_JELLYFIN_ENTITY] = self._jellyfin_entity
# Running apps from ADB media sessions
running_apps = self._get_running_apps()
if running_apps:
attrs[ATTR_MEDIA_DAG_RUNNING_APPS] = running_apps
# Power monitoring
if self._power_entity:
attrs["power_switch"] = self._power_entity
power_data = self._get_power_data()
if power_data:
attrs["power_monitoring"] = power_data
# Intent state for debugging
if self._intent:
attrs["_intent"] = self._intent.to_debug_dict()
return attrs
# ── Commands — our own transports only (t41: the external entity is gone) ──
async def _power_key(self, *, send_when_on: bool) -> None:
"""Send the protocol POWER key when the known state disagrees (t41).
Both native transports are ours now, so this no longer delegates to an
androidtv_remote entity: the protocol POWER key is the path we own. An
unknown state sends nothing (no superfluous toggle — the same rule the
remote entity applies), and without the protocol transport there is
nothing to transport the key over.
"""
manager = self._manager
if manager is None or manager.is_on is not send_when_on:
return
await manager.send_protocol_key(PROTOCOL_REMOTE_KEYS["power"])
def _script_for(self, command: str) -> str | None:
"""The script configured to own ``command``, if any (t44)."""
return command_scripts(self._entry.options).get(command)
async def _script_served(self, command: str, variables: dict | None = None) -> bool:
"""True when a configured script handled ``command`` instead of the transports."""
return await async_run_command_script(
self.hass, self._entry.options, command, variables
)
async def _ensure_receiver_on(self) -> None:
"""Turn a SWITCH receiver on before playback — only when it is off (t61).
The user's request, verbatim: "it would be nice if a receiver could just
be a switch, I don't need my volume scripts then because the receiver
portion could just make sure the receiver is on if it's a switch". So a
``switch.*`` receiver is ENSURED ON by the playback entry points
(:meth:`async_turn_on`, :meth:`async_play_media`,
:meth:`async_select_source`) and nothing else happens to it: no volume,
no toggle, no other switch semantics.
Deliberately narrow, in four ways:
* only a ``switch.*`` receiver is touched — a ``media_player.*``
receiver keeps its behaviour exactly;
* only when the switch reports ``off``. An ``on`` switch issues no
service call at all, so this is idempotent — a state write, a poll or
a second entry point in the same action never re-calls it. A state we
cannot read (missing entity, ``unavailable``, ``unknown``) is left
alone rather than guessed at, with a debug line saying so;
* never called from a state read, a poll, a listener or attribute
rendering, so a receiver that is off while the Shield is idle stays
off — this is a playback action, not a synchronisation;
* a service failure (the entity vanished between the read and the call)
is logged, not raised: a receiver that cannot be switched on must not
stop the Shield from playing.
"""
entity_id = self._receiver_entity
if not entity_id or not entity_id.startswith(f"{RECEIVER_SWITCH_DOMAIN}."):
return
state = self._read(entity_id)
if state is None:
_LOGGER.debug(
"receiver %s is not in the state machine — not switching it",
entity_id,
)
return
if state.state != STATE_OFF:
if state.state != STATE_ON:
_LOGGER.debug(
"receiver %s reports %r — not switching it", entity_id, state.state
)
return
try:
await self.hass.services.async_call(
RECEIVER_SWITCH_DOMAIN,
"turn_on",
{"entity_id": entity_id},
blocking=True,
)
except HomeAssistantError as err:
_LOGGER.debug("receiver %s could not be turned on: %s", entity_id, err)
async def async_turn_on(self):
"""Wake the Shield (only when it reports OFF) — or run the turn_on script.
A ``switch.*`` receiver is ensured on first (t61): the receiver is where
the Shield's sound comes out, so a playback entry point that wakes the
Shield wakes it too — and only when it is actually off.
"""
await self._ensure_receiver_on()
if await self._script_served("turn_on"):
return
await self._power_key(send_when_on=False)
async def async_turn_off(self):
"""Sleep the Shield (only when it reports ON) — or run the turn_off script."""
if await self._script_served("turn_off"):
return
await self._power_key(send_when_on=True)
async def async_volume_up(self):
if await self._script_served("volume_up"):
return
await self._remote_key_cmd("volume_up", "volume_up")
async def async_volume_down(self):
if await self._script_served("volume_down"):
return
await self._remote_key_cmd("volume_down", "volume_down")
async def async_mute_volume(self, mute):
"""Mute — via the configured script, else the protocol/ADB key (C-VOL)."""
if await self._script_served("volume_mute", {SCRIPT_VAR_MUTED: mute}):
return
await self._remote_key_cmd("volume_mute", "mute")
async def async_set_volume_level(self, volume):
"""Set absolute volume — reachable only with a script (t44).
There is no native path to replace: the protocol carries UP/DOWN/MUTE keys
only (C-VOL) and ADB has no absolute volume either. Configured, this is the
hook for a device whose volume is owned elsewhere (a speaker switch);
unconfigured it stays the no-op it has always been.
"""
await self._script_served("volume_set", {SCRIPT_VAR_LEVEL: volume})
def _source_package(self, source) -> str | None:
"""The package behind a source name, or a package id passed through (t47).
Both sides are normalized the same way: the query is stripped here and the
names were stripped when the directory was built (t51), so a padded entry
matches its trimmed spelling. Names are compared case-insensitively — which
is why ``source_list`` collapses names that differ only by case (t53), so
that the row it offers resolves back to the same app it displays. When two
packages share a name the first in map order wins, the same one
``source_list`` offers (see ``_app_directory``); the shadowed package stays
reachable by passing its id.
"""
directory = self._app_directory
wanted = str(source or "").strip()
if not wanted:
return None
if wanted in directory:
# an automation may hand us the package directly; that is the id
# this table is keyed by (t61: the browse tree that used to publish
# it is gone, the id itself is unchanged)
return wanted
folded = wanted.casefold()
for package, name in directory.items():
if str(name).casefold() == folded:
return package
return None
async def async_select_source(self, source):
"""Select an app by its friendly name (t47) — script first, else launch it.
A configured ``select_source`` script keeps precedence (t44: selecting a
source can be more than launching an app — an AVR input, a speaker switch).
Without one the name is resolved back to its package through the SAME
directory the source list came from and launched over the shared
``play_media("app", …)`` path, so a universal-media-player replacement gets
the native behaviour. An unknown name is an error, never a silent no-op.
A ``switch.*`` receiver is ensured on first (t61), before the script: a
source selection is the start of playback, and it dispatches internally
so the switch is looked at exactly once per user action.
"""
await self._ensure_receiver_on()
if await self._script_served("select_source", {SCRIPT_VAR_APP_NAME: source}):
return
package = self._source_package(source)
if package is None:
raise ServiceValidationError(
translation_domain=DOMAIN,
translation_key="unknown_source",
translation_placeholders={"source": str(source)},
)
await self._dispatch_play_media(MediaType.APP, package)
async def _remote_key_cmd(self, remote_key: str, adb_key: str) -> None:
"""Simple key command without intent bookkeeping: protocol → ADB keyevent."""
protocol_key = PROTOCOL_REMOTE_KEYS.get(remote_key)
if (
protocol_key
and self._manager is not None
and await self._manager.send_protocol_key(protocol_key)
):
return
if self._manager is not None and await self._manager.send_media_command(adb_key):
return
async def _media_cmd(
self, ha_service: str, adb_command: str, intent_state: MediaPlayerState | None = None
) -> None:
"""Send a media command over the fastest available command path.
Order: protocol key push → ADB keyevent (t41: our own transports only —
the transitional external-entity tier is gone). With neither transport
up the command is a no-op, never a call into another integration.
"""
if intent_state:
self._set_intent(ha_service, intent_state)
self.async_write_ha_state()
# Use ADB media dispatch when ADB is active and Jellyfin isn't playing
jf = self._read(self._jellyfin_entity)
jf_active = jf and jf.state in (STATE_PLAYING, STATE_PAUSED)
# 1. Protocol key push (fast; works whenever the transport is up)
protocol_key = PROTOCOL_MEDIA_KEYS.get(ha_service)
if (
protocol_key
and self._manager is not None
and await self._manager.send_protocol_key(protocol_key)
):
if self._intent is not None:
self._intent.via_protocol = True
self._intent.protocol_key = protocol_key
return
# 2. ADB keyevent (socket-independent; exact same commands as before)
if self._manager and self._manager.connected and not jf_active:
success = await self._manager.send_media_command(adb_command)
if success:
# The ADB path served this command — the self-heal retry must
# also go over ADB, not back to the remote.
if self._intent is not None:
self._intent.via_adb = True
self._intent.adb_command = adb_command
return
async def async_media_play(self):
await self._media_cmd("media_play", "play", MediaPlayerState.PLAYING)
async def async_media_pause(self):
await self._media_cmd("media_pause", "pause", MediaPlayerState.PAUSED)
async def async_media_stop(self):
await self._media_cmd("media_stop", "stop", MediaPlayerState.IDLE)
async def async_media_next_track(self):
await self._media_cmd("media_next_track", "next")
async def async_media_previous_track(self):
await self._media_cmd("media_previous_track", "previous")
async def async_bring_to_foreground(self, package: str) -> bool:
"""Bring a specific app to the foreground via ADB."""
if self._manager is None or not self._manager.connected:
_LOGGER.warning("ADB not available for bring_to_foreground")
return False
return await self._manager.bring_to_foreground(package)
# ── BrowseMedia app directory (P4-2c) ──
async def async_browse_media(self, media_content_type=None, media_content_id=None):
"""The media browser is EMPTY on purpose — and says so unambiguously.
The user's report, verbatim: "Media Browser shows Apps. To me it should
probably be integrated with the home assistant media display, keep
select sources for apps". They are right about the surface: HA's media
browser is for BROWSABLE media, while those rows are SOURCES. They stay
where a source belongs — ``source_list``/``source``, the source
dropdown, ``select_source`` and ``play_media("app", …)`` — and that
offer is complete.
So this returns a valid, standard ``media_player.BrowseMedia`` root with
NO children rather than a second, inconsistent copy of the app list:
``BrowseMedia`` (never ``BrowseMediaSource``, which media_player has not
exported since before t37 D1), the device as the root title, a directory
class, and ``BROWSE_ROOT_ID``/``BROWSE_ROOT_TYPE``. There is no node to
select, so no dead entry can be offered and a click can never reach a row
that cannot launch. An integration with genuinely browsable media would
publish it here; this one has none.
t63 — and the id is a real STRING, which is the fix for the next live
report, "Browse media seems to spin and never finish loading". This
method returns with no awaits, so the hang was in what it handed back:
a null ``media_content_id``. HA core never serves one (see
``BROWSE_ROOT_ID``), because the frontend keys the node it is loading by
that id. Every requested id answers this same node, so a repeat request
is idempotent rather than a loop.
"""
return BrowseMedia(
title=self._entry.title or "NVIDIA Shield",
media_class=MediaClass.DIRECTORY,
media_content_type=BROWSE_ROOT_TYPE,
media_content_id=BROWSE_ROOT_ID,
can_play=False,
can_expand=False,
children=[],
)
# ── play_media (§7): channel digits, app/url launch ──
async def async_play_media(self, media_type: str, media_id: str) -> None:
"""HA's ``play_media`` entry point — ensure the receiver, then dispatch.
The receiver ensure (t61) lives on the PUBLIC path only, so an internal
caller (:meth:`async_select_source`) dispatches without a second look at
the same switch inside one user action.
"""
await self._ensure_receiver_on()
await self._dispatch_play_media(media_type, media_id)
async def _dispatch_play_media(self, media_type: str, media_id: str) -> None:
"""Channel selection by digit number; app/url launches (C-LAUNCH).
Channel path replicates HA core androidtv_remote exactly: digits only,
configurable inter-digit delay (default 0.1 s), no ENTER — and the
padded prior in-flight channel sequence is cancelled first.
TEXT entry (P5-2): play_media("text", "...") — protocol IME send_text
first; the ADB `input text` fallback tier runs only when the
protocol send is unavailable or failed (the Shield may swallow IME
text while its on-screen keyboard is up, RESEARCH_IDEAS §2).
"""
if media_type == "text":
if not media_id:
_LOGGER.warning("play_media(text): empty text ignored")
return
if self._manager is not None and await self._manager.send_text_ime(media_id):
return
if self._manager is not None and await self._manager.send_adb_input_text(media_id):
return
_LOGGER.warning(
"play_media(text): no transport available (protocol down, ADB"
" unavailable) — text not sent"
)
return
if media_type == "channel":
digits = [c for c in media_id if c.isdigit()]
if not digits:
_LOGGER.warning("play_media(channel): no digits in %r", media_id)
return
self._last_channel = "".join(digits)
self._cancel_inflight_channel()
self._channel_task = self._track_task(
self._channel_entry_sequence(digits)
)
return
if media_type in ("app", "url"):
if self._manager is not None and await self._manager.launch_app(media_id):
return
if (
media_type == "app"
and self._manager is not None
and await self._manager.bring_to_foreground(media_id)
):
# Fallback: monkey launch of the bare package (no deep links).
return
_LOGGER.warning(
"play_media(%s): could not launch %s — no available transport",
media_type,
media_id,
)
return
_LOGGER.warning(
"play_media: unsupported media type %r (supported: channel/app/url)"
" — nothing sent",
media_type,
)
def _cancel_inflight_channel(self) -> None:
task = self._channel_task
if task is not None and not task.done():
task.cancel()
self._channel_task = None
async def _channel_entry_sequence(self, digits: list[str]) -> None:
delay = self._entry.options.get(CONF_CHANNEL_DIGIT_DELAY, CHANNEL_DIGIT_DELAY)
send_enter = self._entry.options.get(CONF_CHANNEL_SEND_ENTER, False)
try:
for digit in digits:
# 1. Protocol digit key; 2. ADB keyevent 7..16 (t41: our own
# transports only — an unserved digit is dropped, never handed
# to another integration)
served = False
if self._manager is not None:
served = await self._manager.send_protocol_key(f"KEYCODE_{digit}")
if not served:
served = await self._manager.send_digit_key(digit)
if not served:
_LOGGER.warning(
"channel digit %s not sent — no available transport", digit
)
await asyncio.sleep(delay)
if (
send_enter
and self._manager is not None
and not await self._manager.send_protocol_key("KEYCODE_ENTER")
):
# ENTER fallback chain: protocol key → ADB keyevent 66.
# (No legacy-entity tier: the external androidtv_remote has
# no ENTER service to delegate to.)
await self._manager.send_enter_key()
except asyncio.CancelledError:
raise
# ── P4-2a: the option-gated adb_command service ──
# Entities register their manager as a target when their entry enables the
# option; the domain service unregisters once the last participant unloads
# (core androidtv service posture: documented, opt-in, default off).
_ADB_COMMAND_TARGETS: dict[str, ShieldConnectionManager] = {}
_ADB_COMMAND_SCHEMA = vol.Schema(
{
vol.Required("command"): str,
# t14: the UI's target picker sends the SELECTED Shield as `entity_id`
# (a string, or a LIST — HA's picker sends a list for a picked target),
# and an automation that targets by device sends `device_id`. Both arrive
# here as text-or-list and are resolved to exactly ONE participant in the
# handler: a command must never be sent to a Shield the user did not pick,
# and "which one?" is never guessed.
vol.Optional(ATTR_ENTITY_ID): cv.entity_ids,
vol.Optional(ATTR_DEVICE_ID): cv.ensure_list_csv,
}
)
def _requested_adb_command_targets(call) -> list[str]:
"""The entity ids the caller selected, in order, deduplicated (t14).
TWO shapes reach here, both of them HA's own: the UI's target picker merges the
selection into the call as ``entity_id``, and an automation written against a
device target sends ``device_id``. A value is a string or a list (the picker
sends a list).
A device_id expands ONLY through this integration's own registry entries, so a
device id can never pull in an unrelated integration's entities — and with no
registry to consult it expands to nothing (an error naming the target, never a
guess).
"""
requested: list[str] = []
for value in cv.ensure_list(call.data.get(ATTR_ENTITY_ID)):
text = str(value).strip()
if text:
requested.append(text)
device_ids = cv.ensure_list(call.data.get(ATTR_DEVICE_ID))
if device_ids:
hass = getattr(call, "hass", None)
registry = er.async_get(hass) if hass is not None else None
for device_id in device_ids:
text = str(device_id).strip()
if not text or registry is None:
continue
# MEASURED on HA 2026.10.1: ``async_entries_for_device`` is a
# MODULE-LEVEL helper that takes the registry — the EntityRegistry class
# does not carry the method — and only the real-HA file drives it.
for entry in er.async_entries_for_device(registry, text):
# A Shield DEVICE carries sensors, a remote and an image entity too;
# only the media player is something this action can act on.
if entry.domain == ADB_COMMAND_TARGET_DOMAIN:
requested.append(entry.entity_id)
return list(dict.fromkeys(requested))
def _single_participant_target(call, targets: dict, *, service: str) -> str:
"""Exactly ONE participating Shield from ``targets``, or an error (t14/t17).
The three failures are told apart because the fix differs: nothing selected
(``no_target`` — pick the Shield), something selected that does not participate
in THIS action (``unsupported_target`` — its entry does not offer the action,
or it is another integration's entity), and more than one selected
(``ambiguous_target`` — never broadcast, never aimed at the wrong Shield).
t17: the same resolver serves ``adb_command`` and ``send_intent``; only the
registry of participants differs, and the messages name the SERVICE so the
error reads correctly for both (the placeholders are passed either way, so
neither call site can forget one).
"""
requested = _requested_adb_command_targets(call)
if not requested:
raise ServiceValidationError(
f"No Shield selected: pick one in the target picker, or pass entity_id "
f"(or its device_id). {service} sends nothing without a target.",
translation_domain=DOMAIN,
translation_key="no_target",
translation_placeholders={"service": service},
)
unknown = [entity_id for entity_id in requested if entity_id not in targets]
if unknown:
raise ServiceValidationError(
f"{', '.join(unknown)} is not a participant of {service} — nothing was sent.",
translation_domain=DOMAIN,
translation_key="unsupported_target",
translation_placeholders={
"entity_id": ", ".join(unknown),
"service": service,
},
)
if len(requested) > 1:
raise ServiceValidationError(
f"{', '.join(requested)} covers more than one {service} target — select "
"exactly one Shield (one media_player entity). Nothing was sent.",
translation_domain=DOMAIN,
translation_key="ambiguous_target",
translation_placeholders={
"entity_id": ", ".join(requested),
"service": service,
},
)
return requested[0]
def _single_adb_command_target(call) -> str:
"""The ``adb_command`` target (t14): the generalised resolver, one registry."""
return _single_participant_target(
call, _ADB_COMMAND_TARGETS, service=f"{DOMAIN}.{SERVICE_ADB_COMMAND}"
)
async def _async_adb_command_service(call):
"""Run a raw ADB shell command on the SELECTED Shield (t29 G8, t14).
The integration's async_setup registers this ALWAYS; the entry's
adb_command_enabled option gates USE (participants register from
async_added_to_hass). Failures raise ServiceValidationError with
translated keys (action-exceptions) — never warning logs.
t14 — THE TARGET. The service is registered domain-wide with a runtime
description whose ``target`` is the Shield's ``media_player`` entity, so the UI
offers a picker; HA merges whatever was picked into ``call.data`` as
``entity_id`` and/or ``device_id`` (a string, or the list a picked target
produces). Resolution is deliberately strict — exactly one participant, or a
ServiceValidationError naming what to pass — because the alternative (picking a
Shield for the user) is a raw shell command sent to the wrong device.
THE RESPONSE (t14). The output comes back under ``adb_response``, the same key
the deprecated ``androidtv.adb_command`` returned, so a template written
against that integration keeps working. Callers that do not ask for a response
are unaffected: HA drops the value, and the registration is OPTIONAL (never
"only"). An unreachable Shield is an error (``adb_unavailable``), not an empty
response.
"""
command = str(call.data.get("command") or "").strip()
if not command:
raise ServiceValidationError(
translation_domain=DOMAIN, translation_key="invalid_command"
)
entity_id = _single_adb_command_target(call)
manager = _ADB_COMMAND_TARGETS[entity_id]
poller = manager.adb_poller # public accessor (t21 F6)
if poller is None or not manager.connected:
raise ServiceValidationError(
translation_domain=DOMAIN,
translation_key="adb_unavailable",
translation_placeholders={"entity_id": entity_id},
)
result = await poller.shell(command)
_LOGGER.debug("adb_command %r → output=%s", command, result is not None)
return {ADB_COMMAND_RESPONSE_KEY: result}
# ── t17: registered intents — the model, the command, and the action ──
#
# The second half of the intents feature (docs/INTENTS_PLAN.md §3-§5). The
# discovery half (t16) ANSWERS "what can this app be asked to do"; nothing it
# finds runs by itself. This half is the user's explicit "register it, then fire
# it": one button entity per registered intent, and the
# ``nvidia_shield.send_intent`` action for per-intent variables.
#
# WHAT A REGISTERED INTENT IS. Ordinary options data (CONF_REGISTERED_INTENTS:
# a list of dicts, see const.py), so it survives a reload and is otherwise
# inert. Two rules shape everything below:
#
# * NOTHING RUNS UNLESS THE USER ASKED. No auto-registration from discovery, and
# no intent is fired by a poll, a state change or a reload. The only triggers
# are a button press and the action.
# * THE COMMAND IS BUILT, NEVER PASSED THROUGH. ``am start`` is assembled from
# the stored fields with plain ``str.replace``-style placeholder substitution
# (NO eval, NO format(), NO shell interpolation) and every single value is
# ``shlex.quote``d, so a variable whose value is ``"; rm -rf /"`` reaches the
# device as literal data inside one quoted word. ``adb_command`` remains the
# one raw-shell door; this is not a second one.
#
# The failures are named because the fix differs: an unknown intent name lists
# the known ones, a missing REQUIRED field names the field, a variable the
# intent never declared is REFUSED (nothing silently travels to the device, and
# nothing is silently dropped), a value that cannot become its declared type
# names the field and the value, a data template with an unfilled placeholder
# names the placeholder, ADB being off/down says so (the protocol cannot carry
# intents), and a device that answers with an error has its OWN message
# surfaced — never a silent success.
#: ``{name}`` in a data template — the ONLY place a placeholder is honoured.
_INTENT_PLACEHOLDER_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
#: A registered intent's id is a slug: it becomes the button's key and the
#: selector's value, so it must be safe in both and can never collide with the
#: "Add new" sentinel.
_INTENT_ID_RE = re.compile(r"^[a-z0-9_]+$")
#: Declared field keys are shell-safe by construction: letters, digits and
#: underscores, never a leading dash (so a key can never be read as a flag).
_INTENT_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
def intent_slug(text: str) -> str:
"""A registered intent's id from its display name (t17).
Deterministic and readable: lower-case, runs of anything else become ``_``.
The options screen uses this for new rows; an existing row keeps its id, so
renaming an intent never moves its button.
"""
slug = re.sub(r"[^a-z0-9]+", "_", str(text or "").lower()).strip("_")
return slug or "intent"
def _normalised_field(raw) -> dict | None:
"""One declared field, defensively normalised; None when unusable (t17).
The runtime reads options a user may have hand-edited, so this is the
tolerant door: a field without a usable key or type is DROPPED here and the
row keeps working with the fields that are sound (the options screen refuses
to write one in the first place).
"""
if not isinstance(raw, dict):
return None
key = str(raw.get("key") or "").strip()
type_ = str(raw.get("type") or "string").strip().lower()
if not _INTENT_KEY_RE.match(key) or type_ not in INTENT_FIELD_TYPES:
return None
field = {"key": key, "type": type_, "required": bool(raw.get("required"))}
default = raw.get("default")
if default is not None and str(default) != "":
field["default"] = str(default)
return field
def normalise_intent(raw) -> dict | None:
"""One registered intent in the shape the runtime reads; None when unusable.
The rule the whole feature turns on: an intent must name SOMETHING to launch
— a component (``pkg/.Activity``, with the slash Android requires) OR an
action (optionally with categories). A row with neither cannot produce a
command, so it is dropped rather than kept as a button that can only fail.
"""
if not isinstance(raw, dict):
return None
name = str(raw.get("name") or "").strip()
package = str(raw.get("package") or "").strip()
intent_id = str(raw.get("id") or "").strip() or intent_slug(name)
if not _INTENT_ID_RE.match(intent_id):
intent_id = intent_slug(intent_id or name)
activity = str(raw.get("activity") or "").strip()
action = str(raw.get("action") or "").strip()
if "/" not in activity:
# "-n pkg.Activity" without the "/" is never a component Android accepts
activity = ""
if not name or not package or not (activity or action):
return None
categories = [
str(category).strip()
for category in (raw.get("categories") or [])
if str(category).strip()
]
fields = [_normalised_field(field) for field in (raw.get("fields") or [])]
return {
"id": intent_id,
"name": name,
"package": package,
"activity": activity,
"action": action,
"categories": categories[:INTENT_FIELD_LIMIT],
"data": str(raw.get("data") or ""),
"fields": [field for field in fields if field][:INTENT_FIELD_LIMIT],
}
def registered_intents(options) -> list[dict]:
"""Every registered intent of an entry, in order, deduplicated (t17).
Reads OPTIONS and nothing else: no shell, no discovery, no I/O. Duplicate
ids keep their FIRST row (a hand-edited copy cannot shadow the real one),
and the registration cap is applied here so the runtime and the screen agree
about what exists.
"""
raw_rows = (options or {}).get(CONF_REGISTERED_INTENTS) or []
if isinstance(raw_rows, dict):
# tolerate a mapping-shaped paste: the VALUES are the rows
raw_rows = list(raw_rows.values())
intents: list[dict] = []
seen: set[str] = set()
for raw in raw_rows:
intent = normalise_intent(raw)
if intent is None or intent["id"] in seen:
continue
seen.add(intent["id"])
intents.append(intent)
if len(intents) >= INTENT_REGISTRATION_LIMIT:
break
return intents
def intent_by_id(options, intent_id) -> dict | None:
"""The registered intent with this id, or None (t17)."""
wanted = str(intent_id or "").strip()
for intent in registered_intents(options):
if intent["id"] == wanted or intent["name"] == wanted:
return intent
return None
def intent_default_variables(intent) -> dict:
"""The values a button press supplies: the declared DEFAULTS (t17).
A required field with no default makes a button press an error naming the
field — which is honest: the button has no way to ask, and the action is
where such an intent is meant to be used.
"""
return {
field["key"]: field["default"]
for field in (intent.get("fields") or [])
if "default" in field
}
def _intent_value(key: str, type_: str, value, intent_name: str):
"""Coerce one declared value to its type, or raise naming field+value (t17)."""
if type_ in ("string", "raw"):
return str(value)
if type_ == "int":
try:
return str(int(str(value).strip()))
except (TypeError, ValueError):
pass
elif type_ == "bool":
text = str(value).strip().lower()
if text in ("true", "1", "yes", "on"):
return "true"
if text in ("false", "0", "no", "off", "none"):
return "false"
raise ServiceValidationError(
f"'{key}' expects a {type_} value, but {value!r} is not one — "
f"'{intent_name}' was not sent.",
translation_domain=DOMAIN,
translation_key="invalid_intent_field",
translation_placeholders={
"field": key,
"type": type_,
"value": str(value),
"intent": intent_name,
},
)
def intent_am_start_command(intent, variables=None) -> str:
"""The ``am start`` command for ONE registered intent (t17).
Assembled from the stored row plus the caller's variables; raises a
ServiceValidationError (with a plain message AND a translation key, so the
button and the action both read well) for every way it can be wrong. No
value is ever interpolated into a shell string unquoted, and no value is
ever evaluated: a data template's ``{placeholder}`` is replaced with text.
"""
intent_name = str(intent.get("name") or intent.get("id") or "intent")
fields = intent.get("fields") or []
declared = {field["key"] for field in fields}
given = {str(key): value for key, value in (variables or {}).items()}
unknown = sorted(set(given) - declared)
if unknown:
raise ServiceValidationError(
f"'{intent_name}' declares no field(s) {', '.join(unknown)} — nothing was sent.",
translation_domain=DOMAIN,
translation_key="unknown_intent_variable",
translation_placeholders={
"fields": ", ".join(unknown),
"intent": intent_name,
},
)
resolved: dict[str, tuple[str, str]] = {}
for field in fields:
key = field["key"]
if key in given:
value = given[key]
elif "default" in field:
value = field["default"]
elif field.get("required"):
raise ServiceValidationError(
f"'{intent_name}' needs a value for '{key}' — nothing was sent.",
translation_domain=DOMAIN,
translation_key="missing_intent_field",
translation_placeholders={"field": key, "intent": intent_name},
)
else:
continue # optional, no default, not supplied: simply not sent
resolved[key] = (_intent_value(key, field["type"], value, intent_name), field["type"])
data = str(intent.get("data") or "")
if data:
def _substitute(match: re.Match) -> str:
key = match.group(1)
if key not in resolved:
raise ServiceValidationError(
f"'{intent_name}' uses {{{key}}} in its data, but no value was "
"supplied for it — nothing was sent.",
translation_domain=DOMAIN,
translation_key="unresolved_intent_placeholder",
translation_placeholders={"placeholder": key, "intent": intent_name},
)
return str(resolved[key][0])
data = _INTENT_PLACEHOLDER_RE.sub(_substitute, data)
parts = ["am start"]
activity = str(intent.get("activity") or "")
action = str(intent.get("action") or "")
if activity:
parts += ["-n", shlex.quote(activity)]
if action:
parts += ["-a", shlex.quote(action)]
for category in intent.get("categories") or []:
parts += ["-c", shlex.quote(str(category))]
if data:
parts += ["-d", shlex.quote(data)]
for key, (value, type_) in resolved.items():
parts += [INTENT_TYPE_FLAGS[type_], shlex.quote(key), shlex.quote(value)]
return " ".join(parts)
#: The lines an ``am start`` failure prints. Checked as substrings because the
#: device's own wording varies by Android version; a match is surfaced VERBATIM
#: (the device's message is the useful one) and never guessed at.
_INTENT_FAILURE_MARKERS = (
"error:",
"exception:",
"permission denial",
"does not exist",
"unable to resolve",
"not found",
"security exception",
)
def intent_failure_message(output) -> str | None:
"""The device's own error text from an ``am start`` answer, or None (t17).
``am start`` prints "Starting: Intent {…}" when it accepted the intent. A
rejected one prints an error line instead, and THAT line is what the user
needs ("unable to resolve Intent", "does not exist", "Permission Denial"),
so it is returned as-is rather than replaced by our prose.
"""
if output is None:
return None
for line in str(output).splitlines():
stripped = line.strip()
if not stripped:
continue
lowered = stripped.lower()
if any(marker in lowered for marker in _INTENT_FAILURE_MARKERS):
return stripped
return None
async def run_registered_intent(manager, entity_id: str, intent, variables=None) -> str:
"""Send ONE registered intent over ADB; return the output, raise on failure (t17).
The single place a registered intent becomes a shell command, shared by the
button platform and the action so the two cannot diverge. ADB is the only
transport that can carry an intent — when it is off or down the error says
exactly that instead of an obscure failure (the protocol transport has no
``am start``).
"""
command = intent_am_start_command(intent, variables)
poller = getattr(manager, "adb_poller", None) if manager is not None else None
if poller is None or not getattr(manager, "connected", False):
raise ServiceValidationError(
f"'{intent.get('name') or intent.get('id')}' needs ADB: turn ADB on for "
f"{entity_id} and make sure the Shield is reachable — the remote protocol "
"cannot send an intent. Nothing was sent.",
translation_domain=DOMAIN,
translation_key="intents_need_adb",
translation_placeholders={"entity_id": entity_id},
)
_LOGGER.debug("send_intent %s → %s", intent.get("id"), command)
output = await poller.shell(command)
if output is None:
raise ServiceValidationError(
f"The Shield did not answer for '{intent.get('name') or intent.get('id')}' "
"— nothing was sent.",
translation_domain=DOMAIN,
translation_key="intent_no_answer",
translation_placeholders={"entity_id": entity_id},
)
message = intent_failure_message(output)
if message:
raise ServiceValidationError(
f"The Shield refused '{intent.get('name') or intent.get('id')}': {message}",
translation_domain=DOMAIN,
translation_key="intent_failed",
translation_placeholders={"message": message},
)
return output
# ── t17: the send_intent action ──
#
# WHICH SHIELDS PARTICIPATE. The same idea as adb_command, with a different
# registry on purpose: a raw shell command is opt-in behind
# ``adb_command_enabled`` (t29 G8), while an intent can only ever run because
# the USER REGISTERED IT, so the media player participates whenever it exists.
# Nothing runs by itself: an entry with no registered intents can produce no
# button and no successful call.
_INTENT_TARGETS: dict[str, ShieldConnectionManager] = {}
_INTENT_SCHEMA = vol.Schema(
{
vol.Required("intent"): str,
vol.Optional("variables"): dict,
# exactly the t14 target handling: the picker merges the selection into
# the call as entity_id (string or list); a device target sends device_id
vol.Optional(ATTR_ENTITY_ID): cv.entity_ids,
vol.Optional(ATTR_DEVICE_ID): cv.ensure_list_csv,
}
)
def send_intent_service_description(names) -> dict:
"""The runtime DESCRIPTION of ``send_intent`` (t17).
MEASURED on HA 2026.10.1 (t14, re-read for t17): ``async_set_service_schema``
copies ``name``/``description``/``fields`` verbatim, validates only
``target``, and adds the ``response`` flag from the service's registration —
so a field's ``selector`` is what the frontend renders, and the intent
dropdown is a plain select selector with ``custom_value`` on (a name
registered after this description was published must still be typeable, and
the action validates the name against the ENTRY's own list anyway).
``names`` is passed in because the list is per-ENTRY data while the service
description is domain-wide: the caller publishes what is loaded, and the
lookup at call time stays authoritative.
"""
options = sorted({str(name) for name in (names or []) if str(name).strip()})
return {
"name": "Send intent",
"description": (
"Send one of this Shield's REGISTERED intents over ADB (the Android "
"``am start`` command built from the registration). Register intents in "
"the integration's options under Intents; the action returns the "
"device's own output, and a rejected intent raises with the device's "
"message."
),
"target": INTENT_SERVICE_TARGET,
"fields": {
"intent": {
"name": "Intent",
"description": (
"Which registered intent to send, by its name (as the Intents "
"screen shows it). Registering an intent also creates a button "
"for it: the button is the no-variable way, this action is how "
"variables arrive from automations and scripts."
),
"required": True,
"selector": {
"select": {
"options": options,
"custom_value": True,
"mode": "dropdown",
}
},
},
"variables": {
"name": "Variables",
"description": (
"A value for each field the intent declares (keys as declared on "
"the Intents screen). A declared field with a default may be "
"omitted; a required one raises, naming the field. Fields the "
"intent does not declare are refused — nothing is guessed and "
"nothing extra is sent."
),
"selector": {"object": {}},
},
"entity_id": {
"name": "Entity",
"description": (
"The Shield to send it to: its media_player entity. Select it in "
"the target picker above, or pass entity_id (or the Shield's "
"device_id) in YAML."
),
"selector": {"entity": {"domain": "media_player"}},
},
},
}
async def _async_send_intent_service(call):
"""Send ONE registered intent to the SELECTED Shield (t17).
The target resolution is t14's, unchanged in spirit: exactly one participant,
or an error naming what to pass. Everything after that is the registration's
own business — the ENTRY's options decide which intents exist, so an unknown
name lists the ones that do, and the device's output is returned under
INTENT_RESPONSE_KEY so a template can see whether the Shield accepted it.
"""
entity_id = _single_participant_target(
call, _INTENT_TARGETS, service=f"{DOMAIN}.{SERVICE_SEND_INTENT}"
)
manager = _INTENT_TARGETS[entity_id]
options = getattr(getattr(manager, "entry", None), "options", None) or {}
intents = registered_intents(options)
wanted = str(call.data.get("intent") or "").strip()
intent = intent_by_id(options, wanted)
if intent is None:
known = ", ".join(sorted(intent["name"] for intent in intents)) or "none yet"
raise ServiceValidationError(
f"'{wanted or '<empty>'}' is not a registered intent of {entity_id}. "
f"Known intents: {known}.",
translation_domain=DOMAIN,
translation_key="unknown_intent",
translation_placeholders={
"intent": wanted or "<empty>",
"known": known,
"entity_id": entity_id,
},
)
variables = call.data.get("variables") or {}
if not isinstance(variables, dict):
raise ServiceValidationError(
f"'variables' must be a mapping of field name to value for "
f"'{intent['name']}' — nothing was sent.",
translation_domain=DOMAIN,
translation_key="invalid_intent_variables",
translation_placeholders={"intent": intent["name"]},
)
output = await run_registered_intent(manager, entity_id, intent, variables)
_LOGGER.debug("send_intent %s → output=%s", intent["id"], output is not None)
return {INTENT_RESPONSE_KEY: output}
Reference in new issue View Git Blame Copy Permalink