Samsung TV (Pro / newer Tizen)

Newer Samsung Tizen TVs — and Samsung's commercial "Pro" / hospitality sets — accept control over an HTTPS token API on port 1516. GEM enrolls once to get a long-lived access token, then sends remote-key and direct-control commands over that secure channel. One TV becomes one GEM device, and commands target that device directly (this driver creates no zones).

This is the driver to reach for when the older Tizen WebSocket path (the Samsung TV (Tizen WebSocket) driver, port 8002) won't pair on a newer set.

Three things to know before you start:

• Pairing is a command you run, not an automatic prompt. Unlike the WebSocket driver, this one does not pop the allow-prompt by itself on connect. You add the device, then run the pair command once and accept the on-screen prompt on the TV. GEM stores the returned token and from then on connects on its own. Until a token exists, the device stays idle — it won't poll or send keys.
• Power-on is Wake-on-LAN. The HTTPS API answers reliably only while the TV is awake. GEM wakes a sleeping TV by sending a Wake-on-LAN packet to its MAC address, so the MAC is required for cold power-on (see the power section for the exact attribute to set).
• GEM polls for live status. While the TV is on, GEM reads volume, mute, input, and power every few seconds and reports them back, so a touchpanel and any triggers stay in sync.

Which Samsung driver?

Samsung ships several control protocols, and GEM has a driver for each:

• Samsung TV (Pro / newer Tizen) (this page) — HTTPS token API on 1516, for newer Tizen and Pro/hospitality sets.
• Samsung TV (Tizen WebSocket) — the WebSocket remote API on 8002, for most consumer Tizen smart TVs.
• Samsung MDC — the MDC serial/IP protocol used by Samsung commercial displays and signage.
• Samsung TV (Serial-over-IP) (samsung_tv_serial) — 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, this Pro driver is the recommended fallback. If you're not sure which the TV speaks, start with the WebSocket driver, and switch here if pairing fails.

What's controlled

• Power — power_on (Wake-on-LAN + power-on request), power_off, and a raw power toggle key.
• Volume and mute — step the volume up/down, and discrete mute on / off / toggle.
• Inputs — jump to HDMI 1–4.
• Navigation and keys — the full directional pad, menu/exit/return, transport keys (play, stop, rewind, fast-forward), the numeric keypad, dash, and caption.
• Art Mode — turn The Frame's Art Mode on or off.
• Live status feedback — GEM polls the TV every few seconds while it's on and reports power, volume, mute, current input, and the selected speaker, so a touchpanel and triggers stay in sync.

Prerequisites

• A Samsung Tizen TV on the same LAN as GEM, reachable by IP with no NAT between them. Give it a static IP or DHCP reservation so its address never moves.
• The TV reachable on TCP 1516 (some firmwares move control to 8002 — if so, set the port to match).
• The TV powered on during pairing — the enroll prompt only shows on a live screen.
• For Wake-on-LAN power-on: the TV's MAC address, and Wake-on-LAN ("Power On with Mobile" / "Network Standby") enabled on the TV. GEM and the TV must share the same broadcast segment.

Setup

1. Open Devices, add a device, and choose the Samsung TV (Pro / newer Tizen) 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.
   • HTTPS Port (optional) — defaults to 1516. Change it only if the TV's firmware uses a different control port (some use 8002).
   • MAC Address (optional) — for Wake-on-LAN power-on. See the power section below for the exact attribute the wake packet reads.
3. Save and enable the device.
4. Pair the TV. With the TV on, open the Script Console and run the pair command against this device:

   await gem.command({device: <device_id>, action: 'pair'});

   The TV shows a remote-access prompt — accept it with the TV remote within about 30 seconds. On success GEM stores the token in the read-only Saved Auth Token attribute and starts polling the TV automatically. (You can also run pair from System → Commands.)
