SamsungTV Smart and Art Mode

A custom integration for Home Assistant to control Samsung Smart TVs (Tizen OS), based on the excellent work of ollo69/ha-samsungtv-smart.

If this project is useful to you, you can support its development:

This fork brings improved WebSocket stability, full Samsung Frame TV Art Mode support, picture mode and source selection fixes for 2024 Frame TVs, and OAuth2 authentication for SmartThings.

---

Table of Contents

• Features
• Requirements
• Migrating from ollo69
• Installation
• Configuration
  • SmartThings Authentication
  • Integration Setup
  • Options
  • Reconfigure
• Entities
• Services
  • Standard TV Services
  • Frame Art Services
• Frame Art Mode
  • Thumbnail Downloads
• Automations & Tips
• Troubleshooting
  • Integration not appearing in Add Integration
  • IP Control reports Art Mode "on" when it isn't
• Credits

---

Features

• Full Samsung Smart TV (Tizen OS) control via WebSocket
• Power on/off, volume, source selection, app launching
• SmartThings integration for enhanced status polling (channel info, picture mode, sound mode…)
• Three SmartThings authentication methods: OAuth2, Personal Access Token, or existing ST integration
• Samsung Frame TV Art Mode — full artwork management via a dedicated async API
• New dedicated entities: Art Mode switch and Frame Art sensor
• Picture mode control — select entity with dual-strategy (SmartThings API + WS fallback for HDMI inputs)
• Improved source detection — REST fallback for Frame 2024 TVs where supportedInputSources returns empty; supports custom source names
• App name resolution — unknown SmartThings app IDs are parsed and resolved to display names
• Improved WebSocket connection stability — prevents zombie connections and saturation
• Wake-on-LAN support
• Channel and app list management
• Logo fetching for apps and sources
• folder-gallery-card Lovelace card bundled — no manual installation required

---

Requirements

• Home Assistant ≥ 2025.6.0
• Python packages (installed automatically): websocket-client, wakeonlan, aiofiles, casttube, pysmartthings>=6.0
• A Samsung Smart TV running Tizen OS (2016+), reachable on the local network
• For SmartThings features: a Samsung account and a SmartThings-registered TV

---

Migrating from ollo69/ha-samsungtv-smart

This fork is a drop-in replacement for ollo69's integration. Migration is straightforward and preserves entity IDs, automations, and all existing configuration.

Before you start

• Note down your custom source list, app list, and channel list for each TV: Settings → Integrations → SamsungTV Smart → Configure
• Have your SmartThings credentials ready (API key or OAuth token)
• Optionally, install Spook — it will flag any broken entity references after migration, saving you a lot of manual checking

Migration steps

1. Remove ollo69's integration for each TV via Settings → Integrations → SamsungTV Smart → Delete. Do not rename or remove any entities beforehand.

2. Uninstall ollo69 via HACS — go to HACS → Integrations, find the ollo69 integration and remove it. Then verify that the samsungtv_smart folder is gone from your config/custom_components/ directory (use File Editor or SSH). If it still exists, delete it manually.

   ⚠️ This step is critical: when migrating between two integrations sharing the same domain (samsungtv_smart), HACS can sometimes remove the newly installed files when uninstalling the old one. Always confirm the folder is absent before reinstalling.

3. Restart Home Assistant before proceeding. This ensures the old domain is fully cleared from HA's internal registry.

