Token Control for Samsung Displays

01.Introduction

Token Control for Samsung Displays controls a Samsung BE Series commercial display from a Q-SYS Core over the display's token-authenticated WebSocket API. It pairs with the display from its own Setup page, wakes the display with Wake-on-LAN, and sends every key on the display's remote.

02.Requirements

Component	Requirement
Q-SYS Designer	Tested with Q-SYS Designer 10.4
Q-SYS Core	A Core with WebSocket support
Samsung display	BE Series (Tizen OS) with IP Remote enabled, under Settings > All Settings > Connections > Network > Expert Settings. Tested on the LH43BEFHLGFXGO (BE43FX-H)
Network	TCP from the Core to the display: port 8002 (WSS) or 8001 (WS) for control, and 8001 (HTTP) for the power state and the MAC fill
Wake-on-LAN	Optional. Needed only to wake a display that closes its control channel in standby. See Power Control
License	One activation code per Core. See Licensing

03.Installation

The Token Control for Samsung Displays package contains one plugin file:

File	Purpose	License
Token_Control_for_Samsung_Displays.qplugx	The display controller	Licensed

04.Quick Start

For more than one display, add one plugin instance per display and pair each one once. One activation code covers every instance on a Core.

A display that goes quiet in standby is the most common support call, see Power Control.

05.Plugin Properties

The connection settings are controls on the Setup page, not properties, see Setup Page.

Property	Range / Choices	Default	Description
Activation_Code	Text	blank	The activation code for this Core's Locking ID. Leave blank to run the demo. See Licensing.
Activation_Code_Backup	Text	blank	The code for the other Core of a redundant pair. Leave blank on a single Core.
Show_Locking_ID	No / Yes	No	When Yes, shows the LOCKING ID box above the LICENSE box, in the Setup page header.
Debug_Level	Standard / Verbose	Standard	Standard logs startup, connections and errors. Verbose adds every WebSocket frame.

06.Setup Page

Editing IP Address, Device Name, Use SSL or Auth Token starts a new connection on its own, less than a second later.

Connection

Control	Default	Description
IP Address	blank	Required. IP address of the Samsung display.
Device Name	QSysRemote	The name the display shows in its pairing prompt.
MAC Address	blank	The display's MAC address, 12 hexadecimal digits, for Wake-on-LAN. When left blank, it fills from the display's first answer, on connect or on the 15-second power-state check. A value you enter yourself is never overwritten. Colons, hyphens, dots, spaces or no separators are all accepted. Used only to wake the display from standby: by Power Toggle, and by Auto Wake when it is on.
Use SSL	On	On: encrypted WebSocket (WSS) on port 8002. Off: unencrypted WS on port 8001, for a display that does not accept WSS.
Auto Wake	Off	Lets the reconnect loop wake the display. Read Auto Wake before you turn it on.
Connected LED / Reconnect	-	The LED lights while the display's control channel is open. A display in standby can accept the connection and still ignore every key, so the LED stays off until the channel opens. Reconnect starts a new connection attempt without pushing the design again.

Auto Wake

Auto Wake lets the plugin send Wake-on-LAN on its own when reconnects fail. It is off by default.

With Auto Wake on, the plugin sends a wake packet on the second failure in a row and on every failure after it. A failure is a dropped connection, or a reconnect attempt that errors, closes or times out before the display opens its control channel. The count starts again when the channel opens. Pressing Reconnect or Import also starts it again, as does editing IP Address, Device Name, Use SSL or Auth Token.

Auto Wake ignores the display's power state. It sends its wake packet even while the banner reads Not Present - Display in standby. With Auto Wake on, a display that closes its connection in standby is switched back on each time it is turned off. A display in standby that accepts the connection but never opens its control channel is also sent a wake packet on each reconnect.

Turn Auto Wake on only where the plugin must wake a display without anyone pressing Power Toggle. It also needs Wake-on-LAN to work: see the requirements under Power Control. With Auto Wake off and a MAC Address set, the debug console logs Auto-WOL skipped - Auto Wake is off (consecutive failures: 2) once each time reconnects start failing.

Status banner

Q-SYS prints the state first and the plugin's message after it, as in Not Present - Display in standby. OK prints alone. When two rows apply, the higher row wins.

