samsungctl

by Ape

Remote control Samsung televisions via a TCP/IP connection

453 Stars 157 Forks Last release: Not found MIT License 96 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

==========

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
command to send keys to a TV:

::

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

host
is the hostname or IP address of the TV.
key
is 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 --help
for 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.conf
in this order. A simple default configuration is bundled with the source as
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
can be constructed using the
with
statement:

.. 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 (
legacy
or
websocket
) name string Name of the remote controller. description string Remote controller description. id string Additional remote controller ID. timeout int Timeout in seconds.
0
means no timeout. =========== ====== ===========================================

The

Remote
object 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
control
multiple times using the same
Remote
object. The connection is automatically closed when exiting the
with
statement.

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
is
KEY_POWER
on the newer TVs.

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.