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
|
#####
Usage
#####
Once you've installed the ``lirc`` python package, there will be a number
of things you can now import from it to get started.
.. code-block:: python
from lirc import Client, LircdConnection
The most relevant of these is ``Client``, since this is the main class
you will be using. ``LircdConnection`` is the object that is used to configure
the connection to LIRC when you initialize the ``Client``.
If you want to catch any of the exceptions, those are all under ``lirc.exceptions``.
.. code-block:: python
from lirc.exceptions import (
LircError,
LircdSocketError,
LircdConnectionError,
LircdInvalidReplyPacketError,
LircdCommandFailureError,
UnsupportedOperatingSystemError
)
***********************
Initializing the Client
***********************
.. code-block:: python
import lirc
client = lirc.Client()
print(client.version())
>>> '0.10.1'
To use this package, we instantiate a ``Client``. By initializing it
with no arguments, the ``Client`` will attempt to connect to the lirc
daemon with the default connection parameters for your operating system.
However, if you've instantiated the ``Client`` without any arguments,
you don't get any errors, and you recieve a response from the ``version()``
command, you are connected to the daemon. Most people should not need to
change the default parameters.
Overriding LIRC Defaults on Initialization
==========================================
However, what if we the defaults don't work for us or we have a more complex setup?
Let's say we're on Windows and we want to connect over TCP to a remote LIRC server
on another Windows machine. So we've passed in an ``address`` to override the default
so it doesn't look for the daemon on the localhost. ``socket`` and ``timeout`` are
passed in just to show that we can, these are already the defaults on Windows.
.. code-block:: python
import socket
from lirc import Client, LircdConnection
client = Client(
connection=LircdConnection(
address=("10.16.30.2", 8765),
socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM),
timeout=5.0
)
)
The ``Client`` takes in one optional keyword argument: connection.
This connection must be a ``LircdConnection``. This connection, if not
specified manually, will have default values to connecting to lircd for
the operating system you are using.
The ``address`` specifies how to reach the lircd daemon. On Windows,
we pass a ``(hostname, port)`` tuple since we connect over TCP such as
``('localhost', 8765)``. However on Linux and macOS, we pass in the path
to the socket on the filesystem as a string.
The ``socket`` is the connection type. On Linux/macOS, it will default to a UNIX
domain socket connection. On Windows, ``socket.socket(socket.AF_INET, socket.SOCK_STREAM)``
is used for a connection over TCP.
Lastly, ``timeout`` specifies the amount of time to wait when reading from the socket
for a response.
LIRC Initialization Defaults per Operating System
=================================================
From the options we may pass into the ``LircdConnection``, ``address``
and ``socket`` will change depending on the operating system you are using.
The ``timeout`` always defaults to 5.0 (seconds).
On Linux, this will attempt to connect to the lircd socket at
``/var/run/lirc/lircd`` and create a socket using ``AF_UNIX`` and
``SOCK_STREAM``.
On macOS, it will be almost identical to Linux except that all the paths
will be prefixed by ``/opt/local/`` so the connection to the lircd
socket will instead be at ``/opt/local/var/run/lirc/lircd``. The socket that
is created will be the same.
However if we are on Windows, we can't use unix domain sockets. Instead,
WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string
for the address, it defaults to a tuple of ``("localhost", 8765)``, which is the
default connection parameters for WinLIRC. The first part contains the address
whereas the second is the port. Furthermore, the socket that is created uses
``AF_INET`` and ``SOCK_STREAM`` instead so we can connect over TCP.
****************
Sending IR Codes
****************
In order to send IR signals with our remote, one option we have
is that we can use the ``send_once`` method on the ``lirc.Client``.
.. code-block:: python
import lirc
client = lirc.Client()
client.send_once('our-remote-name', 'key-in-the-remote-file')
Using the ``send_once()`` method is quite simple. For any method,
such as this one, that takes in a remote and a key, the parameters
are always in that order with the remote name first and then the key
name. Because the ``send_once`` method does not get any meaningful data
back from lircd, there is no return value from it. Instead, as is the case
for most methods here that don't have a meaningful return value, a
``lirc.exceptions.LircdCommandFailureError`` is raised if the command we
sent failed.
Furthermore, we can also send the key in rapid succession. This is useful
if we, say, want to go to channel 33.
.. code-block:: python
import lirc
client = lirc.Client()
client.send_once('our-remote-name', 'key_3', repeat_count=1)
We can also send IR codes using ``send_start`` and ``send_stop``.
``send_start`` works in a similar manner to ``send_once``. The
difference is that with ``send_start``, IR codes are continually
sent until a ``send_stop`` call.
.. code-block:: python
import time
import lirc
client = lirc.Client()
client.send_start('our-remote-name', 'key_right')
time.sleep(5)
client.send_stop()
In this example, we see that we can start sending our 'key_right'
signal for 5 seconds and then call ``send_stop`` to stop that. Notice
that we didn't pass any arguments to ``send_stop``. This is because by
default, the ``Client`` will keep track of the last remote name and
remote key that was used with ``send_start``. Optionally, we could of
made it explicit.
.. code-block:: python
client.send_stop('our-remote-name', 'key_right')
This allows you to have multiple ``send_start``s running at the same time,
since you can explicitly pass in which remote and key to stop.
|