State	Message	Cause	Remedy
Fault	License required - demo expired	The demo ended.	See Licensing.
Fault	No IP address configured	IP Address is empty, or holds a character other than a letter, digit, dot or hyphen.	Enter the display's IP address.
Fault	Unauthorized - clear Auth Token and reconnect	The display rejected the saved token. It clears when the channel opens, when you edit Auth Token or IP Address, or on Import.	Re-pair.
Not Present	Display in standby	The display reports standby.	None if it was turned off on purpose. To wake it, see Power Control.
OK	(none)	The control channel is open.	None.
Initializing	Connecting to <ip>	A connect attempt is running. An attempt still running after 30 to 45 seconds is replaced.	Wait.
Fault	Display refused connection - check TV remote access/port	The display refused the connection.	Check IP Remote on the display, and Use SSL.
Fault	Display on but control channel down - check remote access setting	The display answers but does not open its control channel.	Check IP Remote on the display. Approve a pairing prompt if one shows.
Fault	Display unreachable - check power/network	The connection failed and the display has not answered since.	Check the display's power and network.
Initializing	Initializing	No connect attempt yet: at start, or just after a setting changes.	Wait.
Fault	WebSocket API unavailable	The Core has no WebSocket support, so the plugin stopped at start.	See Requirements.

The plugin asks the display for its power state every 15 seconds. A display that turns its network off in standby cannot answer. Between reconnect attempts it reads Fault - Display unreachable - check power/network while it is off.

Export / Import

Export copies the connection settings (IP Address, Device Name, Auth Token, MAC Address, Use SSL and Auto Wake) into the read-only Exported JSON box as one JSON string. Paste a saved string into the Import box and press Import to apply it and reconnect. A string with no Auto Wake setting leaves Auto Wake as it is. Use this to copy a configuration to another instance.

A string carries its display's Auth Token and MAC Address. To use it with a different or replacement display, clear MAC Address after Import, then re-pair.

07.Display Pairing

The first time the plugin connects with no token, the display shows a prompt asking to allow the control system. When you approve it, the display sends a token. The plugin writes the token into Auth Token on the Setup page, where it is saved with the design and used on every later connection.

Two settings limit access to the credential this plugin stores:

• In Core Manager, under Access Management, turn on Access Control.
• If no external control system reads or drives this block, set its Script Access to Script.

Pairing status

The Pairing status line in the AUTH TOKEN card shows where the token stands.

Message	Meaning
No token - will request pairing	No token. The next connection shows the prompt on the display.
Token present	A saved token is loaded and is used on connect.
Token stored - paired	Pairing succeeded and the token was saved.
Token rejected - clear Auth Token field and re-pair	The display refused the saved token. See Re-pairing.

Re-pairing

A saved token stops working when the display is factory-reset or replaced, or when its pairing is revoked in the display's settings. The Status banner then reads Fault - Unauthorized - clear Auth Token and reconnect.

08.Licensing

The plugin reads Activation_Code and Activation_Code_Backup when the design starts.

What demo expiry stops

The licensed product is the remote. At expiry the plugin closes its connection to the display and stops reconnecting, and the Connected LED goes off. Every key on the Control page greys out, and a press from a pin sends nothing. The Setup page stays usable, so you can still edit the connection and export or import a configuration.

Activate

License status

Q-SYS prefixes the LICENSE box text with its own status word, so the box reads OK - ACTIVATED or Compromised - DEMO: 9:59 remaining.

Status	Color	Meaning
ACTIVATED	Green	A code validated against this Core. No time limit.
DEMO: M:SS remaining	Yellow	No code entered. Counting down.
DEMO (invalid code): M:SS remaining	Yellow	A code was entered and did not validate against this Core's Locking ID.
DEMO EXPIRED - Activation Required	Red	The demo ran out. "What demo expiry stops" above says what the plugin still does.

At expiry the plugin's Status control also reads Fault - License required - demo expired, so a Status Combiner sees the fault.

09.Power Control

Control	Function
Power Toggle	Sends Wake-on-LAN, then KEY_POWER 2 seconds later. KEY_POWER toggles the display; it is not a discrete power-on.

10.Volume Control

Control	Function
Vol - (pin Volume Down)	Lowers the volume one step. Hold to ramp at about five steps per second until you release.
Vol + (pin Volume Up)	Raises the volume one step. Hold to ramp at about five steps per second until you release.
Mute (pin Mute Toggle)	Toggles mute.

11.Navigation

Control	Function
Up / Down / Left / Right	Move in menus
Enter	Select the current item
Return	Go back one menu or screen
Menu	Open the display's main menu

12.Input Sources

Control	Function
Source	Opens the display's on-screen input list

