# Samsung TV Wake on LAN: restore "turn the TV on from Home Assistant"
# after HA deprecated the implicit magic packet.
#
# Home Assistant's samsungtv integration used to send the Wake-on-LAN
# packet itself: ``media_player.turn_on`` on a TV whose config entry
# stored a MAC woke the panel, with nothing to configure. That branch
# now raises the ``deprecated_implicit_wake_on_lan`` repair issue
# (breaks_in_ha_version 2026.8.0) and the supported replacement is an
# explicit automation. The entity only takes the deprecated path when
# *no* turn_on automation is registered, so installing this recipe both
# keeps the TV waking and stops the warning being raised again. It does
# not clear one already showing: samsungtv/entity.py calls
# ``ir.async_create_issue`` and never ``async_delete_issue``, so an
# existing notice stays until the homeowner dismisses it.
#
# Each automation is four lines. The work this recipe saves the
# homeowner is the three pieces around them:
#   1. each TV's MAC address, read here from its samsungtv config entry
#      by the ``samsung_tv_macs`` resolver rather than looked up in the
#      TV's network menu;
#   2. the Wake on LAN integration, which is NOT part of HA's
#      default_config, so ``wake_on_lan.send_magic_packet`` does not
#      exist until someone adds it. It is declared below as a prereq
#      with ``auto_setup``, so the wizard offers a "Set up Wake on LAN"
#      button that drives the config flow server-side instead of asking
#      for a four-field form. One setup covers every television: HA
#      registers the service in the component's ``async_setup``, not per
#      config entry, and each automation carries its own MAC;
#   3. the ``samsungtv.turn_on`` trigger, once per television. The
#      editor does offer it, as the TV's "Device is requested to turn
#      on" device trigger, but a house of sets means one automation per
#      TV, each paired with the right MAC by hand.
#
# One install covers the whole house. The package is written per recipe
# slug, so a second install would overwrite the first rather than add a
# second television. That is why the TV role is multi-select and the
# template writes one automation per set.
#
# No helpers and no dashboard card: the recipe adds no entity of its
# own, and the control surface is the TV's existing media_player card,
# whose power button is exactly what starts firing again.
slug: samsung-tv-wake-on-lan
version: 1.0.0
title: "Samsung TV: Wake on LAN"
tagline: Turn your televisions on from Home Assistant again, the way the samsungtv integration used to before Wake-on-LAN had to be wired up by hand.
description: >-
  Restores power-on for your Samsung TVs after Home Assistant deprecated
  the implicit Wake-on-LAN in the samsungtv integration. Installs the
  automation the deprecation asks for, one per television you pick: a
  samsungtv turn_on trigger that sends the magic packet to that set's
  MAC address. Reads each MAC from the TV's own config entry and sets up
  the Wake on LAN integration for you, so nothing has to be looked up or
  typed in.
author: Selora AI
released: "2026-09-23"
# The ``samsung_tv_macs`` resolver and the ``mapping`` input type it
# fills both ship in 0.18.0. An older integration rejects the manifest
# outright (unknown input type), so the catalog hides the recipe below
# that release instead.
min_integration_version: "0.18.0"
tags: [entertainment, tv, samsung, wake-on-lan]
roles:
  # The televisions to wake. ``integration: samsungtv`` is what makes the
  # picker useful: the trigger platform below is samsungtv's own, so a
  # Chromecast or a Sonos in the media_player domain could be selected
  # but could never fire it.
  #
  # No max_count: every Samsung TV in the house can be picked at once,
  # and the template writes one automation per set. That is not a
  # convenience: the package is written per recipe slug, so installing
  # this recipe a second time for a second television would overwrite
  # the first rather than add to it.
  #
  # The title names what is being picked, not the brand: the Match step
  # lists the samsungtv integration prereq as "Samsung Smart TV", and a
  # role called "Samsung TV" sitting under it reads as the same row
  # twice rather than as "is the integration connected?" followed by
  # "which televisions?".
  - id: tv
    title: Televisions to wake
    kind: media_player
    integration: samsungtv
    min_count: 1
    selection: required
    description: >-
      The Samsung televisions to turn on. Only TVs reached through the
      samsungtv integration are offered, because the wake trigger is
      that integration's own.
inputs:
  # One MAC address per picked television, keyed by its entity id, which
  # is what lets a single install cover a house. Auto-resolved by the
  # ``samsung_tv_macs`` resolver from the config entries behind the
  # bound entities, which already store them, so the wizard never shows
  # this field and the homeowner never opens a TV's network menu.
  #
  # ``mapping`` is the resolver-only input type for exactly this shape;
  # a scalar input would cap the recipe at one television. The resolver
  # raises when a picked TV publishes no MAC (older models don't), and
  # the install halts with a punch-list entry naming that set rather
  # than quietly leaving it without a wake automation.
  - id: macs
    type: mapping
    label: TV MAC addresses
    description: >-
      Hardware address each wake packet is sent to. Read automatically
      from your Samsung TVs' existing Home Assistant connections.
    resolver: samsung_tv_macs
    default: {}