5. Verify. Run a quick status read and a harmless key:

   await gem.command({device: <device_id>, action: 'get_status'});
   await gem.command({device: <device_id>, action: 'mute_toggle'});

   get_status should report the TV's current power, volume, mute, and input.

Once paired, you should not have to re-enroll unless the token is cleared or a factory reset / firmware change invalidates it — in which case run pair again.

Power on, and the Wake-on-LAN limitation

The HTTPS API answers reliably only while the TV is awake, so power behaves like the other network TV drivers:

• power_off sends the power-off request — it works any time the TV is on.
• power_on sends a power-on request and a Wake-on-LAN "magic packet" to the TV's MAC. From a cold (asleep) TV, the wake packet is what actually turns it on; without a MAC, power_on reports a missing-MAC error and the TV stays off.
• power sends a raw power toggle key. Like a toggle on any of these TVs, it only acts while the TV is already on — don't rely on it to wake a sleeping set. Use the explicit power_on / power_off pair in room-on / room-off macros.

warning

Wake-on-LAN reads the mac_address attribute

The device form's MAC Address field stores the MAC under the attribute name mac, but the Wake-on-LAN power-on path reads the MAC from an attribute named mac_address. For dependable cold power-on, add an attribute named exactly mac_address to the device (open the device's Attributes, add mac_address, value type string, set it to the TV's MAC, e.g. AA:BB:CC:DD:EE:FF). Without mac_address, power_on returns a "missing mac address" error from a cold start.

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. 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 and mute

• Stepping — volume_up and volume_down nudge the TV's volume one step at a time. GEM tracks the level it last read and steps from there.
• Mute — this driver has discrete mute_on, mute_off, and mute_toggle, so a mute button works directly without any emulation.

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 its volume device to this TV. 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 audio output away from its own speakers so you aren't fighting two volume controls.

Setting an absolute volume level isn't wired on this driver

A volume command appears in the device's command list, but on this driver it currently does nothing (it returns an "unknown command" error). Use volume_up / volume_down to change volume. The current level is still read back into the volume attribute for display.

Inputs

hdmi_1 through hdmi_4 jump straight to those HDMI inputs. GEM reads the TV's current input back into the input attribute (reported as hdmi_1, hdmi_2, …) so a touchpanel can show which source is live.

Navigation, keys, and transport

Named remote keys are available as commands and behave exactly like pressing the matching button on the Samsung remote:

• Directional pad — up, down, left, right, enter.
• Navigation — menu, exit, return.
• Transport — play, stop, rewind, fast_forward.
• Numeric keypad — 0–9, plus dash and caption.

To tune a specific channel, send the digits as keypad commands (1, 2, …) followed by enter.

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 channel. GEM reflects the result in the art_mode attribute.

Status feedback

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

• power_state — on or off.
• volume — the TV's current volume level.
• mute_state — on or off.
• input — the current input (e.g. hdmi_1).
• speaker_select — the TV's selected speaker / audio output.

These keep a touchpanel's readouts live and can be used as trigger conditions — for example, fire a macro when the TV turns on. See Triggers. To change the poll cadence, set the optional status_interval attribute (milliseconds; default 5000).

Polling pauses while the TV is off

Status polling only reads the TV when GEM already believes it is on. If someone powers the TV on with the physical remote, GEM won't notice until the next command or until you run get_status. Driving power through power_on / power_off keeps GEM's power_state accurate.

Attributes

Device — required

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

Device — optional

Attribute	Type	Description
port	int	HTTPS control port. Default 1516; some firmwares use 8002.
mac	string	MAC field on the device form. Stored for reference. Note: the Wake-on-LAN path reads mac_address, not this — see below.
mac_address	string	The MAC the Wake-on-LAN power_on actually uses. Add this attribute (string) for cold power-on.
token	string (secure, read-only)	The HTTPS access token. Stored automatically after pair; you don't enter it. Clear it to force re-pairing. (A token put in a password attribute is also accepted.)
status_interval	int	Status poll interval in milliseconds. Default 5000.
default_volume	int	Starting volume assumed for the first volume_up / volume_down if GEM hasn't read a level yet. Default 20.

