1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
==========
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 <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`_.
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]
[--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 <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
|
