summaryrefslogtreecommitdiffstats
path: root/docs
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
parentAdd note to customizing client (diff)
downloadlirc-b400aba3f82eb7a490bdbc8d141777e82d625ac8.zip
Update docs
Diffstat (limited to '')
-rw-r--r--docs/source/configuring-system-lirc.rst10
-rw-r--r--docs/source/hardware-setup.rst7
-rw-r--r--docs/source/installation.rst14
-rw-r--r--docs/source/usage.rst120
4 files changed, 114 insertions, 37 deletions
diff --git a/docs/source/configuring-system-lirc.rst b/docs/source/configuring-system-lirc.rst
index 5122804..6527344 100644
--- a/docs/source/configuring-system-lirc.rst
+++ b/docs/source/configuring-system-lirc.rst
@@ -40,7 +40,11 @@ the remote configuration file. The RedRat3-II is now discontinued, although
`its driver's are still available <https://www.redrat.co.uk/support/firmware-drivers/>`_, but you
could look into the `RedRatX <https://www.redrat.co.uk/products/redrat-x/>`_ or see if you can
find a `RedRat3-II used <https://www.ebay.com/sch/i.html?_nkw=redrat3-ii&_sacat=0>`_. Place this
-generated remote configuration file in your ``lircd.conf.d`` folder.
+generated remote configuration file in your ``/etc/lirc/lircd.conf.d`` folder.
+
+*******************************
+Iguanaworks IR Transciever Note
+*******************************
If you're using an Iguanaworks IR Transciever, you may find the discussion below useful. Basically,
the device should just work on the default driver.
@@ -61,8 +65,8 @@ macOS
-----
On macOS, the paths are almost the same as the Linux ones, just prefixed with ``/opt/local/``.
-Therefore, the LIRC configuration is typically at ``/opt/local/etc/lirc/`` and the lircd socket
-is at ``/opt/local/var/run/lirc/lircd``
+Therefore, the LIRC configuration is typically at ``/opt/local/etc/lirc/`` and the lircd
+socket is at ``/opt/local/var/run/lirc/lircd``.
Refer to the Linux section for the rest of the configuration as they are almost the same besides
the ``/opt/local/`` prefix. However, on macOS, there is also no ``default`` driver like there is
diff --git a/docs/source/hardware-setup.rst b/docs/source/hardware-setup.rst
index 27bb489..ef3a3e4 100644
--- a/docs/source/hardware-setup.rst
+++ b/docs/source/hardware-setup.rst
@@ -1,5 +1,8 @@
Hardware Setup
==============
-In order to use this package, you'll need to have an IR emitter
-or transciever hooked up to your computer. \ No newline at end of file
+This package will work as long as you have a lirc daemon running. You can use
+the ``version()`` method on the ``Client`` and see what version of the lirc
+daemon is running. However, in order to do anything useful (such as sending
+IR codes), you'll need to have an IR emitter or transciever hooked up to your
+computer and recognized by lirc. \ No newline at end of file
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index e8255de..e6eec34 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -34,15 +34,15 @@ Linux:
Windows:
- * WinLIRC at http://winlirc.sourceforge.net/ is a port for Windows.
+ * `WinLIRC <http://winlirc.sourceforge.net/>`_ is a port for Windows.
It works a bit differently since it is just a collection of files
- in a folder that you run. More information on that can be found
- at `using LIRC on Windows <./using-lirc-on-windows.html>`_.
+ in a folder that you run. More information on setting up WinLIRC can be found
+ at `configuring the system LIRC <./configuring-system-lirc.html>`_.
macOS:
- * There is a port on MacPorts at https://ports.macports.org/port/lirc/summary
- with it's source code on GitHub at https://github.com/andyvand/LIRC. However,
+ * There is `a port on MacPorts <https://ports.macports.org/port/lirc/summary>`_
+ with it's `source code on GitHub <https://github.com/andyvand/LIRC>`_. However,
it doesn't appear to be maintained any longer and is not the latest LIRC version.
- You can then run ``port install lirc`` or build the package from source using
- the instructions on the README of the GitHub repository. \ No newline at end of file
+ You can still install it using ``port install lirc`` or build the package from
+ source using the instructions on the README of the GitHub repository. \ No newline at end of file
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