Remote control Samsung televisions via a TCP/IP connection
==========
samsungctl is a library and a command line tool for remote controlling Samsung televisions via a TCP/IP connection. It currently supports both pre-2016 TVs as well most of the modern Tizen-OS TVs with Ethernet or Wi-Fi connectivity.
websocket-client(optional, for 2016+ TVs)
curses(optional, for the interactive mode)
samsungctl can be installed using
pip_:
::
# pip install samsungctl
Alternatively you can clone the Git repository and run:
::
# python setup.py install
It's possible to use the command line tool without installation:
::
$ python -m samsungctl
You can use
samsungctlcommand to send keys to a TV:
::
$ samsungctl --host [options] [key ...]
hostis the hostname or IP address of the TV.
keyis a key code, e.g.
KEY_VOLDOWN. See
Key codes_.
There is also an interactive mode (ncurses) for sending the key presses:
::
$ samsungctl --host [options] --interactive
Use
samsungctl --helpfor more information about the command line arguments:
::
usage: samsungctl [-h] [--version] [-v] [-q] [-i] [--host HOST] [--port PORT] [--method METHOD] [--name NAME] [--description DESC] [--id ID] [--timeout TIMEOUT] [key [key ...]]Remote control Samsung televisions via TCP/IP connection
positional arguments: key keys to be sent (e.g. KEY_VOLDOWN)
optional arguments: -h, --help show this help message and exit --version show program's version number and exit -v, --verbose increase output verbosity -q, --quiet suppress non-fatal output -i, --interactive interactive control --host HOST TV hostname or IP address --port PORT TV port number (TCP) --method METHOD Connection method (legacy or websocket) --name NAME remote control name --description DESC remote control description --id ID remote control id --timeout TIMEOUT socket timeout in seconds (0 = no timeout)
E.g. samsungctl --host 192.168.0.10 --name myremote KEY_VOLDOWN
The settings can be loaded from a configuration file. The file is searched from
$XDG_CONFIG_HOME/samsungctl.conf,
~/.config/samsungctl.conf, and
/etc/samsungctl.confin this order. A simple default configuration is bundled with the source as
samsungctl.conf_.
samsungctl can be imported as a Python 3 library:
.. code-block:: python
import samsungctl
A context managed remote controller object of class
Remotecan be constructed using the
withstatement:
.. code-block:: python
with samsungctl.Remote(config) as remote: # Use the remote object
The constructor takes a configuration dictionary as a parameter. All configuration items must be specified.
=========== ====== =========================================== Key Type Description =========== ====== =========================================== host string Hostname or IP address of the TV. port int TCP port number. (Default:
55000) method string Connection method (
legacyor
websocket) name string Name of the remote controller. description string Remote controller description. id string Additional remote controller ID. timeout int Timeout in seconds.
0means no timeout. =========== ====== ===========================================
The
Remoteobject is very simple and you only need the
control(key)method. The only parameter is a string naming the key to be sent (e.g.
KEY_VOLDOWN). See
Key codes_. You can call
controlmultiple times using the same
Remoteobject. The connection is automatically closed when exiting the
withstatement.
When something goes wrong you will receive an exception:
================= ======================================= Exception Description ================= ======================================= AccessDenied The TV does not allow you to send keys. ConnectionClosed The connection was closed. UnhandledResponse An unexpected response was received. socket.timeout The connection timed out. ================= =======================================
This simple program opens and closes the menu a few times.
.. code-block:: python
#!/usr/bin/env python3import samsungctl import time
config = { "name": "samsungctl", "description": "PC", "id": "", "host": "192.168.0.10", "port": 55000, "method": "legacy", "timeout": 0, }
with samsungctl.Remote(config) as remote: for i in range(10): remote.control("KEY_MENU") time.sleep(0.5)
The list of accepted keys may vary depending on the TV model, but the following list has some common key codes and their descriptions.
================= ============ Key code Description ================= ============ KEYPOWEROFF Power off KEYUP Up KEYDOWN Down KEYLEFT Left KEYRIGHT Right KEYCHUP P Up KEYCHDOWN P Down KEYENTER Enter KEYRETURN Return KEYCHLIST Channel List KEYMENU Menu KEYSOURCE Source KEYGUIDE Guide KEYTOOLS Tools KEYINFO Info KEYRED A / Red KEYGREEN B / Green KEYYELLOW C / Yellow KEYBLUE D / Blue KEYPANNELCHDOWN 3D KEYVOLUP Volume Up KEYVOLDOWN Volume Down KEYMUTE Mute KEY0 0 KEY1 1 KEY2 2 KEY3 3 KEY4 4 KEY5 5 KEY6 6 KEY7 7 KEY8 8 KEY9 9 KEYDTV TV Source KEYHDMI HDMI Source KEYCONTENTS SmartHub ================= ============
Please note that some codes are different on the 2016+ TVs. For example,
KEY_POWEROFFis
KEY_POWERon the newer TVs.
I did not reverse engineer the control protocol myself and samsungctl is not the only implementation. Here is the list of things that inspired samsungctl.