Samsung TV (Tizen WebSocket)

Samsung Tizen smart TVs (the consumer "smart TV" line) are controlled over Samsung's Tizen WebSocket remote API on port 8002 — the same protocol Samsung's SmartThings remote uses. One TV becomes one GEM device, and commands target that device directly (this driver creates no zones).

Three things to know before you start:

• Pairing, not a password. The first time GEM connects, the TV pops a remote-access prompt on screen asking to allow a controller named GEM, and someone must accept it with the TV remote. GEM stores the resulting access token automatically — you never type it in.
• Power-on is Wake-on-LAN. The WebSocket API only answers while the TV is on, so there is no protocol "turn on" once the TV is asleep. GEM powers the TV on by sending a Wake-on-LAN packet to its MAC address, which is why the MAC is needed for cold power-on.
• Volume goes over a second path. Step commands (volume_up / volume_down) and mute are sent as remote keys over the WebSocket, but a fixed volume level (set_volume / get_volume) is set and read over the TV's built-in UPnP service on port 9197. Both run to the same TV; just know they are two different mechanisms when you troubleshoot.

Which Samsung driver?

This Tizen WebSocket driver fits most consumer Samsung smart TVs. Two siblings exist for cases it doesn't cover: samsung_tv_pro for newer/Pro Tizen models that use the HTTPS token-pairing API on port 1516, and samsung_tv_serial for control over the TV's RS-232 service port through a serial-to-IP adapter. If WebSocket pairing won't take on a newer set, try the samsung_tv_pro driver instead.

What's controlled

• Power — on (via Wake-on-LAN) and off.
• Volume and mute — a fixed volume level (0–100), volume up/down, and mute-toggle.
• Inputs — jump to HDMI 1–4, or open the on-screen source menu.
• Apps — launch any installed app by its Samsung app id, and list what's installed.
• Navigation and keys — the full directional pad, menu/guide/exit/home/back, channel up/down, and any Samsung remote key by name (with optional press-and-hold).
• Art Mode — turn The Frame's Art Mode on or off.
• Live status feedback — GEM polls the TV every few seconds and reports whether it's on, its current volume, and its mute state, so a touchpanel and triggers stay in sync.

Prerequisites

• A Samsung Tizen TV on the same LAN as GEM, reachable by IP (no NAT between them). Give it a static IP or DHCP reservation so its address never moves.
• Remote-access / IP control enabled on the TV — on most models this is Settings → General → External Device Manager → Device Connect Manager (turn on Access Notification so the allow-prompt appears) and/or Network → Expert Settings → Power On with Mobile. Exact menu paths vary by model year.
• Wake-on-LAN ("Power On with Mobile" / "Network Standby") enabled if you want power_on to work while the TV is off. Without it, GEM can control the TV when it's on but cannot wake it.
• The TV's MAC address — shown under the TV's network status, or on a label on the set.

Setup

1. Open Devices, add a device, and choose the Samsung TV (Tizen WebSocket) driver. It suggests the AV subsystem and a tv device type — accept those.
2. Fill in the fields:
   • TV IP Address (required) — the TV's LAN IP, e.g. 192.168.1.50.
   • MAC Address (optional but needed for power-on) — used for Wake-on-LAN, e.g. AA:BB:CC:DD:EE:FF.
3. Save and enable the device.
4. Accept the prompt on the TV. On the first connect the TV shows a remote-access request from a device named GEM — accept it with the TV remote. GEM stores the access token in the read-only Saved Auth Token attribute automatically; you should not have to re-accept unless that token is cleared or a firmware update invalidates it.

Once accepted, GEM begins polling the TV for availability, volume, and mute.

Power on, and the Wake-on-LAN limitation

The Tizen WebSocket API only responds while the TV is on. So:

• power_off sends the power-off key — it works any time the TV is on.
• power_on sends a Wake-on-LAN "magic packet" to the TV's MAC address. If the MAC is blank or wrong, or Wake-on-LAN is disabled on the TV, power_on does nothing. (If the TV happens to already be on, power_on also sends the power-on key, but the wake packet is what does the real work from a cold state.)
• power_toggle is not reliable for turning the TV on. Because the key channel only answers while the TV is on, a toggle sent to a powered-off TV is rejected. Use the explicit power_on (Wake-on-LAN) and power_off commands rather than power_toggle when you need dependable power control — for example in a room-on / room-off macro.

