summaryrefslogtreecommitdiffstats
path: root/docs/source/usage.rst
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-07-15 23:08:11 -0500
committerEugene Triguba <eugenetriguba@gmail.com>2020-07-15 23:08:11 -0500
commit705a84f5b8908b462a0c0c98b64d5d111ec20d17 (patch)
treeff58948fd2b3f6b287dc0c36e170e0159b3c3430 /docs/source/usage.rst
parentRun CI on macos, windows, and ubuntu (diff)
downloadlirc-705a84f5b8908b462a0c0c98b64d5d111ec20d17.zip
Change how address and socket are determined in Lirc
This is to help with making this package cross-platform.
Diffstat (limited to 'docs/source/usage.rst')
-rw-r--r--docs/source/usage.rst57
1 files changed, 48 insertions, 9 deletions
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 588d2f7..ef9aa96 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -16,16 +16,16 @@ of things you can now import from it to get started.
)
The most relevant of these is ``Lirc``, since this is the main class
-you will be using.
+you will be using. ``LircResponse`` is the response object that is returned
+when you send a command. All the others are just errors.
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 simplest way to construct ``Lirc`` is with no arguments at all.
+The ``Lirc`` class takes in three separate options: ``address``, ``socket``,
+and ``timeout``. These all have default values that depend on the operating
+system you are on. So the simplest way to construct ``Lirc`` is with no
+arguments at all.
.. code-block:: python
@@ -33,6 +33,45 @@ The simplest way to construct ``Lirc`` is with no arguments at all.
lirc = Lirc()
-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
+Overriding LIRC Defaults on Initialization
+------------------------------------------
+
+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
+
+ import socket
+ from lirc import Lirc
+
+ lirc = Lirc(
+ address=("10.16.30.2", 8765),
+ socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM),
+ timeout=5
+ )
+
+LIRC Initialization Defaults per Operating System
+-----------------------------------------------
+
+From the options we may pass into ``Lirc``, ``address`` and ``socket`` will
+change depending on the operating system you are using. The ``timeout`` always
+defaults to 5 (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
+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.
+
+However if we are on Windows, we can't use unix domain sockets. So 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), 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 now.