4. Install this fork via HACS (add https://github.com/TheFab21/ha-samsungtv-smart as a custom repository, see Installation), then restart Home Assistant again.

5. Verify files are on disk before trying to add the integration:

   ls /config/custom_components/samsungtv_smart/

   If the folder is missing or empty despite HACS showing the integration as "Downloaded", use the HACS 3-dot menu → Redownload to force a fresh install.

6. Add each TV using the badge below or via Settings → Devices & Services → + Add Integration → search SamsungTV Smart. Use the exact same device name as before — this preserves your entity IDs (e.g. media_player.living_room_tv).

7. Re-enter your SmartThings credentials when prompted. OAuth2 is recommended for a maintenance-free setup (see SmartThings Authentication).

8. Restore your source, app, and channel lists via Settings → Integrations → SamsungTV Smart → Configure for each TV. The format is identical to ollo69.

9. If any entity ID got a _2 suffix, rename it back via Settings → Entities.

Key differences from ollo69

• Art Mode: use the dedicated switch.<tv_name>_art_mode entity to toggle Art Mode instead of the set_art_mode service. The switch is more reliable and works consistently across all Frame TV models, including multi-TV setups.
• Picture mode: a new select.<tv_name>_picture_mode entity is available. If you had automations calling samsungtv_smart.select_picture_mode, they continue to work.
• SmartThings authentication: OAuth2 is now available and strongly recommended over Personal Access Tokens (PATs expire after 24 hours).
• Frame 2024 TVs: source list and picture mode detection are fixed via REST fallbacks — no manual workarounds needed.

---

Installation

HACS (recommended)

Or manually add the custom repository in HACS:

1. Go to HACS → Integrations → ⋮ → Custom repositories
2. Add https://github.com/TheFab21/ha-samsungtv-smart as Integration
3. Search for SamsungTV Smart and install

Manual

1. Download or clone this repository.

2. Copy the samsungtv_smart folder into your Home Assistant custom_components directory:

   config/
   └── custom_components/
       └── samsungtv_smart/
   

3. Restart Home Assistant.

---

Configuration

SmartThings Authentication

⚠️ Upcoming SmartThings API pricing change. Samsung has announced that the SmartThings API will move to paid tiers, with free access phasing out around October 2026 (a $4.99/month "Personal" plan with a monthly call quota for individual/non-commercial developers, plus separate commercial tiers — exact quotas not yet published). All SmartThings features of this integration (picture mode, channel/app info, sound mode, etc.) call the SmartThings API under your own Samsung account, so this may eventually apply to you, not just to the project itself. Nothing changes today and no code changes are required yet — this integration still works exactly as before. We're tracking the published quotas and will document any impact (e.g. reducing polling frequency) once Samsung releases the details. See the SmartThings blog post for the announcement.

Three methods are available. Choose one.

---

Option 1 — OAuth2 (Recommended)

This method authenticates via your Samsung account. Tokens are refreshed automatically.

Step 1 — Create a SmartThings OAuth App (one time)

⚠️ The SmartThings Developer Portal web UI no longer supports creating OAuth apps. Use the SmartThings CLI instead.

1. Install the SmartThings CLI.
2. Run smartthings apps:create and follow the interactive prompts:
   • Display Name: Home Assistant Samsung TV
   • Description: For Home Assistant integration of Samsung The Frame TV
   • Icon Image URL: leave blank
   • Target URL: leave blank
   • Scopes: select r:devices:* and x:devices:*
   • Redirect URI: https://my.home-assistant.io/redirect/oauth
   • Select Finish and create OAuth-In SmartApp
3. The CLI will display your app credentials — save the OAuth Client Id and Client Secret.

⚠️ Use the OAuth Client Id, NOT the App Id.

Step 2 — Add Application Credentials in Home Assistant

1. Go to Settings → Devices & Services.
2. Click ⋮ → Application Credentials → + Add Application Credentials.
3. Select SamsungTV Smart.
4. Enter your Client ID and Client Secret.
5. Click Add.

The OAuth2 option will only appear in the integration setup after completing this step.

Step 3 — Configure the integration

When adding the integration, select OAuth2 (Sign in with Samsung) and follow the login flow.

---

Option 2 — Personal Access Token (PAT)

⚠️ Not recommended. SmartThings Personal Access Tokens have a limited lifetime (24 hours). When the token expires, SmartThings features will stop working silently and you will need to manually generate a new token and reconfigure the integration. Consider using OAuth2 or SmartThings Integration Link for a maintenance-free setup.

1. Go to https://account.smartthings.com/tokens.
2. Create a new token with at least Devices permissions.
3. Copy the token.
4. When adding the integration, select Personal Access Token and paste it.

---

Option 3 — SmartThings Integration Link

If you already have the native SmartThings integration configured in Home Assistant:

1. When adding the integration, select Personal Access Token.
2. In the dropdown, select your existing SmartThings integration instead of entering a token manually.

---

Integration Setup

Click the badge above to open the config flow directly, or follow these steps manually:

1. Go to Settings → Devices & Services → + Add Integration.
2. Search for SamsungTV Smart and select it.
3. Choose your authentication method (see above).
4. Enter your TV's IP address (a static IP or DHCP reservation is strongly recommended).
5. Follow the on-screen steps. Your TV may prompt you to accept the pairing request — accept it.

Note: Custom integrations installed via HACS do not appear under the "Samsung" brand group in the Add Integration search. If you can't find "SamsungTV Smart" in the search results, use the badge above — it opens the config flow directly regardless.

Tip: If your TV is off and you are using Wake-on-LAN, make sure WOL is enabled in your TV's network settings.

---

Options

After initial setup, click Configure on the integration card to access these options:

Option	Description
Source list	Define custom input sources (JSON: {"HDMI 1": "KEY_HDMI1", ...})
App list	Define custom app shortcuts (JSON)
App load method	How to load the app list: All, Default, or Disabled
App launch method	Standard, Remote, or REST
Power on method	Wake-on-LAN or SmartThings
WOL repeat count	Number of WOL packets sent (1–5)
Scan interval	SmartThings polling interval (seconds)
Use ST channel info	Fetch live channel info from SmartThings
Use ST status info	Fetch power/input status from SmartThings
Show channel number	Display channel number alongside channel name
Use mute check	Detect mute state via SmartThings
Logo option	Show logos for apps/channels (local or remote)
Sync turn on/off	Optional entity to mirror TV power state
External power entity	Use an external sensor to determine power state
Toggle Art Mode	Toggle Art Mode when turning on a Frame TV that is already in Art Mode
Ping port	Port used to detect TV presence
WS name	Name shown on the TV when pairing (default: [Home Assistant])

IP Control moved. Pairing and the Enable IP Control / Enable IP Control Art Mode toggles are no longer in this Options screen — they now live under Reconfigure → IP Control (see Reconfigure below).

---

How control works — and what App launch method actually does

These are two different layers. Don't confuse the App launch method option with how the integration connects to the TV.

App launch method (an option — app launching only)

The App launch method option (Standard / Remote / REST) only decides which channel is used to launch an application. It has no effect on power, keys, volume, sources or Art Mode.

Value	What it does
Standard	ms.application.start over the control WebSocket channel (falls back to remote). Recommended.
Remote	ed.apps.launch over the remote WebSocket channel (same channel as key presses).
REST	POST /api/v2/applications/{id} over HTTP. Deprecated by Samsung on recent Tizen — often a no-op on 2022+ sets, and the integration reports success even when nothing launched.

Recommendation: leave this on Standard. Switch to Remote only if a specific app won't launch. REST is mainly relevant to older TVs.

Connection layers (the architecture — they coexist)

The integration does not pick a single connection mechanism. Three layers run together, each with its own job:

Layer	Transport	Role
WebSocket	Local, ports 8001/8002	Primary control: power, keys, volume, sources, app launching, and Frame Art Mode.
SmartThings	Cloud (OAuth2 / PAT)	Status polling (power, input, channel, picture/sound mode) and optional power-on. Read-mostly — not a local command channel.
IP Control	Local JSON-RPC, port 1516	Optional. Reliable power on/off without SmartThings, plus optional Art Mode control. Paired and toggled under Reconfigure.

The three layers are complementary, not alternatives. App launch method sits on top of the WebSocket layer (two of its three values are WebSocket channels); it is not a fourth connection mechanism.

---

Reconfigure

To change connection or credentials after setup, open Settings → Devices & Services → Samsung TV Smart → Reconfigure. The flow is split into three clear sections so you only touch what you need:

Section	What it changes
Connection	TV IP address and WebSocket port (8001, or 8002 for SSL-only TVs). Use 8001 unless your TV only answers on 8002. The integration also falls back between the two ports automatically at runtime if a firmware update filters the configured one.
Authentication	The auth method (OAuth2 / Personal Access Token / SmartThings link). For OAuth2, selecting it starts the login flow immediately.
IP Control	Pair the local JSON-RPC channel (port 1516) and, once paired, toggle Enable IP Control (reliable power on/off without SmartThings) and Enable IP Control Art Mode (⚠️ off by default — see the warning below). To pair, check Pair now with the TV ON and in normal viewing (not Art Mode) and accept the on-screen prompt.

⚠️ Do not enable Enable IP Control Art Mode unless you know your firmware handles it — it can break Art Mode entirely and may need a factory reset to recover (seen on QE55LS03D fw 2123). See IP Control reports Art Mode "on" when it isn't.

---

Entities

Each configured TV creates the following entities:

Entity	Type	Description
media_player.<tv_name>	Media Player	Main TV control entity
switch.<tv_name>_art_mode	Switch	Toggle Art Mode on/off (Frame TVs only)
sensor.<tv_name>_frame_art	Sensor	Currently displayed artwork info (Frame TVs only)
sensor.<tv_name>_personal / _store / _other	Sensor	Thumbnail folder size (MB) per subdirectory, with a file_list attribute for gallery cards (Frame TVs only, auto-created in v7)
select.<tv_name>_picture_mode	Select	Change picture mode (Standard, Movie, etc.)

Note: The folder-gallery-card Lovelace card is bundled with this integration and registered automatically. No manual installation or resource configuration required.

Media Player Attributes

In addition to standard media player attributes, the following are available:

• device_model, device_name, device_os, device_mac
• picture_mode, picture_mode_list
• sound_mode, sound_mode_list
• channel, channel_name, channel_number
• app_id, app_name
• frame_art_mode — whether Art Mode is active
• frame_art_current — content ID of the current artwork

Frame Art Sensor Attributes

• art_mode — current Art Mode state
• content_id — artwork content ID
• content_type — artwork category
• thumbnail_url — local URL to the thumbnail (if downloaded)

---

Services

Standard TV Services

These are called on the media_player entity.

Service	Description
media_player.turn_on	Turn on the TV (WOL or SmartThings)
media_player.turn_off	Turn off the TV
media_player.volume_up/down	Adjust volume
media_player.mute_volume	Mute/unmute
media_player.set_volume_level	Set volume level (0.0–1.0)
media_player.select_source	Switch input source or launch an app
media_player.play_media	Send a key command or launch a URL
samsungtv_smart.select_picture_mode	Change picture mode
remote.send_command	Send raw key commands (via remote entity)

Sending key commands via play_media:

action: media_player.play_media
target:
  entity_id: media_player.samsung_tv
data:
  media_content_type: send_key
  media_content_id: KEY_MUTE

---

Frame Art Services

These services require a Samsung Frame TV with Art Mode. They are called on the media_player entity.

Service	Description
samsungtv_smart.art_get_artmode	Get current Art Mode status
samsungtv_smart.art_set_artmode	Enable or disable Art Mode
samsungtv_smart.art_available	List all available artworks (optionally filtered by category)
samsungtv_smart.art_get_current	Get info about the currently displayed artwork
samsungtv_smart.art_select_image	Display a specific artwork by content ID
samsungtv_smart.art_upload	Upload a local image to the TV
samsungtv_smart.art_delete	Delete a user-uploaded artwork (MY-* IDs only)
samsungtv_smart.art_get_thumbnail	Download a single artwork thumbnail
samsungtv_smart.art_get_thumbnails_batch	Batch-download thumbnails for multiple artworks
samsungtv_smart.art_set_brightness	Set Art Mode brightness (0–100, mapped to TV scale 1–10)
samsungtv_smart.art_get_brightness	Get current Art Mode brightness
samsungtv_smart.art_change_matte	Change the matte/frame style of an artwork
samsungtv_smart.art_set_photo_filter	Apply a photo filter to an artwork
samsungtv_smart.art_get_photo_filter_list	List available photo filters
samsungtv_smart.art_get_matte_list	List available matte styles
samsungtv_smart.art_set_favourite	Add/remove artwork from favourites
samsungtv_smart.art_set_slideshow	Configure slideshow (duration, shuffle, category). Alias of art_set_auto_rotation — auto-routed to whichever API the TV speaks
samsungtv_smart.art_set_auto_rotation	Configure auto-rotation (duration, shuffle, category). Alias of art_set_slideshow — works on older Frames that don't support the slideshow API

Service Examples

Select an artwork:

action: samsungtv_smart.art_select_image
target:
  entity_id: media_player.samsung_frame
data:
  content_id: SAM-F0206
  show: true

Upload a local image:

action: samsungtv_smart.art_upload
target:
  entity_id: media_player.samsung_frame
data:
  file_path: /config/www/my_art.jpg
  matte_id: modern_apricot
  file_type: jpg

Batch download thumbnails:

action: samsungtv_smart.art_get_thumbnails_batch
target:
  entity_id: media_player.samsung_frame
data:
  category_id: MY-C0002
  favorites_only: false
  force_download: false

Configure slideshow:

action: samsungtv_smart.art_set_slideshow
target:
  entity_id: media_player.samsung_frame
data:
  duration: 15min
  shuffle: true
  category_id: 2

Note on Frame generations. The slideshow feature uses different underlying APIs depending on firmware: newer Frames (2024+) use slideshow_status, while older Frames (≈2020–2021) only support auto_rotation_status. The integration detects which one your TV speaks on first use and routes automatically, so art_set_slideshow and art_set_auto_rotation are interchangeable aliases — use either. duration accepts the presets (3min, 15min, 1h, 12h, 1d, 7d) or any integer number of minutes (e.g. 30, 180); some models reject values outside their supported set.

---

Frame Art Mode

Overview

Frame TVs can display artwork when not in use. This integration provides full programmatic control over the Art Mode, including artwork selection, brightness, matting, filters, and slideshow settings.

Content IDs

Artworks are identified by content IDs:

Prefix	Source
SAM-*	Samsung Art Store content
MY_F*	User-uploaded photos
MY-C*	Categories (MY-C0002=My Photos, MY-C0004=Favorites, MY-C0008=All)

Matte Styles

Format: type_color

⚠️ Available matte types and colors are retrieved dynamically from your TV at startup and vary by model and firmware. The select.samsung_*_matte_type and select.samsung_*_matte_color entities are populated automatically with the options your TV actually supports. Call samsungtv_smart.art_get_matte_list to see the full list for your device.

Example (QE55LS03D 2024): modern_apricot, shadowbox_polar

Photo Filters

Available filters: none, mono, original, ink, watercolor, oil, pastel, posterize, noir, quartertone

Thumbnail Downloads

Thumbnails are automatically organized and saved to a per-TV directory keyed by the config-entry ID (new in v7 — see the v7 changelog for migration notes):

config/www/frame_art/{entry_id}/
├── current.jpg  ← currently displayed artwork
├── personal/    ← user-uploaded photos (MY-F*)
├── store/       ← Samsung Art Store (SAM-*)
└── other/       ← everything else

Find your {entry_id} on the sensor.<tv_name>_frame_art entity (Developer Tools → States) — it's exposed as the entry_id attribute, and the ready-to-use URL base is in thumbnail_folder.

These are accessible via Home Assistant's /local/ URL path, making them directly usable in Lovelace dashboards and galleries.

Smart caching: thumbnails are only downloaded once. Subsequent calls to art_get_thumbnail or art_get_thumbnails_batch skip files that already exist, making batch operations fast on repeat runs. Use force_download: true to override.

Resilient current.jpg: if a live thumbnail fetch for the current artwork fails (a transient TV/WebSocket hiccup), the integration reuses a previously downloaded copy of that artwork as current.jpg instead of showing an error placeholder. (Contributed by @prestonmcafee.)

See Also

• Frame Art Gallery Guide - Interactive Lovelace galleries
• Frame Art Guide - Complete service documentation

---

Automations & Tips

Wake-on-LAN with delayed command

Samsung TVs may need a moment to become responsive after WOL. Use a delay in automations:

automation:
  - alias: "Turn on TV and switch to HDMI 1"
    trigger:
      - platform: ...
    action:
      - service: media_player.turn_on
        target:
          entity_id: media_player.samsung_tv
      - delay: "00:00:08"
      - service: media_player.select_source
        target:
          entity_id: media_player.samsung_tv
        data:
          source: HDMI 1

Preventive maintenance (integration reload)

To prevent WebSocket connection saturation over time, you can schedule a periodic reload:

automation:
  - alias: "Reload SamsungTV integration nightly"
    trigger:
      - platform: time
        at: "03:00:00"
    action:
      - service: homeassistant.reload_config_entry
        target:
          entity_id: media_player.samsung_tv

Art Mode automation on TV off

automation:
  - alias: "Enable Art Mode when TV turns off"
    trigger:
      - platform: state
        entity_id: media_player.samsung_frame
        to: "off"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.samsung_frame_art_mode

---

Troubleshooting

Integration not appearing in Add Integration

Custom integrations installed via HACS do not appear under branded groups (e.g. "Samsung") in the Add Integration search. Use the badge in Integration Setup to open the config flow directly, or search for samsungtv (not samsung) in the search box.

If the config flow still fails with "This integration cannot be added from the UI", the most likely cause is that the integration files are missing from disk despite HACS showing it as installed — a known issue when migrating from ollo69 (same domain, same folder name).

Verify files are present:

ls /config/custom_components/samsungtv_smart/

If the folder is missing or empty, use HACS → SamsungTV Smart → ⋮ → Redownload, select the version explicitly, then restart Home Assistant.

If the folder exists but the flow still fails, enable DEBUG logging and check for errors on startup:

# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.samsungtv_smart: debug

TV not found during setup

• Make sure the TV is on and connected to the same network as Home Assistant.
• Ensure the TV's IP address is correct and reachable (ping <ip>).
• Disable any VLANs or firewall rules blocking ports 8001 and 8002.

TV accepts pairing but integration shows unavailable

• The first pairing token is stored in the config entry. If the token is rejected, delete the integration and re-add it — the TV will prompt again for pairing.
• Make sure you Accept the pairing request on the TV screen within the timeout window.

WebSocket connectivity issues / TV becomes unresponsive

Samsung TVs have strict limits on simultaneous WebSocket connections. If the integration creates too many connections without properly closing them, the TV's SmartThings service can become saturated.

Signs of this issue:

• TV stops responding to commands
• Logs show repeated WebSocketProtocolException or connection refused errors
• Issue resolves temporarily after a TV restart

Mitigations built into this fork:

• Proper handling of invalid WebSocket close opcodes
• Active connection cleanup to prevent zombie connections
• Use the nightly reload automation above as a preventive measure.

Recurring "IP Control state read failed" / "Host is unreachable" errors

If your log shows repeated errors like this, spaced minutes apart, for a TV that is otherwise powered on and working:

Error fetching IP Control state <name> data: IP Control state read failed:
transport failure talking to <ip>:1516: [Errno 113] Host is unreachable
Error fetching IP Control state <name> data: IP Control state read failed:
transport failure talking to <ip>:1516: timed out

These are network-layer errors (the TV briefly becomes unreachable at the IP level), not something the integration can retry around — it just means the TV's network connection dropped for a moment.

The most common cause is a DHCP lease renewal hiccup: even with a DHCP reservation, a short or unstable lease can cause brief unreachability when it renews. The fix is to configure a fully static IP on the TV itself instead of relying on a router-side reservation:

• On the TV: Settings → General → Network → Network Status/Settings → IP Settings → Manual, and enter the IP, subnet, gateway and DNS yourself.

This removes DHCP renewal from the equation entirely. If the errors persist after switching to a static IP, also check the network switch port the TV is plugged into (port resets, re-negotiation, rising CRC/error counters point to a cabling/port issue rather than the integration).

"Host is unreachable" / connection-failure logs only when the TV is OFF

If the errors above happen only while a TV is powered off (and stop once it's on), this is expected behaviour for some Frames — not a bug or a network problem.

Older Frames (notably the 2020 and 2021 models) drop off the network entirely in standby: their network chip powers down, so they stop answering everything incoming — ping, IP Control (port 1516) and the Art WebSocket. From the integration's side that's indistinguishable from "the TV is simply off", so a read failure there just means the TV is off. (2024+ Frames keep their network interface alive in standby and still answer a ping, so they don't show this.)

You can confirm which case you have: with the TV off, ping <tv-ip> from any machine. No reply → that TV goes fully off the network in standby, and the off-state log lines are normal.

Recent versions already keep this quiet: while a TV is off, IP Control transport failures and Art channel connection failures are logged at DEBUG (with at most a single INFO line), not ERROR/WARNING — so real problems still stand out.

"Then how does Home Assistant turn it back on if it's off the network?" — it doesn't reach the TV, it pushes a wake signal, and neither path needs the TV to be reachable:

• SmartThings (cloud): even in deep standby the TV keeps an outbound connection to Samsung's cloud (an always-on part, separate from the main network stack). The power-on command goes to the SmartThings cloud, which pushes it down that channel.
• Wake-on-LAN: the network card's WoL engine listens for a magic packet at the Ethernet level even while the OS network stack is down; a magic packet expects no reply, so it works on a TV that won't answer a ping.

Set the wake method per TV with the Power On Method option (Wake-on-LAN by default; SmartThings or IP Control also available).

SmartThings features not working

• Verify your API key/token has Devices permissions.
• Check that your TV is registered and visible in the SmartThings app.
• For OAuth2: confirm your Developer Portal app is still active and has the correct scopes (r:devices:*, x:devices:*).

OAuth2 — "Token refresh failed"

If the SmartThings OAuth token can no longer be refreshed, the integration raises an alert in Settings → Repairs ("SmartThings authentication failed for …") explaining the cause and pointing you to the fix. The alert clears automatically once authentication is restored. To recover:

1. Check internet connectivity from Home Assistant.
2. Verify your OAuth app is still active by running smartthings apps in the SmartThings CLI.
3. Re-authenticate: go to Settings → Devices & Services → Samsung TV Smart → Reconfigure.

A refresh token can become invalid if it is revoked, expires, or is rotated by SmartThings (which can happen after repeated re-authentication). Reconfiguring issues a fresh token pair.

Source list empty on Frame 2024 TVs

The SmartThings supportedInputSources attribute returns empty on some 2024 Frame TV models. This fork automatically falls back to a REST API call (samsungvd.mediaInputSource) to retrieve the full source list with custom names. If sources still appear missing, check that SmartThings is properly configured and the TV is reachable.

Picture mode not updating after change

SmartThings caches the picture mode value. This fork automatically sends a refresh command after any setPictureMode call to force the TV to report the new value. If the select entity still shows a stale value, wait a few seconds for the next poll cycle.

Frame Art services not working

• These services require a Samsung Frame TV with Art Mode capability.
• Make sure the TV is on (not just in Art Mode).
• Check that port 8002 (encrypted WebSocket) is not blocked.

Art Mode fails briefly after TV wakes from standby

When the TV wakes from standby (e.g. via an automation), the WebSocket connection needs a short time to re-establish before the Art API becomes available. This is normal — the integration will self-recover within a minute. If you experience consistent failures in morning automations, add a 60–90 second delay after the TV turns on before triggering Art Mode commands.

IP Control reports Art Mode "on" when it isn't

Warning

Do not enable Enable IP Control Art Mode unless you know your firmware handles it correctly. On affected firmwares it can leave Art Mode completely broken (detection stuck/flickering, switching unreliable) — and the damage can persist at the TV level, requiring a factory reset to recover. This was observed on a QE55LS03D with firmware 2123. The option is off by default; leave it off and use the WebSocket / Frame Art path, which is unaffected. Power on/off over IP Control is a separate setting and is not impacted.

On some Frame TVs the local IP Control (JSON-RPC, port 1516) artModeControl flag can wedge "on": it keeps returning artModeOn even when the TV is on a real input (e.g. HDMI), so art_mode_status is reported as on permanently or flickers between on and off. The flag is wrong at the source — the same value is returned even when querying the TV directly, outside Home Assistant. The actual panel state in that situation is given by getTVStates.pictureMode (Ambient only while art is really on the panel).

This typically appears after a TV factory reset and re-pairing of the IP Control channel, and looks like a TV firmware fault.

Workarounds, in order of preference:

1. Disable Art Mode over IP Control. Under Reconfigure → IP Control, turn Enable IP Control Art Mode off (this is the default). Art Mode detection and switching then fall back to the WebSocket / Frame Art channel, which is unaffected. Power on/off over IP Control (Enable IP Control / the IP Control power-on method) keeps working — only the Art Mode path is disabled.
2. Factory reset the TV. If you need IP Control for Art Mode and the flag is wedged, the only known way to clear the stuck artModeControl flag on the TV side is a factory reset of the TV (Settings → General → Reset), followed by re-pairing. There is no remote/API command that unsticks it.

Once a firmware update reports artModeControl correctly again, you can re-enable Enable IP Control Art Mode under Reconfigure → IP Control.

---

Credits

This project was a fork of ollo69/ha-samsungtv-smart, itself based on work by @jaruba and @screwdgeh.

Frame Art API based on xchwarze/samsung-tv-ws-api (art-updates branch), with contributions from Matthew Garrett and Nick Waterton.

WebSocket library: websocket-client / Xchwarze.

Special thanks to @PrestonMcAfee and @potatosalad for extensive real-world testing across multiple TV generations and detailed bug reports — many of the 8.0.0 reliability fixes exist because of their feedback.

---

Licensed under the GNU Lesser General Public License v2.1.