Wake-on-LAN is a local-subnet broadcast: the TV and GEM must be on the same network segment, with no router between them blocking the broadcast. As with most TVs, if reliable cold power-on is critical and Wake-on-LAN proves flaky, the standard fallback is a network-attached IR blaster sending the TV's IR power code.

Volume, mute, and the TV's own speakers

This driver controls volume two ways, and which one runs depends on the command:

• A fixed level — set_volume (or volume) with a level of 0–100, and get_volume to read it back — is sent over the TV's UPnP service on port 9197. This is what lets a touchpanel slider set "volume = 35".
• Stepping and mute — volume_up, volume_down, and mute_toggle — are sent as remote keys over the WebSocket, exactly as if you pressed the remote.

If the room's audio comes out of the TV's own speakers, make this TV the AV zone's volume device: open AV Zones, edit the zone, and set the Volume Device field to this TV. Volume and mute for that zone then route to the TV. Unlike some TVs, this driver has a native mute-toggle (it sends the remote MUTE key), so a mute button works directly without any emulation.

If the room audio instead comes from a receiver, amp, or soundbar, leave that device as the zone's Volume Device and set the TV's own audio output away from its speakers, so you aren't fighting two volume controls at once.

note

The fixed-level set_volume / get_volume path depends on the TV exposing UPnP rendering control on port 9197. Most Tizen TVs do, but if a particular model or firmware doesn't, those two commands fail while volume_up / volume_down / mute_toggle (the remote-key path) keep working. If a volume slider has no effect but step buttons do, that's the UPnP service being unavailable.

Inputs, apps, and channels

• Inputs. hdmi_1 through hdmi_4 jump straight to those HDMI inputs. source opens the TV's on-screen source list so a viewer can pick an input that isn't one of the four HDMI shortcuts.
• Apps. Run get_apps to list the apps installed on that specific TV along with their Samsung app ids, then pass an id to launch_app's app_id argument. The app id is not the on-screen name — it's a Samsung identifier (for example Netflix is 11101200001), so always read the real ids off the TV with get_apps rather than guessing. launch_app also accepts an optional app_type (defaults to DEEP_LINK) and meta_tag for deep-linking into specific content.
• Channels. channel_up and channel_down tune the TV's own tuner up and down.

Direct channel entry isn't wired up on this driver

A channel command appears in the device's command list, but on this WebSocket driver it currently does nothing (it returns an "unknown command" error). To tune a specific channel, send the digits as remote keys with send_key — KEY_1, KEY_2, … KEY_0 — followed by enter, or use channel_up / channel_down. Don't rely on the channel command here.

Sending raw remote keys

For anything not covered by a named command, use send_key with a key argument — it accepts a Samsung key name like VOLUP, KEY_VOLUP, or volup (GEM uppercases it and adds the KEY_ prefix if you leave it off). The driver knows the full Samsung remote key set — directional and color keys, KEY_TOOLS, KEY_INFO, KEY_CH_LIST, the numeric keypad KEY_0–KEY_9, picture/aspect keys, and many more. To press and hold a key (for menus that respond to a long press), use hold_key with key and a duration in milliseconds (default 2000).

Art Mode (The Frame)

On The Frame and other Art-Mode TVs, art_mode_on and art_mode_off switch Art Mode through Samsung's art-app channel.

The Frame and power-off

The Frame enters Art Mode when it receives power_off rather than fully powering down. To make power_off fully turn the panel off, disable Art Mode on the TV under Settings → General → Ambient/Art Mode.

Status feedback

While the device is enabled, GEM polls the TV about every 5 seconds and updates these read-only device attributes when they change:

• power_state — on or off, determined by whether the TV answers on its info port.
• volume — the TV's current volume level (read over UPnP).
• mute_state — on or off (read over UPnP).

These keep a touchpanel's volume readout and power indicator live, and they can be used as trigger conditions — for example, fire a macro when the TV turns on. See Triggers.

Attributes

Device — required

Attribute	Type	Description
ip	string	The TV's LAN IP address.

Device — optional

Attribute	Type	Description
mac_address	string	The TV's MAC address. Needed for Wake-on-LAN power_on.
token	string (secure, read-only)	The Tizen access token. Stored automatically after you accept the on-TV prompt; you don't enter it. Clear it to force re-pairing.

