PLUGIN MANUAL / v2.5.5
Samsung Token Control
Q-SYS user plugin for Samsung BE Series commercial displays. Token-authenticated WebSocket control with Wake-on-LAN.
01.Introduction
Samsung Token Control is a Q-SYS plugin that provides comprehensive control of Samsung BE Series commercial displays via WebSocket connection with token-based authentication. This plugin enables AV integrators to incorporate Samsung display control into their Q-SYS designs.
Token Authentication
Secure WebSocket (WSS) connection with persistent token storage for reliable communication.
Power Control
Turn display on/off with Wake-on-LAN support for remote power-on capability.
Full Navigation
Complete remote control emulation including menu navigation and input selection.
Custom Commands
Send any Samsung remote control key code for advanced control scenarios.
02.System Requirements
Minimum Requirements
| Component | Requirement |
|---|---|
| Q-SYS Designer | Version 9.0 or later |
| Q-SYS Core | Any Q-SYS Core processor with WebSocket support |
| Samsung Display | BE Series with WebSocket Remote Control API |
| Network | TCP/IP connectivity between Core and display |
| Port | 8002 (WSS) or 8001 (WS) |
Display Requirements
- Samsung BE Series Commercial Display
- Network connection (Ethernet or Wi-Fi)
- WebSocket Remote Control enabled in display settings
Optional
- Wake-on-LAN - required only if you need to power the display on from standby via the Power Toggle control. Not needed for sending remote-control keys to a display that's already on.
03.Installation
Download the Plugin
Download the Samsung_Token_Control_v2_5_4.qplug file from Fresh AV Labs or your authorized distributor.
Copy to Plugins Folder
Copy the plugin file to your Q-SYS Designer plugins directory:
Documents\QSC\Q-SYS Designer\Plugins\Restart Q-SYS Designer
Close and reopen Q-SYS Designer to load the new plugin.
Add to Design
Find "Fresh AV Labs~Samsung Token Control" in the Schematic Library under Plugins and drag it into your design.
04.Quick Start
First-time setup pairs the plugin with the display and stores the resulting authentication token in the design so the connection persists across restarts. The procedure requires two pushes to the Core because plugin Properties are locked while connected to a running Core: the first push triggers pairing, then you disconnect to paste the token into the Auth_Token property, and a second push locks it in.
Enter network details offline
With the design disconnected from the Core, select the plugin and open its Properties panel (upper-right area of the Q-SYS Designer window). Enter the display's IP_Address and MAC_Address.
Leave the display powered on
Make sure the Samsung display is powered on and reachable on the network. WebSocket Remote Control must be enabled in the display's settings.
Push the design to the Core
Click File > Save to Core & Run. The plugin connects to the display automatically on startup - no Reconnect click required.
Approve the pairing prompt on the display
A prompt appears on the display showing the configured Device_Name. Use the display's remote to select Allow. The display issues an authentication token, which the plugin shows in the Token Display control at the bottom of the plugin block.
Copy the token from Token Display
Copy the token string from the Token Display control on the plugin block.
Disconnect from the Core
Click File > Disconnect. Properties are locked while connected to a running Core - disconnecting lets you edit the Auth_Token property.
Paste into the Auth_Token property
Open the plugin's Properties panel and paste the token into the Auth_Token field.
Save to Core & Run again
Click File > Save to Core & Run a second time. The token is now persisted in the design, and the plugin will reconnect using it on every subsequent startup.
05.Plugin Properties
Configure the plugin by selecting the component and adjusting these properties in the Properties panel.
| Property | Default | Description |
|---|---|---|
Activation_Code | blank | License activation code. Leave blank to use 10-minute demo mode. |
Show_Locking_ID | No | When "Yes", displays the Core's Locking ID for license generation. |
IP_Address | blank | Required. IP address of the Samsung display. |
Device_Name | QSysRemote | Name shown on display when pairing. Customize to identify control system. |
Auth_Token | blank | Persistent authentication token. Displayed in the Token Display control during pairing - copy that value into this property and save the design so the connection persists across restarts. |
MAC_Address | blank | Required to wake display from standby. Display's MAC address for Wake-on-LAN. Used by the Power Toggle control. |
Use_SSL | Yes | Use secure WebSocket (port 8002). Set "No" for unencrypted (port 8001). |
Debug_Level | Standard | Console logging verbosity. Standard logs key events (startup, connections, errors). Verbose adds per-frame WebSocket TX/RX for deep troubleshooting. |
06.Licensing
The plugin recognizes three license states based on what's entered in the Activation_Code property:
Obtaining a License
Get Your Locking ID
Set the Show_Locking_ID property to "Yes". The Locking ID will appear in the plugin UI. This ID is unique to your Q-SYS Core.
Purchase a License
Visit freshavlabs.com and provide your Locking ID to generate an activation code.
Enter Activation Code
Enter the activation code in the Activation_Code property. The license status will show green "ACTIVATED" when valid.
License Status Indicators
| Status | Color | Meaning |
|---|---|---|
| ACTIVATED | Green | Valid license - full functionality enabled |
| DEMO: X:XX | Yellow | Demo mode active with time remaining |
| DEMO EXPIRED | Red | 10-minute demo timer ran out - activation required to unblock control commands |
| INVALID ACTIVATION CODE | Red | A non-blank value was entered but doesn't match this Core's Locking ID - control commands blocked. Verify the code matches the Locking ID on the displayed line, or clear the property to fall back to demo mode |
07.Display Pairing
Samsung BE-series displays use a one-time pairing handshake to establish trust with the control system. The display issues an authentication token on first approval, and the plugin must present that same token on every subsequent connection.
How Pairing Works
The first time the plugin connects to a display with no token, the display shows an on-screen prompt asking whether to allow the control system to connect. Once you approve, the display sends a token in its first WebSocket frame. The plugin surfaces that token in the Token Display control - a read-only output on the plugin block - so you can copy it into the Auth_Token property in the Properties panel. The token must live in the property, not just the control, for the pairing to survive a restart.
For the step-by-step procedure, see Quick Start.
Token Display vs. Auth_Token
These are distinct fields and the distinction matters during setup:
- Token Display - read-only control on the plugin block (visible at the bottom of the plugin in the schematic). Shows the current session's token. Cleared when the design restarts.
- Auth_Token - writable property in the Properties panel. Persists with the design. The plugin reads this value on startup and uses it to authenticate.
The setup procedure copies from Token Display into Auth_Token. Pasting it into the wrong place is the most common first-time mistake.
Re-pairing After Token Rejection
If a saved token stops working - because the display was factory-reset, the pairing was revoked from the display's settings, or the display was replaced - the Status banner shows Unauthorized - clear Auth_Token and reconnect and the Token Display reads Token rejected - clear Auth_Token property. To recover:
Disconnect and clear the stale token
Click File > Disconnect, open the plugin's Properties panel, and delete the contents of the Auth_Token field.
Save to Core & Run
Push the design with an empty Auth_Token. The plugin reconnects without a token, which triggers a fresh pairing prompt on the display.
Approve and capture the new token
Approve the prompt on the display, then copy the new value from the Token Display control.
Save the new token
Click File > Disconnect, paste the new value into the Auth_Token property, and click File > Save to Core & Run again.
08.Power Control
| Control | Function |
|---|---|
| Power Toggle | Sends Wake-on-LAN, waits 2 seconds, then sends KEY_POWER over WebSocket. KEY_POWER is a toggle - not a discrete power-on. See the callout below for behavior in each starting state. Requires MAC_Address for power-on from standby. |
09.Volume Control
| Control | Function |
|---|---|
| Volume Up | Increases display volume by one step |
| Volume Down | Decreases display volume by one step |
| Mute Toggle | Toggles audio mute on/off |
10.Navigation
| Control | Function |
|---|---|
| Up / Down / Left / Right | Navigate in menus |
| Enter | Select/confirm current item |
| Return | Go back to previous menu/screen |
| Menu | Open display's main menu |
11.Input Sources
| Control | Function |
|---|---|
| HDMI | Switch to HDMI input |
| Source | Open input source selection menu |
For direct input selection, use Custom Keys with codes like KEY_HDMI1, KEY_HDMI2, KEY_HDMI3.
12.Custom Keys
Send any Samsung remote control key code for advanced control scenarios.
| Control | Function |
|---|---|
| Custom Key Code | Text input for Samsung key codes |
| Send Custom Key | Sends the entered key code to the display |
Common Key Codes
KEY_HDMI1, KEY_HDMI2, KEY_HDMI3 - Direct HDMI input selection
KEY_TV - Switch to TV tuner
KEY_INFO - Display information overlay
KEY_HOME - Go to home screen
KEY_EXIT - Exit current menu
KEY_CHUP, KEY_CHDOWN - Channel up/down
KEY_0 through KEY_9 - Numeric keys13.Control Pins
All controls are available as pins for integration with Q-SYS scripting and UCIs.
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 |
Power Controls
| Pin Name | Type | Direction |
|---|---|---|
| Power Toggle | Trigger | Both |
Audio and Navigation
| Pin Name | Type | Direction |
|---|---|---|
| Volume Up / Down | Trigger | Both |
| Mute Toggle | Trigger | Both |
| Up / Down / Left / Right | Trigger | Both |
| Enter / Return / Menu | Trigger | Both |
| HDMI / Source | Trigger | Both |
| Custom Key Code | Text | Both |
| Send Custom Key | Trigger | Both |
14.Troubleshooting
Connection Issues
Cannot connect to display
- Verify the IP address is correct and display is powered on
- Ensure WebSocket Remote Control is enabled in display settings
- Check that port 8002 (WSS) or 8001 (WS) is not blocked
- Try toggling
Use_SSLbetween Yes and No - Verify network connectivity (ping the display)
Pairing prompt doesn't appear
- Display may remember previous pairing - try unplugging for 30 seconds
- Verify display model supports WebSocket Remote Control
- Check if another device is already paired/connected
- Try changing
Device_Nameto force new pairing
Token rejected / Unauthorized error
If the Status banner shows Unauthorized - clear Auth_Token and reconnect and the Token Display reads Token rejected - clear Auth_Token property, the saved authentication token is no longer valid. This happens when the display has been factory-reset, the pairing was revoked from the display's settings, or the display was replaced.
To recover, follow the re-pairing procedure in the Display Pairing section. In short: disconnect from the Core, clear the Auth_Token property, Save to Core & Run, approve the new prompt on the display, then disconnect again, paste the new token into Auth_Token, and Save to Core & Run a second time to persist it.
Power Control Issues
Power Toggle doesn't wake display from standby
- Verify
MAC_Addressis correctly entered: 12 hexadecimal characters total. Optional separators (colons, hyphens, dots, spaces) are all accepted and stripped before validation. Examples:AA:BB:CC:DD:EE:FF,AA-BB-CC-DD-EE-FF,AABBCCDDEEFFall work - Check that Wake-on-LAN is enabled in the display's network settings
- WOL packets typically don't traverse routed subnets - Core and display must share a broadcast domain
- Display must be in standby, not unplugged or fully powered off
- The display takes a few seconds to boot after WOL - give it 5-10 seconds before pressing Power Toggle again
License Issues
Activation code doesn't work
- Verify code matches the Core's Locking ID exactly
- Check for typos - format should be
####-####-#### - Codes are Core-specific and cannot be transferred
Debug Output
When the Q-SYS Core debug console is enabled by the integrator, the plugin's startup banner, connection events, and errors are visible there. For deeper diagnostics - including per-frame WebSocket TX/RX traffic - set the Debug_Level property to Verbose. Auth tokens are automatically redacted from verbose logs to keep them out of support captures.
Note: The plugin itself ships with the on-block debug button hidden (ShowDebug = false) so the Properties panel stays clean for end-users. This does not affect logs reaching the Core debug console - it only hides the per-instance debug-window shortcut on the plugin's schematic block.
15.FAQ
Which Samsung displays are compatible?
This plugin is designed for Samsung BE Series commercial displays that support WebSocket Remote Control API. Check your display's specifications to confirm compatibility.
What's the difference between WSS and WS?
WSS (Use_SSL=Yes): Encrypted WebSocket on port 8002. More secure, recommended.
WS (Use_SSL=No): Unencrypted WebSocket on port 8001. Use only if SSL isn't supported.
Can I use one activation code on multiple Cores?
No. Each activation code is tied to a specific Core's Locking ID. Each Core requires its own activation code.
Does the plugin work in Q-SYS Designer emulator?
Yes - the plugin runs in the emulator and the 10-minute demo timer is active there too, which is useful for testing UI layout, pairing flow, and auth-token retrieval.
Important caveat for licensing: in the emulator, System.LockingId returns the literal string "EMULATOR" rather than a real Core's hardware ID. This means activation codes generated against EMULATOR will not validate on real hardware, and codes generated for a real Core will not validate in the emulator. Always generate the activation code using the production Core's actual Locking ID, and only enter it on that Core.
Can I control multiple displays?
Yes - add a separate plugin instance per display. Each Q-SYS Core requires its own activation code; licensing terms for multiple plugin instances on the same Core may vary by purchase. Contact Fresh AV Labs for multi-instance licensing details.
16.Support
Contact Information
Fresh AV Labs
- Website: freshavlabs.com
- Email: support@freshavlabs.com
- License Portal: freshavlabs.com/licenses