Metadata-Version: 2.1 Name: samsungctl Version: 0.7.1 Summary: Remote control Samsung televisions via TCP/IP connection Home-page: https://github.com/Ape/samsungctl Author: Lauri Niskanen Author-email: ape@ape3000.com License: MIT Classifier: Development Status :: 4 - Beta Classifier: Environment :: Console Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python :: 3 Classifier: Topic :: Home Automation License-File: LICENSE Provides-Extra: interactive_ui Requires-Dist: curses ; extra == 'interactive_ui' Provides-Extra: websocket Requires-Dist: websocket-client ; extra == 'websocket' ========== 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 <(https://pip.pypa.io/>`_: :: # 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 ================= ============ KEY_POWEROFF Power off KEY_UP Up KEY_DOWN Down KEY_LEFT Left KEY_RIGHT Right KEY_CHUP P Up KEY_CHDOWN P Down KEY_ENTER Enter KEY_RETURN Return KEY_CH_LIST Channel List KEY_MENU Menu KEY_SOURCE Source KEY_GUIDE Guide KEY_TOOLS Tools KEY_INFO Info KEY_RED A / Red KEY_GREEN B / Green KEY_YELLOW C / Yellow KEY_BLUE D / Blue KEY_PANNEL_CHDOWN 3D KEY_VOLUP Volume Up KEY_VOLDOWN Volume Down KEY_MUTE Mute KEY_0 0 KEY_1 1 KEY_2 2 KEY_3 3 KEY_4 4 KEY_5 5 KEY_6 6 KEY_7 7 KEY_8 8 KEY_9 9 KEY_DTV TV Source KEY_HDMI HDMI Source KEY_CONTENTS 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