Device — status (set automatically)

Attribute	Type	Description
power_state	string	on / off, from the availability poll.
volume	int	Current volume 0–100.
mute_state	string	on / off.

note

Samsung Tizen TVs have no entries in the attribute autocomplete catalog, so when you reference these names in triggers or macros, type them exactly as shown.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons.

Power

Command	Action
power_on	Wake the TV via Wake-on-LAN to its MAC address.
power_off	Turn the TV off (Art Mode on The Frame — see above).
power_toggle	Toggle power — only acts while the TV is on; not reliable for power-on (see above).

Volume and mute

Command	Action
volume / set_volume (arg level)	Set the volume to a level 0–100 (over UPnP).
get_volume	Read the current volume (over UPnP).
volume_up / volume_down	Step the TV volume up / down (remote key).
mute_toggle	Toggle mute (remote MUTE key).

Inputs

Command	Action
hdmi_1 … hdmi_4	Jump to HDMI input 1–4.
source	Open the on-screen source/input list.

Navigation and keys

Command	Action
up down left right enter	Directional pad and select.
menu guide exit home back	Standard navigation keys.
send_key (arg key)	Send any Samsung remote key by name (e.g. KEY_TOOLS, KEY_INFO, KEY_0).
hold_key (arg key, duration)	Press and hold a key for duration ms (default 2000).

Channels

Command	Action
channel_up / channel_down	Tuner channel up / down.
channel (arg channel)	Not implemented on this driver — returns an error. Use digit keys via send_key instead (see above).

Apps and Art Mode

Command	Action
get_apps	List installed apps with their Samsung app ids.
launch_app (args app_id, app_type, meta_tag)	Launch an installed app by its Samsung app id.
art_mode_on / art_mode_off	Turn The Frame's Art Mode on / off.

Status

Command	Action
is_available	Report whether GEM currently sees the TV as on.

Known limitations

• Power-on is Wake-on-LAN only. Once the TV is fully off, the WebSocket API can't wake it — only the magic packet to the MAC can. Use an IR blaster as a fallback if cold power-on must be rock solid.
• power_toggle won't turn the TV on. The key channel only answers while the TV is on. Use explicit power_on / power_off.
• Direct channel entry (channel) isn't implemented on this driver — send digit keys with send_key instead.
• Fixed-level volume needs UPnP. set_volume / get_volume run over the TV's UPnP service on port 9197; if a model doesn't expose it, use the volume_up / volume_down step keys.
• Samsung changes the protocol across firmware. If pairing or commands stop working after a firmware update on a newer set, try the samsung_tv_pro driver (HTTPS token pairing on port 1516).
• Single device, no zones. A Samsung TV is one GEM device; it creates no zones. Group rooms and multi-room behavior at the AV-zone / macro layer.

Troubleshooting

Symptom	Check
The allow-prompt never appears / can't pair	Confirm remote-access / Device Connect Manager (Access Notification) is enabled on the TV, the TV IP is correct, and GEM is on the same LAN with no NAT. Some sets only show the prompt while the TV is on and not asleep.
Commands time out after a TV firmware update	The stored token can be invalidated by a firmware update. Clear the Saved Auth Token attribute and re-accept the on-TV prompt. If it still won't take, switch to the samsung_tv_pro driver.
power_on does nothing	Confirm the MAC Address is set correctly and Wake-on-LAN ("Power On with Mobile" / "Network Standby") is enabled on the TV. Confirm the TV and GEM share the same subnet.
power_off only dims The Frame to artwork	That's Art Mode. Disable Ambient/Art Mode on the TV to make power_off fully power down, or drive Art Mode explicitly with art_mode_on / art_mode_off.
Volume slider does nothing but step buttons work	The fixed-level path (UPnP, port 9197) isn't answering on that model — use volume_up / volume_down.
launch_app launches nothing	Run get_apps to enumerate installed app ids — the user-visible name (e.g. "Netflix") is not the app id.
Power/volume readout is stale	Confirm the device is enabled and connected; status polling runs about every 5 seconds.

See also

• AV Zones — make the TV a zone's Volume Device so volume and mute route to it.
• Devices — adding and configuring devices.
• Commands — running and scripting device commands.
• Triggers — fire automations on the TV's power, volume, or mute state.