summaryrefslogtreecommitdiffstats
path: root/docs/source/usage.rst
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-12-13 21:28:20 -0600
committerEugene Triguba <eugenetriguba@gmail.com>2020-12-13 21:28:20 -0600
commit21d9993eef8c68ad0f6e32ef0c0390202c2a34dd (patch)
tree75d128a78e478041ef13c2289be306d46f2da122 /docs/source/usage.rst
parentIgnore .venv (diff)
parentClarify readme (diff)
downloadlirc-21d9993eef8c68ad0f6e32ef0c0390202c2a34dd.zip
Merge branch 'dev' for 0.2.0 release
Diffstat (limited to 'docs/source/usage.rst')
-rw-r--r--docs/source/usage.rst73
1 files changed, 54 insertions, 19 deletions
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 588d2f7..b007fd0 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -6,33 +6,68 @@ of things you can now import from it to get started.
.. code-block:: python
- from lirc import (
- Lirc,
- LircResponse,
- LircError,
- LircSocketError,
- LircSocketTimeoutError,
- InvalidReplyPacketFormatError
- )
+ from lirc import Client, LircdConnection
-The most relevant of these is ``Lirc``, since this is the main class
-you will be using.
+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
-----------------
-The ``Lirc`` class takes in three separate options, which all have default
-values, that we may pass into it to construct it and override those default
-values.
+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 that depend on the operating
+system you are on. So the simplest way to construct ``Client`` is with no
+arguments at all.
+
+.. code-block:: python
+
+ from lirc import Client
+
+ lirc_client = Client()
+
+Overriding LIRC Defaults on Initialization
+------------------------------------------
-The simplest way to construct ``Lirc`` is with no arguments at all.
+However, if we the defaults don't work for us? 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
- from lirc import Lirc
+ 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
+ )
+ )
+
+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``.
- lirc = Lirc()
+On macOS, it will be almost identical to Linux except that all the paths
+on macOS 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.
-This will attempt to connect to the lircd socket at "/var/run/lirc/lircd" on
-your system, create a socket using ``AF_UNIX`` and ``SOCK_STREAM``, and sets
-a socket timeout of 5 seconds. \ No newline at end of file
+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.