<!-- Markdown copy of https://freshavlabs.com/docs/token-control-for-samsung-displays/ -->

PLUGIN MANUAL / v2.6.4

# Token Control for Samsung Displays

Q-SYS user plugin for Samsung BE Series commercial displays. Token-authenticated WebSocket control with Wake-on-LAN, an on-panel Setup page, and automatic pairing.

## 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.

Automatic Pairing

Approve the prompt on the display once. The plugin stores the token itself.

Power Control

Power Toggle with Wake-on-LAN, for a display in standby.

Full Remote

D-pad, number keys, system and media keys, input list and any custom key code.

On-Panel Setup

Connection, pairing and export/import are live controls on the Setup page.

## 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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#power-control) |
| License         | One activation code per Core. See [Licensing](https://freshavlabs.com/docs/token-control-for-samsung-displays/#licensing)                                                               |

## 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 |

Step 1. Copy the plugin files

Copy each `.qplugx` file into `Documents\QSC\Q-Sys Designer\Plugins\`. A subfolder works; Designer scans the folder recursively. Double-clicking a file also installs it, into the Plugins folder itself. The plugin appears in Schematic Elements under Plugins, Fresh AV Labs.

Step 2. Add it to the design

Drag the plugin from Schematic Elements into the design.

Updating

Every release uses the same filename. Copy the new file over the old one. When you open the design, Designer offers the newer version, and the plugin's settings survive the update.

## Quick Start

Step 1. Enter the display's IP address

Select the plugin and open its Setup page. In the CONNECTION card, type the display's address into IP Address. Leave Device Name, MAC Address and Use SSL at their defaults.

Step 2. Turn the display on

Make sure the display is on and reachable, with IP Remote enabled. The display's own screen shows its picture or home screen, not standby.

Step 3. Push the design

Push the design to the Core. The plugin connects on its own, and the Status banner reads `Initializing - Connecting to <ip>`. The LICENSE box counts down, or reads `ACTIVATED`. Without a code the plugin runs a 10-minute demo, see [Licensing](https://freshavlabs.com/docs/token-control-for-samsung-displays/#licensing).

Step 4. Approve the prompt on the display

The display shows a prompt with the Device Name. Select Allow with the display's remote.

Step 5. Confirm the pairing

The Pairing status reads `Token stored - paired`, the Connected LED lights, and the Status banner reads `OK`. See [Display Pairing](https://freshavlabs.com/docs/token-control-for-samsung-displays/#pairing).

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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#power-control).

## Plugin Properties

The connection settings are controls on the Setup page, not properties, see [Setup Page](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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.                                                                                        |

## 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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#re-pairing).                                                                |
| Not Present  | `Display in standby`                                                | The display reports standby.                                                                                                  | None if it was turned off on purpose. To wake it, see [Power Control](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#re-pairing).

## 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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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`.

Step 1. Clear the token

On the Setup page, delete the contents of Auth Token. The Pairing status reads `No token - will request pairing`, and the display shows a new pairing prompt.

Step 2. Approve the prompt

Select Allow on the display. The Pairing status reads `Token stored - paired`.

## Licensing

The plugin reads `Activation_Code` and `Activation_Code_Backup` when the design starts.

Three license states

1. **Blank.** The plugin runs a 10-minute demo with every function. The LICENSE box counts down. Restart the design to start another demo.
2. **Valid code.** The LICENSE box reads `ACTIVATED`. There is no time limit.
3. **Wrong code.** The plugin runs the same demo and the LICENSE box reads `DEMO (invalid code): M:SS remaining`, so a mistyped code is visible. Correct or clear the code before the demo ends.

### 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

Step 1. Read the Core's Locking ID

Set `Show_Locking_ID` to Yes and push the design. The Locking ID appears in the LOCKING ID box. Core Manager also shows it under Licensing, for any Core, with no design change. The Designer emulator reports `EMULATOR` or `*100000000000000`. The plugin marks it as not a Core ID. No code can be made for it.

Step 2. Get a code for that Locking ID

Buy or request an activation code at [freshavlabs.com](https://freshavlabs.com), quoting the Locking ID exactly.

Step 3. Enter the code and push the design

Paste the code into `Activation_Code` and push the design. The LICENSE box reads `ACTIVATED`. The plugin compares only the digits of the code, so punctuation and spaces do not matter. A code entered on a running design applies at the next design start.

Redundant Core pairs

Each Core has its own Locking ID and needs its own code. Put the primary Core's code in `Activation_Code` and the backup Core's code in `Activation_Code_Backup`. Read the backup Core's Locking ID from its own Core Manager; no failover is needed. Either code matching the running Core licenses the plugin, so a failover stays licensed.

### 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.

Codes are bound to one Core

An activation code works only on the Core whose Locking ID it was made for. It cannot move to another Core.

## 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. |

How Power Toggle wakes a display

The plugin sends `KEY_POWER` only when the Connected LED is on. Displays wake in one of two ways. A display that keeps its control channel open in standby wakes on `KEY_POWER` alone, in about 4 seconds. The tested BE43 does this with its Power On with Mobile setting on, and it ignored Wake-on-LAN. A display that closes its channel in standby can be woken only by the Wake-on-LAN packet. If the display is already on, it ignores Wake-on-LAN and `KEY_POWER` sends it to standby.

If the control channel is not open when you press Power Toggle, the plugin also retries the connection 10 seconds later. The other controls respond soon after the display wakes.

Wake-on-LAN Requirements

Three conditions are necessary for Wake-on-LAN. The MAC Address field on the Setup page must contain the MAC address of the display. If the field is empty, the plugin gets the address from the display and writes it into the field. Wake-on-LAN must be on in the network menu of the display. The Q-SYS Core and the display must be in the same broadcast domain, because a router usually stops WOL packets.

## 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.                                                                              |

## 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 |

## 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.

## 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     |

## 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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#input-sources).

## 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      |

## Troubleshooting

A symptom that prints a Status banner message is covered in the [Status banner](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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](https://freshavlabs.com/docs/token-control-for-samsung-displays/#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.

## Support

* Support tickets: [freshavlabs.com/support](https://freshavlabs.com/support/)
* Website: [freshavlabs.com](https://freshavlabs.com)
* Email: <support@freshavlabs.com>

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