summaryrefslogtreecommitdiffstats
path: root/docs/source/usage.rst
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2021-04-18 18:47:57 -0500
committerEugene Triguba <eugenetriguba@gmail.com>2021-04-18 18:47:57 -0500
commitb400aba3f82eb7a490bdbc8d141777e82d625ac8 (patch)
tree98ff11d0da726cefcfee455dbcffdc9a8ed23959 /docs/source/usage.rst
parentAdd note to customizing client (diff)
downloadlirc-b400aba3f82eb7a490bdbc8d141777e82d625ac8.zip
Update docs
Diffstat (limited to '')
-rw-r--r--docs/source/usage.rst120
1 files changed, 95 insertions, 25 deletions
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 9b2fee9..118a307 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -13,26 +13,46 @@ 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``.
-*****************
-Initializing Lirc
-*****************
+If you want to catch any of the exceptions, those are all under ``lirc.exceptions``.
-The ``Client`` class 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. So the simplest way to construct ``Client``
-is with no arguments at all.
+.. code-block:: python
+
+ from lirc.exceptions import (
+ LircError,
+ LircdSocketError,
+ LircdConnectionError,
+ LircdInvalidReplyPacketError,
+ LircdCommandFailureError,
+ UnsupportedOperatingSystemError
+ )
+
+***********************
+Initializing the Client
+***********************
.. code-block:: python
- from lirc import Client
+ import lirc
+
+ client = lirc.Client()
+
+ print(client.version())
+ >>> '0.10.1'
- lirc_client = Client()
+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, if we the defaults don't work for us or we have a more complex setup?
+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
@@ -51,6 +71,23 @@ passed in just to show that we can, these are already the defaults on Windows.
)
)
+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
=================================================
@@ -69,17 +106,17 @@ 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 on 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.
+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, we can use the ``send_once`` method on
-the ``lirc.Client``.
+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
@@ -88,17 +125,50 @@ the ``lirc.Client``.
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.
+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.
+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. \ No newline at end of file