integrations:
  # Declared so a home whose TV was set up over another integration is
  # told that, rather than shown an empty picker: the role is scoped to
  # the samsungtv platform, so without it the wizard has nothing to
  # offer and the reason is invisible. No auto_setup: samsungtv's flow
  # needs the on-screen pairing prompt accepted on the TV itself, which
  # is a person in front of the panel, not a backend call.
  - domain: samsungtv
    title: Samsung Smart TV
  # Wake on LAN is not in HA's default_config, so on most homes
  # ``wake_on_lan.send_magic_packet`` simply does not exist and the
  # automation would fail at runtime with a service-not-found. The
  # prereq gate catches that before the package is written.
  #
  # auto_setup makes it a button rather than a form: the wizard runs
  # HA's config flow server-side with the MAC the ``samsung_tv_mac``
  # resolver already found, which is the same value the flow's only
  # required field asks for. The optional SecureOn password, broadcast
  # address, and broadcast port are left unset.
  #
  # One entry is enough for the whole house, whichever TV seeds it: HA
  # registers ``send_magic_packet`` in the wake_on_lan component's
  # ``async_setup``, not per config entry, and each automation names the
  # MAC it wants. The entry exists to make the service exist.
  #
  # Which also means the entry's options never reach the automations:
  # the service reads only its own call data. Editing the entry's
  # broadcast address changes that entry's button, not what this recipe
  # sends. The automations send a plain broadcast to the MAC, which is
  # the replacement HA's repair text asks for ("an explicit Wake-On-LAN
  # automation ... targeting MAC address X") and what reaches a TV on
  # Home Assistant's own network segment, the topology Samsung sets need
  # anyway (they refuse off-subnet control connections). The deprecated
  # implicit path also sent a unicast to the TV's last known IP; a
  # cross-subnet home that relied on that has to add the TV's
  # ``broadcast_address`` to its automation by hand.
  - domain: wake_on_lan
    title: Wake on LAN
    auto_setup:
      resolved:
        mac: samsung_tv_mac
package_files:
  - package/automations/wake.yaml.j2

{# Samsung TV Wake on LAN: send the magic packet whenever something
   asks one of the chosen televisions to turn on.

   One automation per TV, because the trigger is per entity and the
   packet is per MAC. They all come from one install: the package is
   written per recipe slug, so installing the recipe again for a second
   television would overwrite the first rather than add to it.

   ``samsungtv.turn_on`` is the samsungtv integration's own trigger
   platform (samsungtv/triggers/turn_on.py, dispatched through
   samsungtv/trigger.py). The media_player and remote entities register
   a PluggableAction keyed on their device_id, and calling
   media_player.turn_on runs whatever is attached to it. Registering
   these automations is therefore both the wake path and the thing that
   retires HA's deprecated_implicit_wake_on_lan repair issue: the
   entity only falls back to sending the packet itself when no turn_on
   automation exists.

   The trigger schema takes device_id OR entity_id
   (cv.has_at_least_one_key) and translates an entity_id to the device
   it belongs to, so the entity the role resolves is enough: no
   device-registry lookup, and no device_id that would change if a TV
   were re-paired.

   ``inputs.macs`` is a mapping input: one MAC per bound entity, keyed
   by entity id, resolved from each TV's own samsungtv config entry.
   A picked TV that publishes no MAC halts the install rather than
   rendering here, so every key in this loop resolves.

   The automation id is keyed on the entity's object_id rather than the
   loop index, so reinstalling after adding or dropping a television
   leaves the other automations' ids where they were. HA tracks state
   and traces per id; a positional id would shuffle them.

   mode: single because the packet is idempotent: a second turn_on
   while the first is still in flight has nothing to add, and the TV is
   either already awake or about to be.

   The MAC is quoted so YAML reads it as a string. A bare
   00:11:22:33:44:55 is parsed as a sexagesimal number by YAML 1.1
   loaders, which would hand wake_on_lan an integer.

   No runtime Jinja here, so nothing needs {% raw %}. If any is added,
   keep it on a single quoted line, because the renderer's trim_blocks
   swallows the following line at an end-of-line tag. #}
automation:
{% for tv in roles.tv %}
  - id: selora_recipe_{{ slug | replace('-', '_') }}_wake_{{ tv.split('.')[1] }}
    alias: "Samsung TV: wake on LAN ({{ tv.split('.')[1] | replace('_', ' ') }})"
    description: >-
      Sends a Wake-on-LAN magic packet to {{ tv }} whenever Home
      Assistant is asked to turn it on, replacing the implicit
      Wake-on-LAN the samsungtv integration deprecated.
    mode: single
    trigger:
      - platform: samsungtv.turn_on
        entity_id: {{ tv }}
    action:
      - service: wake_on_lan.send_magic_packet
        data:
          mac: "{{ inputs.macs[tv] }}"
{% endfor %}