==========

samsungctl

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.

Dependencies

• Python 3

• websocket-client

  (optional, for 2016+ TVs)

• curses

  (optional, for the interactive mode)

Installation

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

Command line usage

You can use

samsungctl

::

$ samsungctl --host  [options]  [key ...]

host

key

KEY_VOLDOWN

Key codes

There is also an interactive mode (ncurses) for sending the key presses:

::

$ samsungctl --host  [options] --interactive

Use

samsungctl --help

::

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

/etc/samsungctl.conf

samsungctl.conf 

Library usage

samsungctl can be imported as a Python 3 library:

.. code-block:: python

import samsungctl

A context managed remote controller object of class

Remote

with

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

legacy

websocket

0

The

Remote

control(key)

KEY_VOLDOWN

Key codes

control

Remote

with

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

Example program

This simple program opens and closes the menu a few times.

.. code-block:: python

#!/usr/bin/env python3

import 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)

Key codes

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_POWEROFF

KEY_POWER

References

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.

• http://sc0ty.pl/2012/02/samsung-tv-network-remote-control-protocol/
• https://gist.github.com/danielfaust/998441
• https://github.com/Bntdumas/SamsungIPRemote
• https://github.com/kyleaa/homebridge-samsungtv2016