skip to navigation
skip to content

samsungctl 0.6.0

Remote control Samsung televisions via TCP/IP connection

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)

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 <host> [options] <key> [key ...]

`host` is the hostname or IP address of the TV. `key` is a key code, e.g.
`KEY_VOLDOWN`. See [Key codes](#key-codes).

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

$ samsungctl --host <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]
[--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](samsungctl.conf).

Library usage
-------------

samsungctl can be imported as a Python 3 library:

```python
import samsungctl
```

A context managed remote controller object of class `Remote` can be constructed
using the `with` statement:

```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](#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.

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

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  
File Type Py Version Uploaded on Size
samsungctl-0.6.0.tar.gz (md5) Source 2016-12-31 8KB