In order for the binding to control your TV, you will be asked to accept the remote connection (from openHAB) on your TV. You have 30 seconds to accept the connection. If you fail to accept it, then most channels will not work.
Once you have accepted the connection, the returned token is stored in the binding, so you don't have to repeat this every time openHAB is restarted.
If the connection has been refused, or you don't have your TV configured to allow remote connections, the binding will not work. If you are having problems, check the settings on your TV, sometimes a family member denies the popup (because they don't know what it is), and after that nothing will work.
Under `advanced`, you can enter a Smartthings PAT, and Device Id. This enables more channels via the Smartthings cloud. This is only for TV's that support Smartthings. No hub is required. The binding will attempt to discover the device ID for your TV automatically, you can enter it manually if automatic detection fails.
Also under `advanced`, you have the ability to turn on *"Subscribe to UPnP events"*. This is off by default. This option reduces (but does not eliminate) the polling of UPnP services. You can enable it if you want to test it out. If you disable this setting (after testing), you should power cycle your TV to remove the old subscriptions.
For >2019 TV's, there is an app workaround, see [App Discovery](#app-discovery) for details.
Some channels do not work on some TV's. It depends on the age of your TV, and what kind of interface it has. Only link channels that work on your TV, polling channels that your TV doesn't have may cause errors, and other problems. see [Tested TV Models](#tested-tv-models).
### keyCode channel:
`keyCode` is a String channel, that emulates a remote control. it allows you to send keys to the TV, as if they were from the remote control, hence it is send only.
This is one of the more useful channels, and several new features have been added in this binding.
Results in a 1 second pause after `KEY_MENU` before `KEY_DOWN` is sent, and a 2 second delay before `KEY_EXIT` is sent. The other commands have 300mS delays between them.
**NOTE:** the delay replaces the 300 mS default delay (so 1000 is 1 second, not 1.3 seconds).
To send keyPresses (like a long press of the power button), you would send:
`"-4000,KEY_POWER"`
This sends a 4 second press of the power button. You can combine these with other commands and delays like this:
`"-3000, KEY_RETURN, 1000, KEY_MENU"`
This does a long press (3 seconds) of the RETURN key (on my TV this exits Netflix or Disney+ etc), then waits 1 second, then exits the menu.
The delimiter is `,`.
By not overlapping, I mean that if you send two strings one after the other, they are executed sequentially. ie:
sending
`"-3000, KEY_RETURN, 100, KEY_MENU"`
immediately followed by:
`"KEY_EXIT"`
would send a long press of return, a 1 second pause, then menu, followed by exit 300mS later.
Spaces are ignored. The supported keys can be listed in the Thing `keyCode` channel
**NOTE:** You have to escape the `"` in the string.
### url
`url` is a String channel, but on later TV's (>2016) it will not fill in the url for you. It will launch the browser, you can then use a rule to read the url (from the channel) and use the `keyCode` channel to enter the URL. Bit of a kludge, but it works.
The `sourceApp` channel will show `Internet` (if configured correctly) and sending `""` to the `sourceapp` channel will exit the browser. You can also send `ON` to the `stopBrowser` channel.
### stopBrowser
`stopbrowser` is a Switch channel. Sending `ON` exits the current app, sending `OFF` sends a long press of the `KEY_EXIT` button (3 seconds).
### Power
The power channel is available on all TV's. Depending on the age of your TV, you may not be able to send power ON commands (see [WOL](#wol)). It should represent the ON state of your TV though.
## Frame TV's
Frame TV's have additional channels.
**NOTE:** If you don't have a Frame TV, don't link the `art` channels, it will confuse the binding, especially power control.
`artMode` is a Switch channel. When `power` is ON, `artMode` will be OFF. If the `artMode` channel is commanded `OFF`, then the TV will power down to standby/off mode (this takes 4 seconds).
Commanding ON to `artMode` will try to power up the TV in art mode, and commanding ON to `power` will try to power the TV up in ON mode, but see WOL limitations.
To determine the ON/ART/OFF state of your TV, you have to read both `power` and `artMode`.
**NOTE:** If you don't have a Frame TV, don't use the `artMode` channel, it will confuse the power handling logic.
### setArtMode:
**NOTE** Samsung added back the art API in Firmware 1622 to >2021 Frame TV's. If you have this version of firmware or higher, don't use the `setArtMode` channel, as it is not neccessary.
`setArtMode` is a Switch channel. Since Samsung removed the art api in 2022, the TV has no way of knowing if it is in art mode or playing a TV source. This switch is to allow you to manually tell the TV what mode it is in.
If you only use the binding to turn the TV on and off or to Standby, the binding will keep track of the TV state. If, however you use the remote to turn the TV on or off from art mode, the binding cannot detect this, and the power state will become invalid.
This input allows you to set the internal art mode state from an external source (say by monitoring the power usage of the TV, or by querying the ex-link port) - thus keeping the power state consistent.
**NOTE:** If you don't have a >2021 Frame TV, don't use the `setArtMode` channel, it will confuse the power handling logic.
### artImage:
`artImage` is an Image channel that receives a thumbnail of the art that would be displayed in artMode (even if the TV is on). It receives iimages only (you can't send a command to it due to openHAB lmitations).
`artlabel` is a String channel that receives the *intenal* lable of the artwork displayed. This will be something like `MY_0010` or `SAM-0123`. `MY` means it's art you uploaded, `SAM` means its from the Samsung art gallery.
You have to figure out what the label actually represents.
You can send commands to the channel. It accepts, Strings, string representations of a `Rawtype` image and `RawType` Images. If you send a String, such as `MY-0013`, it will display that art on the TV. If the TV is ON, playing live TV, then the Tv will switch to artMode.
If you send a `RawType` image, then the image (jpg or png or some other common image format) will be uploaded to the TV, and stored in it's internal storage - if you have space.
The string representation of a `Rawtype` image is of the form `"data:image/png;base64,iVBORw0KGgoAAA........AAElFTkSuQmCC"` where the data is the base64 encoded binary data. the command would look like this:
`artJson` is a String channel that receives the output of the art websocket channel on the TV. You can also send commands to this channel.
If you send a plain text command, the command is wrapped in the required formatting, and sent to the TV artChannel. you can use this feature to send any supported command to the TV, the response will be returned on the same channel.
If you wrap the command with `{``}`, then the whole string is treated as a json command, and sent as-is to the channel (basic required fields will be added).
Currently known working commands for 2021 and earlier TV's are:
set_auto_rotation_status "type" is "slideshow" pr 'shuffelslideshow", "value" is off or duration in minutes "category_id" is a string representing the category
get_device_info
get_content_list
get_current_artwork
get_thumbnail - downloads thumbnail in same format as uploaded
send_image - uploads image jpg/png etc
delete_image_list - list in "content_id"
select_image - selects image to display (display optional) image label in "content_id", "show" true or false
get_photo_filter_list
set_photo_filter
get_matte_list
set_matte
get_motion_timer (and set) valid values: "off","5","15","30","60","120","240", send settiing in "value"
get_motion_sensitivity (and set) min 1 max 3 set in "value"
get_color_temperature (and set) min -5 max +5 set in "value"
get_brightness (and set) min 1 max 10 set in "value"
get_brightness_sensor_setting (and set) on or off in "value"
```
Currently known working commands for 2022 and later TV's are:
set_slideshow_status "type" is "slideshow" pr 'shuffelslideshow", "value" is off or duration in minutes "category_id" is a string representing the category
get_device_info
get_content_list
get_current_artwork
get_thumbnail_list - downloads list of thumbnails in same format as uploaded
send_image - uploads image jpg/png etc
delete_image_list - list in "content_id"
select_image - selects image to display (display optional) image label in "content_id", "show" true or false
get_photo_filter_list
set_photo_filter
get_matte_list
set_matte
get_artmode_settings - returns the below values
set_motion_timer valid values: "off","5","15","30","60","120","240", send settiing in "value"
set_motion_sensitivity min 1 max 3 set in "value"
set_color_temperature min -5 max +5 set in "value"
set_brightness min 1 max 10 set in "value"
set_brightness_sensor_setting on or off in "value"
```
Some of these commands are quite complex, so I don't reccomend using them eg `get_thumbnail`, `get_thumbnail_list` and `send_image`.
Some are simple, so to get the list of art currently on your TV, just send:
```java
TV_ArtJson.sendCommand("get_content_list")
```
To set the current artwork, but not display it, you would send:
`artBrightness` is a dimmer channel that sets the brightness of the art in ArtMode. It does not affect the TV brightness. Normally the brightness of the artwork is controlled automatically, and the current value is polled and reported via this channel.
`artColorTemperature` is a Number channel, it reports the "warmth" of the artwork from -5 to 5 (default 0). It's not polled, but is updated when artmode status is updated.
`artOrientation` is a Switch channel, it reports the current orientation of the TV, OFF for Landscape, and ON for Portrait. This channel is polled. If you send an ON or OFF command to this channel, then the binding will send a long (4s) press of the key defined in the configuration for orientationKey.
For 2023- TV's `orientationKey` should be KEY_MULTI_VIEW (default), for 2024+ TV's this should be KEY_HOME.
The `sourceApp` channel is a string channel, it displays the name of the current app, `artMode` or `slideshow` if the TV is in artMode, or blank for regular TV.
To discover all installed apps names, you can enable the DEBUG log output from the binding to see a list of apps that have been discovered as installed. This list is displayed once, shortly after the TV is turned On.
If you have a TV >2019, then the list of apps will not be discovered. Instead, a default list of known appID's is built into the binding, these cover most common apps. The binding will attempt to discover these apps, and, if you are lucky, your app will be found and you have nothing further to do. It is possible that new apps have been added, or are specific to your country that are not in the built in list, in which case you can add these apps manually.
If the app you need is not discovered, a file `samsungtv.cfg` will need to be be created in the openHAB config services directory (`/etc/openhab/services/` for Linux systems).
You need to edit the file `samsungtv.cfg`, and add in the name, appID, and type of the apps you have installed on your TV. Here is a sample for the contents of the `samsungtv.cfg` file:
```java
# This file is for the samsungtv binding
# It contains a list in json format of apps that can be run on the TV
# It is provided for TV >2020 when the api that returns a list of installed apps was removed
Enter this into the `samsungtv.cfg` file and save it. The file contents are read automatically every time the file is updated. The binding will check to see if the app is installed, and start polling the status every 10 seconds (or more if your refresh interval is set higher).
Apps that are not installed are deleted from the list (internally, the file is not updated). If you install an app on the TV, which is not in the built in list, you have to update the file with it's appID, or at least touch the file for the new app to be registered with the binding.
The entry for `Internet` is important, as this is the TV web browser App. on older TV's it's `org.tizen.browser`, but this is not correct on later TV's (>2019). This is the app used for the `url` channel, so it needs to be set correctly if you use this channel.
`org.tizen.browser` is the internal default, and does launch the browser on all TV's, but on later TV's this is just an alias for the actual app, so the `sourceApp` channel will not be updated correctly unless the correct appID is entered here. The built in list has the correct current appID for the browser, but if it changes or is incorrect for your TV, you can update it here.
You can use any name you want in this list, as long as the appID is valid. The binding will then allow you to launch the app using your name, the official name, or the appID.
In order to be able to control the TV input (HDMI1, HDMI2 etc), you have to link the binding to the smartthngs API, as there is no local control capable of switching the TV input.
The binding will attempt to find the Device ID for your TV. If you have several TV’s of the same type, you will have to manually identify the Device ID for the current Thing from the logs. The device ID should look something like 996ff19f-d12b-4c5d-1989-6768a7ad6271. If you have only one TV of each type, Device ID should get filled in for you.
You can now link the `sourceName`, `sourceId`, `channel` and `channelName` channels, and should see the values updating. You can change the TV input source by sending `"HDMI1"`, or `"HDMI2"` to the `sourceName` channel, the exact string will depend on your TV, and how many inputs you have. You can also send a number to the `sourceId` channel.
**NOTE:** You may not get anything for `channelName`, as most TV’s don’t report it. You can only send commands to `channel`, `sourceName` and `sourceId`, `channelName` is read only.
Smartthings Subscriptions are supported. This is a feature which reduces the polling of Smartthings channels (on by default).
If the Smarthings channels only update with the Smartthings app open, turn subscription off, and the channels will be polled instead. Channels are only polled when the TV is ON.
Because Samsung does not publish any documentation about the TV's UPnP interface, there could be differences between different TV models, which could lead to mismatch problems.
Tested TV models (but this table may be out of date):
If you enable the Smartthings interface, this adds back the `sourceName`, `sourceId`, `programTitle` and `channelName` channels on >2016 TV's
Samsung removed the app API support in >2019 TV's, if your TV is >2019, see the section on [Apps](#apps).
Samsung removed the art API support in >2021 TV's, if your Frame TV is >2021, see the section on [setArtMode](#setartmode).
Samsung re-introduced the art API in firmware 1622 for >2021 Frame TV's. if you have ths version, art channels will work correctly.
**NOTE:** `brightness`, `contrast`, `colorTemperature` and `sharpness` channels only work on legacy interface TV's (<2016).
## Troubleshooting
On legacy TV's, you may see an error like this:
```
2021-12-08 12:19:50.262 [DEBUG] [port.upnp.internal.UpnpIOServiceImpl] - Error reading SOAP response message. Can't transform message payload: org.jupnp.model.action.ActionException: The argument value is invalid. Invalid number of input or output arguments in XML message, expected 2 but found 1.
This is not an actual error, but is what is returned when a value is polled that does not yet exist, such as the URL for the TV browser, when the browser isn’t running. These messages are not new, and can be ignored. Enabling `subscription` will eliminate them.
The `getSupportedChannelNames` messages are not UPnP services, they are not actually services that are supported *by your TV* at all. They are the internal capabilities of whatever method is being used for communication (which could be direct port connection, UPnP or websocket).
They also do not reflect the actual capabilities of your TV, just what that method supports, on your TV, they may do nothing.
You should get `volume` and `mute` channels working at the minnimum. Other channels may or may not work, depending on your TV and the binding configuration.
If you see errors that say `no route to host` or similar things, it means your TV is off. The binding cannot discover, control or poll a TV that is off.
For the binding to function properly it is very important that your network config allows the machine running openHAB to receive UPnP multicast traffic.
Multicast traffic is not propogated between different subnets, or VLANS, unless you specifically configure your router to do this. Many switches have IGMP Snooping enabled by default, which filters out multicast traffic.
If you want to check the communication between the machine and the TV is working, you can try the following:
### Check if your Linux machine receives multicast traffic
**With your TV OFF (ie totally off)**
- Login to the Linux console of your openHAB machine.
- make sure you have __netcat__ installed
- Enter `netcat -ukl 1900` or `netcat -ukl -p 1900` depending on your version of Linux
### Check if your Windows/Mac machine receives multicast traffic
**With your TV OFF (ie totally off)**
- Download Wireshark on your openHAB machine
- Start and select the network interface which is connected to the same network as the TV
- Filter for the multicast messages with the expression `udp.dstport == 1900 && data.text` if you have "Show data as text" enabled, otherwise just filter for `udp.dstport == 1900`
### What you should see
You may see some messages (this is a good thing, it means you are receiving UPnP traffic).
Now turn your TV ON (with the remote control).
You should see several messages like the following:
Where the ip address in `LOCATION` is the ip address of your TV, and the `USN` varies. `MediaRenderer` is the most important service, as this is what the binding uses to detect if your TV is online/turned On or not.
If you now turn your TV off, you will see similar messages, but with `NTS: ssdp:byebye`. This is how the binding detects that your TV has turned OFF.
Try this several times over a period of 30 minutes after you have discovered the TV and added the binding. This is because when you discover the binding, a UPnP `M-SEARCH` packet is broadcast, which will enable mulicast traffic, but your network (router or switches) can eventually start filtering out multicast traffic, leading to unrealiable behaviour.
If you see these messages, then basic communications is working, and you should be able to turn your TV Off (and on later TV's) ON, and have the status reported correctly.
### Multiple network interfaces
If you have more than one network interface on your openHAB machine, you may have to change the `Network` setings in the openHAB control panel. Make sure the `Primary Address` is selected correctly (The same subnet as your TV is connected to).
### I'm not seeing any messages, or not Reliably
- Most likely your machine is not receiving multicast messages
- Check your network config:
- Routers often block multicast - enable it.
- Make sure the openHAB machine and the TV are in the same subnet/VLAN.
- disable `IGMP Snooping` if it is enabled on your switches.
- enable/disable `Enable multicast enhancement (IGMPv3)` if you have it (sometimes this helps).
- Try to connect your openHAB machine or TV via Ethernet instead of WiFi (AP's can filter Multicasts).
- Make sure you don't have any firewall rules blocking multicast.
- if you are using a Docker container, ensure you use the `--net=host` setting, as Docker filters multicast broadcasts by default.
### I see the messages, but something else is not working properly
There are several other common issues that you can check for:
- Your TV is not supported. H (2014) and J (2015) TV's are not supported, as they have an encrypted interface.
- You are trying to discover a TV that is OFF (some TV's have a timeout, and turn off automatically).
- Remote control is not enabled on your TV. You have to specifically enable IP control and WOL on the TV.
- You have not accepted the request to allow remote control on your TV, or, you denied the request previously.
- You have selected an invalid combination of protocol and port in the binding.
- The binding will attempt to auto configure the correct protocol and port on discovery, but you can change this later to an invalid configuration, eg:
- Protocol None is not valid
- Protocol Legacy will not work on >2016 TV's
- Protocol websocket only works with port 8001
- Protocol websocketsecure only works with port 8002. If your TV supports websocketsecure on port 8002, you *must* use it, or many things will not work.
- The channel you are trying to use is not supported on your TV.
- Only some channels are supported on different TV's
- Some channels require additional configuration on >2016 TV's. eg `SmartThings` configuration, or Apps confguration.
- Some channels are read only on certain TV's
- I can't turn my TV ON.
- Older TV's (<2016)donotsupporttuningON
- WOL is not enabled on your TV (you have to specifically enable it)
- You have a soundbar connected to your TV and are connected using wired Ethernet.
- The MAC address in the binding configuratiion is blank/wrong.
- You have to wait up to 60 seconds after turning OFF, before you can turn back ON (This is a Samsung feature called "instant on")
- My TV asks me to accept the connection every time I turn the TV on
- You have the TV set to "Always Ask" for external connections. You need to set it to "Only ask the First Time". To get to the Device Manager, press the home button on your TV remote and navigate to Settings → General → External Device Manager → Device Connect Manager and change the setting.
- You are using a text `.things` file entry for the TV `thing`, and you haven't entered the `webSocketToken` in the text file definition. The token is shown on the binding config page. See [Binding Configuration](#binding-configuration).
