diff options
| author | Eugene Triguba <eugenetriguba@gmail.com> | 2020-12-13 21:28:20 -0600 |
|---|---|---|
| committer | Eugene Triguba <eugenetriguba@gmail.com> | 2020-12-13 21:28:20 -0600 |
| commit | 21d9993eef8c68ad0f6e32ef0c0390202c2a34dd (patch) | |
| tree | 75d128a78e478041ef13c2289be306d46f2da122 /docs | |
| parent | Ignore .venv (diff) | |
| parent | Clarify readme (diff) | |
| download | lirc-21d9993eef8c68ad0f6e32ef0c0390202c2a34dd.zip | |
Merge branch 'dev' for 0.2.0 release
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/conf.py | 6 | ||||
| -rw-r--r-- | docs/source/configuring-system-lirc.rst | 7 | ||||
| -rw-r--r-- | docs/source/installation.rst | 13 | ||||
| -rw-r--r-- | docs/source/usage.rst | 73 |
4 files changed, 70 insertions, 29 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py index cd10b4c..1c5552c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -31,7 +31,11 @@ release = "0.1.0" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel"] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.napoleon", +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/configuring-system-lirc.rst b/docs/source/configuring-system-lirc.rst index 5c9d829..5122804 100644 --- a/docs/source/configuring-system-lirc.rst +++ b/docs/source/configuring-system-lirc.rst @@ -50,7 +50,12 @@ the device should just work on the default driver. Windows ------- -The Windows setup information is a work in progress. +You'll want to make sure you install WinLIRC at http://winlirc.sourceforge.net/. +This is the LIRC port for Windows which corresponds with version 0.9.0 of LIRC. Past that, +you can run the WinLIRC executable file and select the "Input Plugin" for your device. Then, +you can select the remote configuration and click OK. You should now be able to select your remote +and send key codes. As long as the program is running in the background (it minimizes to the tray), +this package will be able to connect to it. macOS ----- diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 3f74864..e8255de 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -19,9 +19,9 @@ through pip. System LIRC Package ------------------- -While there are ports of LIRC to macOS and Windows, -the original Linux version is generally easier to -get working and install. +While LIRC was originally created for Linux, there +are ports of LIRC to macOS and Windows which this +python package is compatibile with. Linux: @@ -36,8 +36,7 @@ Windows: * WinLIRC at 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 so you'll have to adjust the ``socket`` - and ``socket_path`` parameter. More information on that can be found + in a folder that you run. More information on that can be found at `using LIRC on Windows <./using-lirc-on-windows.html>`_. macOS: @@ -46,6 +45,4 @@ macOS: with it's source code on GitHub at 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. See - `using LIRC on macOS <./using-lirc-on-macos.html>`_ for more information on - getting LIRC setup on macOS and how to use this python package with it.
\ No newline at end of file + 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 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. |