Device — status (set automatically)

Attribute	Type	Description
power_state	string	on / off.
volume	int	Current volume level.
mute_state	string	on / off.
input	string	Current input, e.g. hdmi_1.
speaker_select	string	Selected speaker / audio output.
art_mode	string	on / off (Art-Mode TVs).

note

Samsung Pro 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.

Setup and status

Command	Action
pair	Enroll with the TV and store an access token. Run once at commissioning (TV must be on).
get_status	Read power, volume, mute, input, and speaker now.

Power

Command	Action
power_on	Power-on request + Wake-on-LAN to mac_address.
power_off	Turn the TV off.
power	Raw power toggle key — only acts while the TV is on.

Volume and mute

Command	Action
volume_up / volume_down	Step the TV volume up / down.
mute_on / mute_off / mute_toggle	Mute on, off, or toggle.
volume (arg volume)	Not implemented on this driver — returns an error. Use volume_up / volume_down.

Inputs

Command	Action
hdmi_1 … hdmi_4	Jump to HDMI input 1–4.

Navigation, keys, and transport

Command	Action
up down left right enter	Directional pad and select.
menu exit return	Standard navigation keys.
play stop rewind fast_forward	Transport keys.
0–9 dash caption	Numeric keypad, dash, and caption.
back pause	Not implemented on this driver — return an error. Use return for back and the transport keys for playback.

Art Mode

Command	Action
art_mode_on / art_mode_off	Turn The Frame's Art Mode on / off.

Channels

Command	Action
channel (args tuner, major, minor)	Not implemented on this driver — returns an error. Tune by sending digit keys 0–9 then enter.

Known limitations

• Pairing is manual. You must run pair once (TV on) and accept the on-screen prompt; the driver doesn't enroll automatically on connect. Until a token exists, the device is idle.
• Power-on is Wake-on-LAN only, and the wake packet reads the mac_address attribute (not the form's mac field). Add mac_address for cold power-on, or use an IR blaster as a fallback.
• power (the raw toggle key) won't wake a sleeping TV. Use power_on / power_off.
• Absolute volume, channel, pause, and back aren't wired on this driver and return an error — use the step / digit / return alternatives noted above.
• Status can go stale if the TV is powered on by its physical remote, since polling only runs while GEM believes the TV is on. Drive power through GEM, or run get_status.
• 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
pair times out	The TV must be on. On some models the allow-prompt is hidden under Settings → External Device Manager — power-cycle and re-run pair, accepting within ~30 seconds.
Commands return TLS / certificate errors	The TV uses a self-signed certificate, which GEM expects and does not pin. If a firmware update moved control to port 8002, set the HTTPS Port attribute to 8002 and reconnect.
Device does nothing after saving	It isn't paired yet. Run the pair command (TV on) — until a token is stored, the driver stays idle.
power_on does nothing	Confirm a mac_address attribute holds the TV's MAC, Wake-on-LAN is enabled on the TV, and the TV and GEM share the same subnet. Verify the magic-packet path with a network sniffer if needed.
Volume slider has no effect	Absolute volume isn't wired on this driver — use volume_up / volume_down.
Power/volume readout is stale	Confirm the device is enabled and paired; polling runs about every 5 seconds while the TV is on. If the TV was turned on by its remote, run get_status.
Pairing won't take at all	The TV may speak a different protocol — try the Samsung TV (Tizen WebSocket) driver (port 8002), or Samsung MDC for a commercial display.

See also

• Samsung TV (Tizen WebSocket) — the WebSocket driver for most consumer Tizen TVs.
• Samsung MDC — Samsung commercial display / signage control.
• 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.
• Script Console — where you run the one-off pair command.
• Triggers — fire automations on the TV's power, volume, or input state.