To change input, press Source, move to the input with the D-pad, and press Enter. There is no button per input: on BE Series displays the discrete input key codes (KEY_HDMI1 and the rest) do not switch inputs reliably over this API.

13.Number, System & Media Keys

Number Keypad

Control	Function
0 - 9 (pins Num 0 - Num 9)	Sends KEY_0 through KEY_9, for channel entry, PIN codes and menu shortcuts

System Keys

Control	Function
Home	Go to the display's home screen
Info	Show the information overlay
Tools	Open the tools menu

Media Transport

Control	Function
Play	Play
Pause	Pause
Stop	Stop

14.Custom Keys

Send any Samsung remote key code.

Control	Function
Custom Key Code	The key code to send, such as KEY_EXIT
Send Key (pin Send Custom Key)	Sends the key code to the display

Common Key Codes

KEY_SOURCE                       - Open the input source list
KEY_HOME                         - Go to home screen
KEY_INFO                         - Display information overlay
KEY_MENU                         - Open the main menu
KEY_EXIT                         - Exit current menu
KEY_CHUP, KEY_CHDOWN             - Channel up/down
KEY_0 through KEY_9              - Numeric keys

For inputs, use KEY_SOURCE and the D-pad, not KEY_HDMI1, see Input Sources.

15.Control Pins

Status and Connection

Pin Name	Type	Direction
Status	Status	Output
Connected	LED	Output
License_Status	Status	Output
Locking ID	Text	Output
Token Display	Text	Output
Reconnect	Trigger	Both

Setup (Connection & Config)

Pin Name	Type	Direction
IP Address	Text	Both
Device Name	Text	Both
MAC Address	Text	Both
Auth Token	Text	Both
Use SSL	Toggle	Both
Auto Wake	Toggle	Both
Config Export	Text	Output
Config Import	Text	Both
Export / Import	Trigger	Both

Power

Pin Name	Type	Direction
Power Toggle	Trigger	Both

Audio and Navigation

Pin Name	Type	Direction
Volume Up / Down	Momentary	Both
Mute Toggle	Trigger	Both
Up / Down / Left / Right	Trigger	Both
Enter / Return / Menu	Trigger	Both
Source	Trigger	Both

Hold a Volume pin true to ramp, as with the panel button.

Number, System & Media Keys

Pin Name	Type	Direction
Num 0 - Num 9	Trigger	Both
Home / Info / Tools	Trigger	Both
Play / Pause / Stop	Trigger	Both
Custom Key Code	Text	Both
Send Custom Key	Trigger	Both

16.Troubleshooting

A symptom that prints a Status banner message is covered in the Status banner table.

Cannot connect to display

• Check IP Address on the Setup page, and that the display is on.
• Check that IP Remote is enabled on the display, under Connections > Network > Expert Settings.
• Check that port 8002 (WSS) or 8001 (WS) is open between the Core and the display.
• Try the other Use SSL setting.

Pairing prompt does not appear

• Clear Auth Token. A display that remembers an earlier pairing does not prompt again.
• Check Access Notification on the display, under Connections > Device Connect Manager. Set it to First Time Only.
• Change Device Name.

Token rejected

Follow Re-pairing.

Power Toggle does not wake the display

• Check the Connected LED. A display that keeps its channel open in standby wakes only on KEY_POWER, which needs the LED on. See Power Control.
• Clear MAC Address and press Reconnect, so the plugin fills in the MAC the display reports. A hand-entered MAC that differs from that report logs WOL may target the wrong interface.
• Check the three Wake-on-LAN requirements under Power Control.
• Check that the display is in standby, not unplugged.
• Wait 5 to 10 seconds after a wake before pressing Power Toggle again.

Display turns itself back on after being turned off

• Turn Auto Wake off. The debug console shows Auto-WOL: attempting wake packet each time it wakes the display.
• Do not clear MAC Address instead: the plugin fills it in again from the display.
• Do not turn Wake-on-LAN off on the display instead: Power Toggle then cannot wake a display that closes its channel in standby.

Keys are greyed out

The demo has expired, see What demo expiry stops.

Collecting a log

Set Debug_Level to Verbose to log every WebSocket frame. The auth token is redacted, so the log is safe to send.

17.Support

• Support tickets: freshavlabs.com/support
• Website: freshavlabs.com
• Email: [email protected]

Include with a request:

• Q-SYS Designer version
• Samsung display model
• Plugin version, shown under the plugin name in the header
• The Locking ID, for a license question
• Debug output captured with Debug_Level set to Verbose